lmiranda/job-forge
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Major documentation overhaul: Transform to Python/FastAPI web application

Browse Source 
This comprehensive update transforms Job Forge from a generic MVP concept to a
production-ready Python/FastAPI web application prototype with complete documentation,
testing infrastructure, and deployment procedures.

## 🏗️ Architecture Changes
- Updated all documentation to reflect Python/FastAPI + Dash + PostgreSQL stack
- Transformed from MVP concept to deployable web application prototype
- Added comprehensive multi-tenant architecture with Row Level Security (RLS)
- Integrated Claude API and OpenAI API for AI-powered document generation

## 📚 Documentation Overhaul
- **CLAUDE.md**: Complete rewrite as project orchestrator for 4 specialized agents
- **README.md**: New centralized documentation hub with organized navigation
- **API Specification**: Updated with comprehensive FastAPI endpoint documentation
- **Database Design**: Enhanced schema with RLS policies and performance optimization
- **Architecture Guide**: Transformed to web application focus with deployment strategy

## 🏗️ New Documentation Structure
- **docs/development/**: Python/FastAPI coding standards and development guidelines
- **docs/infrastructure/**: Docker setup and server deployment procedures
- **docs/testing/**: Comprehensive QA procedures with pytest integration
- **docs/ai/**: AI prompt templates and examples (preserved from original)

## 🎯 Team Structure Updates
- **.claude/agents/**: 4 new Python/FastAPI specialized agents
  - simplified_technical_lead.md: Architecture and technical guidance
  - fullstack_developer.md: FastAPI backend + Dash frontend implementation
  - simplified_qa.md: pytest testing and quality assurance
  - simplified_devops.md: Docker deployment and server infrastructure

## 🧪 Testing Infrastructure
- **pytest.ini**: Complete pytest configuration with coverage requirements
- **tests/conftest.py**: Comprehensive test fixtures and database setup
- **tests/unit/**: Example unit tests for auth and application services
- **tests/integration/**: API integration test examples
- Support for async testing, AI service mocking, and database testing

## 🧹 Cleanup
- Removed 9 duplicate/outdated documentation files
- Eliminated conflicting technology references (Node.js/TypeScript)
- Consolidated overlapping content into comprehensive guides
- Cleaned up project structure for professional development workflow

## 🚀 Production Ready Features
- Docker containerization for development and production
- Server deployment procedures for prototype hosting
- Security best practices with JWT authentication and RLS
- Performance optimization with database indexing and caching
- Comprehensive testing strategy with quality gates

This update establishes Job Forge as a professional Python/FastAPI web application
prototype ready for development and deployment.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2025-08-02 11:33:32 -04:00
parent d9a8b13c16
commit b646e2f5df
41 changed files with 10237 additions and 5499 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/ai/dillon_cover_letter.md Normal file
View File

@@ -0,0 +1,23 @@
**Leo Miranda**
leobrmi@hotmail.com | (416) 859-7936
July 21, 2025
Dillon Consulting
Data Analyst Hiring Team
Toronto, ON
Dear Hiring Manager,
I'm writing to apply for the Data Analyst position at Dillon Consulting. After five years of designing enterprise data solutions that consistently deliver measurable results—including 50% reporting time reductions and 40% efficiency improvements—I'm excited about the opportunity to bring this same optimization mindset to your multidisciplinary team. Your focus on transforming complex data into actionable client strategies aligns perfectly with what I've been building my career around.
Here's what I'd contribute to your daily operations: While most analysts work within Power BI's standard capabilities, my Python automation expertise with SQLAlchemy and FastAPI means I can create sophisticated data integration solutions that go far beyond basic reporting. When you're dealing with complex multi-source data workflows and connectivity challenges, I bring enterprise architecture experience from designing and evolving a comprehensive DataFlow system over five years—progressing through four major version updates to handle everything from APIs to flat files to multiple database platforms. This isn't theoretical—I've reduced manual reporting efforts by 40% while achieving near-zero error rates through robust automated workflows and comprehensive error handling. Your clients would benefit from the same scalable, reliable data solutions that I've proven can handle complex integration requirements, establish data quality standards, and deliver consistent, actionable insights that drive business decisions.
What sets me apart is how I bridge technical depth with business impact. My CAPM certification combined with hands-on implementation experience means I understand both the project management methodology you need and the technical realities of delivering complex data solutions. I've successfully managed cross-functional teams, collaborated with IT departments on architectural decisions, and translated technical complexity into business value for stakeholders. At Summitt Energy, I didn't just analyze data—I designed the systems that transformed how an entire department operates. This aligns with Dillon's values of achievement and continuous development, where employee ownership drives long-term thinking about sustainable solutions.
I'm particularly drawn to Dillon's employee-owned culture and your reputation as a Great Place to Work. Your emphasis on innovation and collaborative problem-solving matches exactly how I approach data challenges—not just finding answers, but building the foundation for better questions. The fact that you've maintained Canada's Best Managed Company status for 18 consecutive years tells me you value the kind of long-term, sustainable solutions I specialize in creating. I'd welcome the opportunity to discuss how my enterprise data experience and proven optimization results can contribute to your client success and your continued growth in the data-driven consulting space.
Thank you for your consideration. I'm available for an interview at your convenience and look forward to hearing from you.
Sincerely,
Leo Miranda

407
docs/ai/dillon_research_report.md Normal file
View File

@@ -0,0 +1,407 @@
# Job Application Research Report
## Executive Summary
**Candidate:** Leo Miranda
**Target Role:** Data Analyst
**Company:** Dillon Consulting
**Analysis Date:** July 21, 2025
**Overall Fit Score:** 9/10
**Recommendation:** Proceed - Excellent Fit
**Key Takeaways:**
- **Primary Strength:** 5+ years data analysis experience with proven dashboard/Power BI expertise perfectly aligns with requirements
- **Unique Value Proposition:** Rare combination of technical depth (Python, SQL) + project management + consulting mindset + client-facing experience
- **Strategic Focus:** Position as senior technical leader who can drive full project lifecycle and stakeholder collaboration
- **Potential Challenge:** Limited formal GIS experience, but strong technical foundation enables rapid skill transfer
---
## Source Documentation
### Variable 1: `original-job-description`
*Original job description with formatting improvements only - NO content changes*
```
📋 **Data Analyst**
🏢 **Dillon Consulting**
⭐ **3.5 out of 5 stars**
📍 **Toronto, ON • Hybrid work**
💼 **Benefits:**
• Employee assistance program
• Flexible schedule
📋 **Overview**
Are you a skilled Data Analyst passionate about leading the implementation and management of impactful data-driven solutions? Do you excel at collaborating with diverse stakeholders to understand organizational needs, and then designing and developing customized data models and interactive dashboards using tools like Power BI? Are you experienced in integrating spatial data and GIS solutions to unlock deeper insights?
If you enjoy managing the full project lifecycle, from initial assessment to final deployment and user training, and are committed to driving process improvement by automating reporting and enhancing the accuracy of insights, this opportunity is for you! As someone with a blend of technical expertise, project management acumen, and strong communication skills, you will thrive in our fast-paced, collaborative, and innovative environment dedicated to fostering a data-driven culture.
🎯 **Your Opportunity**
Dillon's is looking for a Data Analyst to join our multidisciplinary team of professionals. You will have the opportunity to lead exciting projects, transforming complex data into actionable strategies and providing our clients with fully integrated and superior data solutions.
At Dillon, we operate as one team. The successful candidate can be based at any one of our offices across Canada.
We offer flexible work hours to help balance the competing demands of work and personal life.
🔧 **Responsibilities**
**What Your Day Will Look Like**
**Client Enablement & Stakeholder Collaboration**
• Collaborate closely with a wide range of stakeholders, including senior leadership, IT departments, data scientists, and client teams, to assess organizational needs and define project scope.
• Implement effective change management strategies, including comprehensive user training and ongoing support, to empower client teams and foster a data-driven culture.
• Facilitate working groups and workshops to promote knowledge transfer and ensure solutions meet evolving client requirements.
• Clearly communicate complex data concepts and project progress to both technical and non-technical audiences.
**Project Leadership & Solution Delivery**
• Lead the implementation and management of data-driven solutions for clients, overseeing the full project lifecycle from initial assessment and requirements gathering to deployment, user training, and ongoing support.
• Design and develop customized, relational data models and interactive, visually appealing dashboards using tools such as Power BI, ensuring they are user-friendly and provide actionable insights aligned with KPIs.
• Integrate spatial data and GIS solutions to enhance analytical capabilities and reporting.
• Ensure seamless data integration from multiple, diverse sources, adhering to data management best practices and establishing organizational data standards.
• Drive process improvement by identifying opportunities for automating reporting, reducing manual efforts, and enhancing the accuracy and timeliness of insights.
• Address and resolve challenges related to data connectivity, data quality, and visualization.
**Learning and Development**
• Commit to self-development and ongoing learning and professional development
• Contribute to Dillon's corporate profile through active participation in professional associations and committees
🎯 **Qualifications**
**What You Will Need To Succeed**
• A degree in Data Science, Computer Science, Information Management, Statistics, Mathematics, Engineering, Business Analytics, or a related field.
• A minimum of 5-7+ years of professional experience in a data analyst role, preferably with experience in a consulting or client-facing environment.
• Proven project management acumen with experience managing projects involving multiple data sources, diverse stakeholder groups, and complex reporting requirements.
• Relevant certifications in Power BI, other BI tools, data analytics, or project management (e.g., PMP) are highly desirable.
🔧 **Experience**
• Proven experience in designing, developing, and implementing customized relational data models and interactive dashboards using Power BI (or similar BI tools like Tableau, Qlik).
• Demonstrated ability in managing the full project lifecycle for data analytics initiatives, including requirements gathering, solution design, development, testing, deployment, and user training.
• Experience with data integration from various sources (databases, APIs, flat files) and establishing data quality and data governance practices.
• Proficiency in SQL and experience with data manipulation and analysis using Python or R is a strong asset.
• Experience with integrating and visualizing spatial data using GIS tools (e.g., ArcGIS, QGIS) and techniques.
• Strong understanding of KPI development and aligning data solutions to meet strategic business objectives.
• Demonstrated ability to automate reporting processes and improve data accuracy.
• Exceptional analytical, problem-solving, and critical-thinking skills.
• Excellent verbal and written communication skills, with the ability to present complex information clearly and persuasively to diverse audiences.
• Proven experience in facilitating workshops, leading training sessions, and managing change within organizations.
🏢 **Why Choose Dillon**
Dillon is powered by people who are technically proficient, passionate about socially important projects, and motivated to deliver superior, tangible results. We strive to remain at the forefront of technology and innovation, and are empowered to continually grow and develop.
**We live our core values:**
• **Reliability:** words result in actions that build trust;
• **Achievement:** do the work to hit the target;
• **Continuous development:** always learning; always adapting; always growing;
• **Creativity:** discover new possibilities;
• **Courage:** do the things that matter, especially when it's hard;
• **Inclusiveness:** enabling belonging to draw strength from our differences.
Dillon is a certified Great Place to Work. This recognition underscores our commitment to fostering an outstanding employee experience and cultivating an exceptional workplace culture. At Dillon, we believe that our people are our greatest asset. This designation reflects our ongoing efforts to ensure that our workplace is not just a place of work, but a community where everyone can thrive.
💰 **In addition, we offer:**
• Employee share purchase plan - Dillon is 100% employee owned and share ownership is open to all employees.
• A competitive compensation package
• Comprehensive health benefits
• Generous retirement savings plan
• Student loan repayment assistance with matching employer contributions
• Flexible work hours and hybrid working options
• Learning and Development opportunities
• Focus on Innovation
• Employee and Family Assistance program
• Goodlife Fitness Corporate Membership
• Wellness Subsidy
📋 **About Dillon**
Dillon is a proudly Canadian, employee-owned, professional consulting firm specializing in planning, engineering, environmental science, and management. We partner with clients to provide committed, collaborative, and inventive solutions to complex, multi-faceted projects. With over 20 offices and more than 1000 employees across Canada, Dillon offers a wide range of services related to building and improving facilities and infrastructure, protecting the environment, and developing communities.
Now operating for over 75 years, we continue to strive for excellence in everything we do. Dillon has been listed as one of Canada's Best Managed Companies for the past 18 years and has the distinction of having achieved Platinum Club member status in this program.
🌟 **Employment Equity, Diversity & Inclusion at Dillon**
Dillon is committed to the principles of employment equity, inclusiveness, and diversity within our organization. We strive to achieve a workplace where opportunities are based on skills and abilities and that respects and values differences.
Inclusion is more than a word to us, it is the way we choose to run our business. We encourage you to contact us if you require accommodation during the interview process. We would love to hear from you!
```
### Variable 2: `research-final-version`
*Processed and categorized information for analysis*
**Extracted Core Elements:**
- **Company Profile:** 75-year-old Canadian consulting firm, employee-owned, 1000+ employees, Great Place to Work certified
- **Role Level:** Senior individual contributor with project leadership responsibilities
- **Technical Stack:** Power BI (primary), SQL, Python/R, GIS tools (ArcGIS, QGIS), data integration tools
- **Soft Skills:** Stakeholder collaboration, change management, training/workshops, cross-functional communication
- **Experience Level:** 5-7+ years minimum, consulting/client-facing preferred
- **Team Context:** Multidisciplinary team, reports to senior leadership, collaborates with IT and data scientists
---
## 1. Job Description Analysis
### Company & Role Profile
**Company:** Dillon Consulting - 75-year-old Canadian consulting firm
**Department:** Data Analytics/Multidisciplinary team
**Industry:** Engineering/Environmental consulting with strong data focus
**Role Level:** Senior individual contributor with project leadership
**Team Size:** Large organization (1000+ employees)
**Reporting Structure:** Multidisciplinary team structure
### Company Intelligence
**Recent Developments:**
- Certified Great Place to Work recognition
- 18 consecutive years as Canada's Best Managed Company
- Platinum Club member status
- Strong focus on innovation and technology advancement
- Employee ownership structure (100% employee-owned)
**Company Culture Indicators:**
- Collaborative "one team" approach
- Values-driven (reliability, achievement, continuous development, creativity, courage, inclusiveness)
- Focus on work-life balance with flexible/hybrid options
- Strong learning and development culture
- Innovation-focused environment
**Industry Context:**
- Infrastructure and environmental consulting market
- Growing demand for data-driven solutions in consulting
- Emphasis on spatial data and GIS integration
- Client-facing technical roles in high demand
---
## 2. Requirements Analysis
### Technical Skills Assessment
| Required Skill | Skill Type | Explicitly Met? | Evidence Location | Strength Level | Strategic Notes |
|---|---|---|---|---|---|
| Power BI | Technical | Yes | Skills Summary + CS Portal project | Strong | Direct experience with dashboard development |
| SQL | Technical | Yes | Skills Summary + Summitt Energy role | Strong | Multiple database platforms (MSSQL, MySQL, PostgreSQL) |
| Python | Technical | Yes | Skills Summary + DataFlow projects | Strong | Advanced usage with Pandas, NumPy, SQLAlchemy |
| Data Modeling | Technical | Yes | DataFlow Development project | Strong | 5-year evolution of relational data models |
| Dashboard Development | Technical | Yes | CS Data Portal + DataFlow | Strong | Interactive dashboards with real-time insights |
| Data Integration | Technical | Yes | Multiple database workflows | Strong | APIs, flat files, multiple source integration |
| Project Management | Technical | Yes | CAPM certification + project experience | Strong | PMI standards, multiple complex projects |
| KPI Development | Technical | Yes | Customer Service KPIs project | Strong | 30% improvement in abandon rate |
| Process Automation | Technical | Yes | DataFlow automation + Python scripts | Strong | 40% efficiency improvements |
| GIS Tools | Technical | No | Not mentioned in resume | Developing | No direct experience, but strong technical foundation |
| Training/Workshops | Soft | Yes | Retention team management | Moderate | Led team of 4, conducted implementations |
| Stakeholder Collaboration | Soft | Yes | Cross-departmental work | Strong | IT collaboration, executive reporting |
| Change Management | Soft | Partial | Genesys Cloud migration | Moderate | Technical implementation focus |
### Soft Skills Assessment
| Required Skill | Met? | Evidence Location | Demonstration Method |
|---|---|---|---|
| Communication (Technical/Non-technical) | Yes | Executive dashboards + IT collaboration | Cross-functional technical communication |
| Workshop Facilitation | Partial | Retention team implementation | Team management and training |
| Project Leadership | Yes | Multiple large projects | End-to-end project ownership |
| Problem-solving | Yes | Error handling + optimization | Complex technical problem resolution |
### Experience Requirements
| Requirement | Leo's Background | Gap Analysis | Positioning Strategy |
|---|---|---|---|
| 5-7+ years Data Analyst | 5+ years at Summitt Energy | Meets minimum requirement | Emphasize depth and progression |
| Consulting/Client-facing | Internal consulting + PMI experience | Partial external consulting | Highlight internal stakeholder management |
| Degree in relevant field | Business Administration + certifications | Non-technical degree | Emphasize certifications and practical experience |
---
## 3. Responsibilities Matching & Performance Analysis
| Job Responsibility | Direct Experience | Related Experience | Performance Capability (1-5) | Implementation Approach |
|---|---|---|---|---|
| Lead data-driven solution implementation | Yes - DataFlow system | 5-year major system evolution | 5 | Leverage proven experience building enterprise data solutions from scratch |
| Design customized relational data models | Yes - SQLAlchemy implementation | OOP architecture with declarative tables | 5 | Apply advanced SQLAlchemy expertise to create scalable, maintainable models |
| Develop Power BI dashboards | Yes - Multiple dashboard projects | Customer Service Portal + reporting | 4 | Combine Power BI experience with Python automation for enhanced functionality |
| Manage full project lifecycle | Yes - Multiple complex projects | DataFlow, Retention Team, CMDB | 5 | Apply CAPM training and proven track record across 4+ major implementations |
| Stakeholder collaboration | Yes - Cross-departmental work | IT teams, executives, specialists | 4 | Leverage experience translating technical concepts for diverse audiences |
| Data integration from multiple sources | Yes - Complex data workflows | APIs, databases, flat files | 5 | Apply expertise with SQLAlchemy, FastAPI, and multiple database platforms |
| Automate reporting processes | Yes - Extensive automation | Python scripts, batch uploads, CLI | 5 | Use proven automation framework that achieved 40%+ efficiency gains |
| Establish data quality practices | Yes - Error handling systems | Comprehensive logging, validation | 4 | Implement robust error handling and data validation methodologies |
| GIS data integration | No direct experience | Strong technical foundation | 3 | Apply Python spatial libraries and database skills to rapidly acquire GIS expertise |
| User training and support | Partial - Team training | Retention team management | 3 | Expand team leadership experience to client training scenarios |
| Change management strategies | Partial - Migration projects | Genesys Cloud implementation | 3 | Build on technical change management to include organizational aspects |
**Performance Capability Legend:**
- 5: Expert level, immediate impact
- 4: Proficient, minimal ramp-up
- 3: Competent, moderate learning
- 2: Developing, significant growth needed
- 1: Beginner, extensive training required
---
## 4. Strategic Skill Transferability Analysis
### Hidden Value Opportunities
**Advanced Automation Capabilities:**
- Job mentions: "automate reporting processes and improve data accuracy"
- Leo's advantage: Python expertise with SQLAlchemy, FastAPI, and CLI development enables sophisticated automation solutions beyond standard BI tools. Can create enterprise-grade data pipelines with robust error handling.
**Technical Infrastructure Perspective:**
- Job mentions: "data integration from multiple sources"
- Leo's advantage: Experience with Azure DevOps, multiple database platforms, and API development provides infrastructure perspective often missing in traditional data analyst roles.
**Performance Optimization Mindset:**
- Job mentions: "enhance accuracy and timeliness of insights"
- Leo's advantage: Proven track record of 50% reporting time reduction and 40% efficiency improvements demonstrates optimization expertise that goes beyond basic reporting.
### Cross-Domain Value Creation
| Job Area | Standard Approach | Leo's Enhanced Approach | Competitive Advantage |
|---|---|---|---|
| Data Modeling | Basic Power BI models | SQLAlchemy declarative architecture + OOP design | Scalable, maintainable enterprise solutions |
| Dashboard Development | Static BI dashboards | Interactive dashboards + Python automation + APIs | Real-time, automated insights with advanced functionality |
| Project Management | Traditional PM tools | CAPM methodology + technical implementation | Bridge between business requirements and technical delivery |
| Data Quality | Manual validation | Automated error handling + comprehensive logging | Proactive quality assurance with detailed audit trails |
---
## 5. Keywords & Messaging Strategy
### Primary Keywords (Must Include)
- Power BI, SQL, Python, data modeling, dashboard development
- Project lifecycle management, stakeholder collaboration, data integration
- Process automation, KPI development, data quality, reporting optimization
- Cross-functional communication, requirements gathering, solution deployment
### Secondary Keywords (Should Include)
- SQLAlchemy, FastAPI, Azure DevOps, change management, user training
- Data governance, business intelligence, analytical solutions, performance optimization
- Multidisciplinary teams, client-facing, consulting environment
### Leo's Unique Keywords (Differentiators)
- Enterprise data architecture, OOP data modeling, API development
- Batch processing optimization, automated data workflows, CLI development
- Cross-platform database integration, technical project leadership
### Messaging Themes
1. **Primary Theme:** Senior technical leader with proven ability to design and implement enterprise-scale data solutions
2. **Supporting Themes:**
- Bridge between technical complexity and business value
- Optimization expert with quantifiable efficiency improvements
- Full-stack data professional combining analysis, automation, and architecture
3. **Proof Points:** 5-year DataFlow evolution, 50% reporting time reduction, 40% efficiency improvements
---
## 6. Competitive Positioning
### Leo's Unique Advantages
1. **Enterprise Architecture Experience:** Unlike typical data analysts, Leo has designed and evolved enterprise-scale data systems over 5 years, demonstrating rare combination of analytical and architectural skills
2. **Proven Optimization Results:** Quantifiable improvements (50% reporting reduction, 40% efficiency gains) demonstrate ability to deliver measurable business value
3. **Technical Depth + Business Acumen:** Combination of advanced programming skills (SQLAlchemy, FastAPI, CLI) with business process optimization and stakeholder management
### Potential Differentiators
- **Technical Depth:** Advanced Python automation and database architecture skills exceed typical Power BI analyst requirements
- **Cross-Functional Value:** Project management certification combined with hands-on technical implementation
- **Scalability Focus:** Experience building systems that evolved over 5 years shows long-term thinking and maintainable design
### Gap Mitigation Strategies
| Identified Gap | Mitigation Approach | Supporting Evidence |
|---|---|---|---|
| Formal GIS experience | Emphasize rapid technical learning ability | Mastered complex tech stack including multiple databases, APIs, automation |
| External consulting experience | Highlight internal consulting and PMI background | Project Management Institute experience + cross-departmental collaboration |
| Formal data science degree | Emphasize practical results and ongoing certification | Ryerson Big Data certification + IBM Data Science (ongoing) + 5+ years proven results |
---
## 7. Application Strategy Recommendations
### Resume Optimization Priorities
1. **Lead with:** Data analysis expertise with enterprise system design and 5+ years progressive experience
2. **Quantify:** 50% reporting time reduction, 40% efficiency improvements, 30% process optimization, zero-error achievement
3. **Technical Focus:** Power BI + Python automation + SQL + project management combination
4. **Experience Narrative:** Evolution from analyst to technical leader driving enterprise solutions
### Cover Letter Strategy
1. **Opening Hook:** "5+ years transforming data challenges into scalable enterprise solutions"
2. **Core Message:** Unique combination of analytical expertise, technical architecture, and proven optimization results
3. **Supporting Examples:**
- DataFlow 5-year evolution demonstrating long-term system thinking
- Quantifiable efficiency improvements aligning with Dillon's achievement values
- Cross-functional collaboration matching their "one team" approach
4. **Company Connection:** Align with Dillon's values of continuous development, achievement, and innovation
### Potential Red Flags to Address
- **Non-technical degree:** Proactively emphasize practical certifications, ongoing learning, and 5+ years of proven technical results
- **Limited external consulting:** Position internal cross-departmental work as equivalent stakeholder management experience
---
## 8. Phase 2 Handoff Information
### Resume Content Priorities (High to Low)
1. **Summitt Energy Data Analyst role** - Emphasize Power BI, Python, SQL, dashboard development, project leadership
2. **DataFlow Development project** - Highlight enterprise architecture, 5-year evolution, OOP design, automation
3. **Customer Service KPIs project** - Showcase quantifiable business improvements and stakeholder collaboration
4. **Technical skills summary** - Focus on Power BI, Python, SQL, project management combination
5. **Education and certifications** - Emphasize relevant certifications and ongoing learning
### Key Messages for Integration
- **Primary Value Prop:** Senior data analyst with enterprise architecture experience and proven optimization results
- **Technical Emphasis:** Power BI + Python automation + SQL + project management
- **Achievement Focus:** 50% reporting reduction, 40% efficiency improvements, 30% process optimization
### Style Guidance
- **Tone:** Technical leadership with business impact focus
- **Emphasis:** Scalable solutions, quantifiable results, cross-functional collaboration
- **Keywords:** Enterprise data solutions, process optimization, stakeholder collaboration, technical leadership
---
## 9. Research Quality Metrics
**Analysis Completeness:**
- Job requirements coverage: 95%
- Skills assessment depth: Comprehensive
- Company research depth: Comprehensive
- Strategic insights quality: High
**Evidence Base:**
- All assessments tied to resume evidence: ✅ Yes
- Transferability analysis completed: ✅ Yes
- Competitive advantages identified: 6 major advantages found
**Source Documentation Quality:**
- Original job description preserved intact: ✅ Yes
- Formatting improvements applied appropriately: ✅ Yes
- Research version comprehensively categorized: ✅ Yes
- Cross-reference accuracy verified: ✅ Yes
**Readiness for Phase 2:**
- Clear content priorities established: ✅ Yes
- Strategic direction defined: ✅ Yes
- All handoff information complete: ✅ Yes
- Original source material available for reference: ✅ Yes
---
## 10. Final Validation Against Original Source
**Cross-Reference Check:**
- ✅ All analyzed requirements traced back to `original-job-description`
- ✅ No requirements missed or misinterpreted
- ✅ Analysis accurately reflects original posting intent
- ✅ Strategic recommendations align with actual job needs
**Original Source Integrity:**
- ✅ `original-job-description` contains exact text as provided
- ✅ Only formatting/organization improvements applied
- ✅ No content modifications or interpretations added
- ✅ Serves as reliable reference for future phases
---
**Phase 1 Status:** ✅ Complete
**Next Phase:** Resume Optimization
**Analyst:** Job Application Research Agent
**Review Required:** No - proceeding to Phase 2
**Documentation Archive:**
- ✅ `original-job-description` preserved and formatted
- ✅ `research-final-version` created and analyzed
- ✅ Strategic analysis completed
- ✅ Ready for Phase 2 handoff

49
docs/ai/optimized_resume_dillon.md Normal file
View File

@@ -0,0 +1,49 @@
# **Leo Miranda**
**leobrmi@hotmail.com | (416) 859-7936**
## **Professional Summary**
Senior Data Analyst with 5+ years of enterprise data system design and implementation experience. Proven track record of delivering measurable business impact through advanced dashboard development, process automation, and stakeholder collaboration. Expert in Power BI, Python, and SQL with demonstrated ability to reduce reporting times by 50% and improve operational efficiency by 40% through innovative data solutions.
## **Core Competencies**
**Technical Expertise:** Power BI • SQL (Microsoft SQL, MySQL, PostgreSQL) • Python (Pandas, NumPy, SQLAlchemy) • Data Modeling • Dashboard Development • Process Automation • FastAPI • Azure DevOps
**Business Intelligence:** KPI Development • Data Integration • Reporting Optimization • Data Quality Management • Business Process Analysis • Performance Analytics
**Project Leadership:** Full Lifecycle Management • Stakeholder Collaboration • Change Management • Cross-Functional Communication • Requirements Gathering • User Training
## **Professional Experience**
### **Data and Reporting Analyst | Summitt Energy | 2020-Present**
**Enterprise Data Solutions & Architecture**
• Designed and evolved comprehensive DataFlow system over 5 years through 4 major version updates, establishing foundational reporting infrastructure for Customer Service department
• Implemented Object-Oriented Programming architecture with SQLAlchemy declarative table definitions, creating scalable enterprise data models
• Developed high-performance batch upload methods for seamless CSV-to-MSSQL data ingestion and optimized CRUD operations
**Dashboard Development & Business Intelligence**
• Created interactive dashboards using Power BI, Plotly-Dash, and advanced visualization tools, providing real-time insights into business operations and partner performance
• Reduced reporting times by 50% through automated data workflows and enhanced decision-making capabilities
• Developed Customer Service Data Portal ensuring 100% accessibility with role-based access controls
**Process Optimization & Automation**
• Engineered Python automation scripts improving department reporting efficiency by 40% with near-zero error rates
• Implemented comprehensive KPI tracking resulting in 30% improvement in abandon rate and 50% increase in Average Speed Answer
• Established robust error handling mechanisms with comprehensive logging, drastically improving system reliability and maintainability
**Project Leadership & Stakeholder Collaboration**
• Led end-to-end implementation of retention team, managing 4 specialists and executing technical configurations for multi-state campaigns
• Collaborated with IT department on architectural design and implementation of inbound and outbound workflows
• Orchestrated Genesys Cloud migration, focusing on tool configuration, data architecture design, and workflow optimization
• Implemented Azure DevOps for centralized project repository management with Agile-based boards
### **Commercial Sales Admin | Summitt Energy | 2017-2020**
• Developed Commercial Drop Manager tool achieving 100% accuracy and reducing task completion time by 75%
• Created data visualization tools for commercial volume forecasting, enhancing accuracy by 25% and promoting data-driven decision-making
• Monitored sales team performance leading to 15% increase in sales efficiency through weekly reporting and analysis
## **Education & Certifications**
• **Ryerson University:** Big Data and Analytics Certification (2021)
• **IBM Data Science Professional Certificate** (Ongoing, Expected 2024)
• **CAPM Certification** (Project Management Institute)
• **Bachelor's Degree in Business Administration** - UCAM (Rio de Janeiro/Brazil)
• **ITIL V3 Foundation Certification**

37
docs/ai/phase1_template.md Normal file
View File

@@ -0,0 +1,37 @@
# Job Application Research Phase
## Job Description Analysis
**Company:** [Company Name]
**Role:** [Position Title]
**Link/Source:** [URL or "Pasted Content"]
### Company/Department Details
- [Company mission, culture, values]
- [Department structure and team dynamics]
- [Key stakeholders and reporting structure]
### Qualification Requirements Analysis
| Required Skill | Type | Met Requirement? | Location in Resume | Priority Level |
|---|---|---|---|---|
| [Skill 1] | Technical/Soft | Yes/No | [Section] | High/Medium/Low |
### Role Responsibilities Matching
| Responsibility | Past Experience Met | Corresponding Experience | Reference (Role/Company) | Strength of Match |
|---|---|---|---|---|
| [Responsibility 1] | Yes/No | [Description] | [Role - Company] | Strong/Moderate/Weak |
### Keywords & Themes
**Primary Keywords:** [List]
**Secondary Keywords:** [List]
**Underlying Themes:** [Company values, desired traits]
### Phase 1 Summary & Recommendations
- **Alignment Score:** [X/10]
- **Key Strengths:** [Top 3 matching areas]
- **Potential Gaps:** [Areas needing emphasis]
- **Adaptation Strategy:** [High-level approach]
---
**Handoff to Phase 2:** ✅ Ready for Resume Optimization

190
docs/ai/phase2_resume_prompt.md Normal file
View File

@@ -0,0 +1,190 @@
# Phase 2: Resume Optimization Agent
You are an expert Resume Optimization Agent, specialized in transforming comprehensive professional backgrounds into targeted, high-impact resumes. You will adapt Leo Miranda's complete resume to maximize alignment with specific job opportunities using strategic insights from Phase 1 research.
## Core Mission
Create a compelling, strategically-optimized resume that positions Leo as the ideal candidate while maintaining 100% accuracy to his actual experience and staying within a strict 600-word limit.
## Required Inputs & Resources
- **Phase 1 Research Report**: Complete strategic analysis with competitive advantages, keyword priorities, and positioning recommendations
- **`complete_resume`**: Leo's comprehensive professional background (access via google_drive_search)
- **Target Word Count**: Maximum 600 words total
- **Output Format**: Markdown for easy copy/paste
## Resume Optimization Workflow
### Step 1: Load Strategic Direction
**Action**: Review Phase 1 Research Report thoroughly to extract:
- **Primary positioning strategy** and messaging themes
- **Content prioritization order** (High/Medium/Low priority experiences)
- **Keywords integration list** (primary and secondary)
- **Competitive advantages** to emphasize
- **Gap mitigation strategies** to implement
- **Quantifiable achievements** to highlight
### Step 2: Access Complete Resume
**Action**: Use google_drive_search to locate and access Leo's `complete_resume` document
- Extract ALL content and experiences available
- Catalog all skills, projects, achievements, and quantifiable results
- Note all technical proficiencies and soft skills demonstrated
### Step 3: Strategic Content Selection
**Action**: Based on Phase 1 priorities, categorize resume content:
**MUST INCLUDE (High Priority):**
- Experiences directly matching job requirements
- Projects demonstrating key capabilities
- Quantifiable achievements supporting competitive advantages
- Skills explicitly requested in job description
**SHOULD INCLUDE (Medium Priority):**
- Supporting experiences that reinforce primary themes
- Additional technical skills enhancing value proposition
- Relevant certifications and education
**COULD INCLUDE (Low Priority):**
- Supplementary experiences if word count allows
- Additional context for career progression
### Step 4: Content Optimization & Adaptation
**Action**: Transform selected content to maximize impact:
**Achievement Amplification:**
- Lead with quantifiable results and business impact
- Use action verbs that align with job responsibilities
- Frame experiences in terms of value delivered
**Keyword Integration:**
- Naturally incorporate primary keywords from Phase 1
- Ensure technical terms match job description language
- Maintain readability while optimizing for ATS systems
**Strategic Positioning:**
- Present Leo according to Phase 1 positioning strategy
- Emphasize unique competitive advantages identified
- Address potential gaps proactively through framing
### Step 5: Structure & Formatting
**Action**: Organize optimized content using professional resume structure:
```markdown
# **Leo Miranda**
[Contact Information]
## **Professional Summary**
[2-3 lines capturing value proposition and primary strengths]
## **Core Competencies**
[Strategic skill groupings based on job requirements]
## **Professional Experience**
[Prioritized positions with optimized bullet points]
## **Key Projects** (if space allows)
[High-impact projects demonstrating capabilities]
## **Education & Certifications**
[Relevant credentials supporting positioning]
```
### Step 6: Word Count Management
**Action**: Achieve 600-word target through strategic editing:
**Prioritization Approach:**
1. Preserve all high-priority content
2. Condense medium-priority content effectively
3. Remove low-priority content if necessary
4. Optimize language for conciseness without losing impact
**Quality Standards:**
- Every word must add value
- Maintain professional tone and readability
- Preserve all quantifiable achievements
- Ensure technical accuracy
### Step 7: Keyword Validation
**Action**: Cross-reference final resume against Phase 1 keyword list:
- Verify primary keywords are naturally integrated
- Confirm secondary keywords are included where appropriate
- Ensure technical terms match job description language
- Validate ATS optimization without keyword stuffing
### Step 8: Strategic Alignment Review
**Action**: Validate resume against Phase 1 strategic recommendations:
- Confirm positioning strategy is effectively implemented
- Verify competitive advantages are prominently featured
- Ensure gap mitigation strategies are reflected
- Check that messaging themes are consistently reinforced
### Step 9: Quality Assurance
**Action**: Comprehensive resume validation:
**Accuracy Check:**
- All content must be verifiable against original resume
- No fabrication or exaggeration of experiences
- Dates, companies, and roles must be accurate
- Technical skills must reflect actual proficiency
**Impact Assessment:**
- Quantifiable achievements prominently featured
- Value propositions clearly articulated
- Career progression logically presented
- Unique strengths effectively highlighted
**Professional Standards:**
- Consistent formatting and structure
- Error-free grammar and spelling
- Professional language and tone
- Appropriate level of detail for space constraints
## Output Requirements
### Deliverable 1: Strategic Resume (Markdown Format)
Present the optimized resume in clean markdown format ready for copy/paste, including:
- Professional header with contact information
- Strategic summary aligned with Phase 1 positioning
- Prioritized experience section with optimized bullet points
- Technical skills emphasizing job-relevant competencies
- Education and certifications supporting candidacy
### Deliverable 2: Optimization Summary
Provide brief analysis including:
- **Content decisions made** and rationale
- **Keywords successfully integrated** from Phase 1 list
- **Competitive advantages emphasized** in final version
- **Word count breakdown** by section
- **Strategic positioning implementation** summary
### Deliverable 3: User Review Points
Present specific areas for Leo's feedback:
- Content prioritization decisions
- Technical skill emphasis choices
- Achievement quantification accuracy
- Any content that required significant condensation
## Quality Standards & Constraints
### Mandatory Requirements:
- **600-word maximum** (strict limit)
- **100% factual accuracy** to original resume
- **Strategic alignment** with Phase 1 recommendations
- **Professional markdown formatting**
- **ATS optimization** without sacrificing readability
### Success Metrics:
- High-impact content within word constraints
- Strategic positioning clearly implemented
- Primary keywords naturally integrated
- Competitive advantages prominently featured
- Ready for immediate job application submission
## Operational Rules
1. **Evidence-Based Only**: Every statement must be verifiable against original resume
2. **No Fabrication**: Never invent experiences, skills, or achievements
3. **Strategic Focus**: Prioritize content supporting Phase 1 positioning strategy
4. **Word Discipline**: Respect 600-word limit through strategic editing, not content reduction
5. **Quality Priority**: Maintain professional standards while optimizing for impact
6. **User Collaboration**: Present clear review points for Leo's validation
7. **Phase Integration**: Seamlessly implement Phase 1 strategic recommendations
**Success Definition**: A compelling, strategically-optimized resume that positions Leo as the ideal candidate while maintaining complete accuracy and staying within word constraints, ready for immediate submission and Phase 3 handoff.

230
docs/ai/phase3_cover_letter_prompt.md Normal file
View File

@@ -0,0 +1,230 @@
# Phase 3: Cover Letter Generation Agent
You are an expert Cover Letter Generation Agent, specialized in creating compelling, authentic, and strategically-targeted cover letters that cut through generic application noise. You will craft Leo Miranda's cover letter using strategic insights from Phase 1 research and the optimized resume from Phase 2, focusing on genuine value proposition and direct impact.
## Core Mission
Create a persuasive, personal, and authentic cover letter that demonstrates exactly how Leo's skills will contribute to the daily operations of the target role, while maintaining a professional yet direct tone that eliminates corporate fluff.
## Required Inputs & Resources
- **Phase 1 Research Report**: Complete strategic analysis with transferability insights and competitive advantages
- **Phase 2 Optimized Resume**: Tailored resume content and positioning strategy
- **Leo's Style Reference**: File `Leonardo-Miranda_20250715_summitt-ops.docx` for authentic voice training
- **Leo's Background Context**: Neurodivergent data scientist, Toronto-based, self-taught expertise
- **Target Tone**: Personal, convincing, authentic - using Leo's proven successful voice
- **Output Format**: Complete cover letter in markdown, ready for submission
## Cover Letter Generation Workflow
### Step 1: Extract Strategic Intelligence
**Action**: Review Phase 1 Research Report to identify:
- **Daily Operations Impact**: Specific ways Leo's skills enhance day-to-day role performance
- **Transferability Opportunities**: How Leo's technical skills solve problems beyond basic requirements
- **Competitive Advantages**: Unique value propositions that differentiate Leo
- **Company Intelligence**: Culture, values, and specific organizational needs
- **Gap Mitigation**: Strategies to address any experience gaps authentically
### Step 2: Learn Leo's Authentic Writing Style
**Action**: Access and analyze `Leonardo-Miranda_20250715_summitt-ops.docx` via google_drive_search to extract:
**Leo's Voice Characteristics:**
- **Warmth & Genuine Enthusiasm**: Uses phrases like "genuine excitement," "I've developed a deep appreciation," "truly draws me to"
- **Natural Flow**: Longer, connected sentences that feel conversational rather than corporate
- **Humble Confidence**: Acknowledges learning opportunities while demonstrating expertise ("it's an area where I know I have much to learn, but...")
- **Specific Knowledge**: References actual work context and business challenges with insider understanding
- **Personal Connection**: Shows genuine interest in the work itself, not just career advancement
- **Natural Time References**: "Having spent the past five years," "I've spent these past years" instead of generic time markers
**Sentence Structure Patterns:**
- Uses connecting phrases to create flowing paragraphs
- Balances technical specificity with business impact
- Expresses learning curiosity while highlighting relevant experience
- Maintains professional warmth throughout
**Authentic Language Markers:**
- "I've had the privilege of developing..."
- "The most rewarding part has been watching..."
- "What genuinely excites me about this opportunity..."
- "I'm eager to bring my problem-solving mindset..."
- References to learning from the target team's expertise
### Step 2: Analyze Target Role Daily Realities
**Action**: Based on research, identify the actual daily challenges of the position:
- **Technical Problems**: Data connectivity, quality issues, complex integrations
- **Stakeholder Challenges**: Cross-functional communication, requirement gathering
- **Process Inefficiencies**: Manual reporting, time-consuming workflows
- **Business Needs**: KPI development, performance optimization, strategic insights
### Step 3: Map Leo's Solutions to Daily Operations
**Action**: Create specific connections between Leo's experience and daily role requirements:
**Technical Contributions:**
- How Leo's Python automation solves their process improvement needs
- How Leo's enterprise data architecture experience handles their complex integration challenges
- How Leo's proven optimization results (40% efficiency gains) directly apply to their workflow enhancement goals
**Business Impact Contributions:**
- How Leo's stakeholder collaboration experience supports their client-facing requirements
- How Leo's project management expertise enables their full lifecycle delivery needs
- How Leo's proven track record delivers measurable results they're seeking
### Step 4: Gather Company-Specific Intelligence
**Action**: Extract from Phase 1 research:
- **Company Values**: How Leo's approach aligns with Dillon's stated values
- **Cultural Fit**: Connections between Leo's work style and their collaborative environment
- **Strategic Initiatives**: How Leo contributes to their innovation and technology advancement goals
- **Employee Ownership**: How Leo's long-term thinking aligns with their ownership culture
### Step 5: Structure Using Leo's Proven Framework
**Action**: Organize content using Leo's successful cover letter structure:
```markdown
[Date]
[Company Information]
**Opening Paragraph: Personal Connection + Genuine Enthusiasm**
- Start with "I'm writing to you today with genuine excitement about..."
- Express specific appreciation for the company's work/reputation
- Create personal connection to the role/industry
- Preview unique qualifications naturally
**Body Paragraph 1: Deep Contextual Knowledge + Specific Examples**
- "Having spent the past [X] years immersed in..." or "I've spent these past years working with..."
- Demonstrate specific understanding of relevant business challenges
- Reference actual projects (like DataFlow) with natural evolution story
- Show impact through specific, relatable examples
**Body Paragraph 2: Learning Excitement + Value Contribution**
- "What genuinely excites me about this opportunity..."
- Express humble confidence: acknowledge learning opportunities while highlighting transferable expertise
- Connect Leo's skills to company's specific needs
- Show enthusiasm for contributing to their team's success
**Closing Paragraph: Genuine Forward-Looking Appreciation**
- "I'm genuinely looking forward to the possibility of discussing..."
- Express authentic appreciation for consideration
- Professional but warm sign-off
```
### Step 6: Craft Authentic Content Using Leo's Voice
**Action**: Write each section channeling Leo's proven successful style:
**Tone Guidelines:**
- **Warm Professional Enthusiasm**: Genuine excitement about the work, not just the opportunity
- **Natural Conversational Flow**: Longer, connected sentences that feel organic
- **Humble Confidence**: Show expertise while expressing genuine learning curiosity
- **Specific and Contextual**: Reference actual work challenges and business understanding
- **Personal Connection**: Demonstrate authentic interest in the company's mission and work
**Leo's Authentic Language Patterns:**
- **Opening**: "I'm writing to you today with genuine excitement about..."
- **Experience Framing**: "Having spent the past [X] years immersed in..." / "I've spent these past years working with..."
- **Project Descriptions**: "I've had the privilege of developing..." / "The most rewarding part has been watching..."
- **Learning Mindset**: "it's an area where I know I have much to learn, but my experience with... has taught me..."
- **Enthusiasm**: "What genuinely excites me about this opportunity..." / "I'm eager to bring my problem-solving mindset..."
- **Closing**: "I'm genuinely looking forward to the possibility of discussing..."
**Content Principles:**
- Use Leo's natural flowing sentence structure from reference document
- Express genuine curiosity about learning from the target team
- Balance technical expertise with humble learning attitude
- Show specific understanding of business challenges
- Maintain warm professionalism throughout
- Reference actual project names and specific accomplishments naturally
### Step 7: Integration of Research Insights
**Action**: Weave Phase 1 strategic findings throughout:
- **Competitive Advantages**: Naturally integrate identified differentiators
- **Transferability Examples**: Include specific skill applications
- **Company Alignment**: Reference their values and culture appropriately
- **Gap Addressing**: Proactively handle any experience gaps with confidence
### Step 8: Optimize for Impact and Authenticity
**Action**: Ensure cover letter achieves maximum impact:
**Impact Optimization:**
- Lead with strongest value propositions
- Use active voice and strong action verbs
- Include specific, quantifiable achievements
- Connect Leo's experience to their business needs
**Authenticity Checks:**
- Eliminate corporate jargon and buzzwords
- Use conversational but professional language
- Reflect Leo's genuine enthusiasm and approach
- Maintain consistency with resume positioning
### Step 9: Final Quality Assurance
**Action**: Comprehensive validation of final cover letter:
**Accuracy Verification:**
- All claims must be verifiable against resume and research
- Technical details must be accurate
- Company information must be correct
- Quantifiable results must match source materials
**Professional Standards:**
- Error-free grammar, spelling, and formatting
- Appropriate length (typically 3-4 paragraphs, 350-450 words)
- Professional formatting ready for submission
- Clear, scannable structure
## Output Requirements
### Deliverable: Complete Cover Letter (Markdown Format)
Present the final cover letter including:
```markdown
**Leo Miranda**
leobrmi@hotmail.com | (416) 859-7936
[Date]
[Hiring Manager/Dillon Consulting]
[Address if available]
Dear Hiring Manager,
[Complete cover letter content with proper paragraph structure]
Sincerely,
Leo Miranda
```
### Content Standards:
- **Length**: 350-450 words optimal
- **Structure**: Conventional 3-4 paragraph format
- **Tone**: Personal, direct, authentic - no corporate fluff
- **Focus**: Daily operations impact and specific value delivery
- **Evidence**: Quantifiable results and concrete examples
- **Alignment**: Clear connection to company culture and values
## Quality Standards & Success Metrics
### Mandatory Requirements:
- **Authentic Voice**: Reflects Leo's genuine enthusiasm and approach
- **Specific Value**: Clear daily operations contributions identified
- **Evidence-Based**: All claims supported by resume and research
- **Direct Communication**: Eliminates unnecessary corporate language
- **Complete Format**: Ready for immediate submission
### Success Metrics:
- Captures Leo's authentic voice and writing style from reference document
- Demonstrates clear understanding of role daily realities
- Shows specific ways Leo's skills solve their actual problems
- Reflects genuine interest in company and position using Leo's natural enthusiasm
- Positions Leo as ideal candidate through authentic differentiation
- Creates compelling case for interview invitation using proven successful approach
- Maintains Leo's characteristic warmth while staying professional
- Uses Leo's natural sentence flow and language patterns
## Operational Rules
1. **Authentic Voice Priority**: Must sound exactly like Leo based on reference document analysis
2. **Style Training Required**: Always access and analyze `Leonardo-Miranda_20250715_summitt-ops.docx` first
3. **Evidence-Based Claims**: Every statement must be verifiable against resume and research
4. **Natural Flow**: Use Leo's flowing, connected sentence structure
5. **Humble Confidence**: Balance expertise demonstration with genuine learning curiosity
6. **Strategic Integration**: Seamlessly incorporate Phase 1 and Phase 2 insights using Leo's voice
7. **Warm Professionalism**: Maintain Leo's characteristic warmth while staying professional
8. **Submission Ready**: Deliver complete, formatted document requiring no additional editing
**Success Definition**: A compelling, authentically Leo-voiced cover letter that demonstrates specific value contribution to daily operations while expressing genuine enthusiasm for learning and collaboration, written in Leo's proven successful style that has generated positive responses.

280
docs/ai/research_output_report.md Normal file
View File

@@ -0,0 +1,280 @@
# Job Application Research Report
## Executive Summary
**Candidate:** Leo Miranda
**Target Role:** [Position Title]
**Company:** [Company Name]
**Analysis Date:** [Date]
**Overall Fit Score:** [X/10]
**Recommendation:** [Proceed/Proceed with Caution/Reconsider]
**Key Takeaways:**
- **Primary Strength:** [Top competitive advantage]
- **Unique Value Proposition:** [What sets Leo apart]
- **Strategic Focus:** [Main positioning theme]
- **Potential Challenge:** [Primary gap to address]
---
## Source Documentation
### Variable 1: `original-job-description`
*Original job description with formatting improvements only - NO content changes*
```
[EXACT job description text as provided by user]
[Only formatting applied: bullet points, icons, spacing, headers for organization]
[NO words, phrases, or meaning altered]
📋 **Role Title:** [As stated in original]
🏢 **Company:** [As stated in original]
📍 **Location:** [As stated in original]
🔧 **Key Responsibilities:**
• [Original responsibility 1]
• [Original responsibility 2]
• [Original responsibility 3]
🎯 **Required Qualifications:**
• [Original qualification 1]
• [Original qualification 2]
• [Original qualification 3]
⭐ **Preferred Qualifications:**
• [Original preferred 1]
• [Original preferred 2]
💼 **Company Information:**
[Any company description as provided in original]
📝 **Additional Details:**
[Any other information from original posting]
```
### Variable 2: `research-final-version`
*Processed and categorized information for analysis*
**Extracted Core Elements:**
- **Company Profile:** [Analytical summary]
- **Role Level:** [Analyzed level and scope]
- **Technical Stack:** [Identified technologies]
- **Soft Skills:** [Communication, leadership requirements]
- **Experience Level:** [Years, background needed]
- **Team Context:** [Reporting structure, collaboration needs]
---
## 1. Job Description Analysis
### Company & Role Profile
**Company:** [Name and brief description]
**Department:** [Team/Division]
**Industry:** [Sector and market position]
**Role Level:** [Junior/Mid/Senior/Lead]
**Team Size:** [If specified]
**Reporting Structure:** [Manager title/department]
### Company Intelligence
**Recent Developments:**
- [Key news, funding, acquisitions, strategic initiatives]
**Company Culture Indicators:**
- [Values, work style, team dynamics from job posting and research]
**Industry Context:**
- [Market trends, competitive landscape, growth areas]
---
## 2. Requirements Analysis
### Technical Skills Assessment
| Required Skill | Skill Type | Explicitly Met? | Evidence Location | Strength Level | Strategic Notes |
|---|---|---|---|---|---|
| [Example: Python] | Technical | Yes | Data Science Projects | Strong | Core expertise, multiple implementations |
| [Example: SQL] | Technical | Yes | Summitt Energy role | Strong | Production database experience |
| [Example: Machine Learning] | Technical | Partial | Self-taught projects | Moderate | Strong foundation, can emphasize growth trajectory |
### Soft Skills Assessment
| Required Skill | Met? | Evidence Location | Demonstration Method |
|---|---|---|---|
| [Example: Leadership] | Yes | Startup Founder experience | Team building and project management |
| [Example: Communication] | Yes | Cross-departmental collaboration | Stakeholder presentation experience |
### Experience Requirements
| Requirement | Leo's Background | Gap Analysis | Positioning Strategy |
|---|---|---|---|
| [Example: 3+ years Data Science] | 2+ years practical experience | 1 year formal gap | Emphasize depth over duration, self-taught dedication |
---
## 3. Responsibilities Matching & Performance Analysis
| Job Responsibility | Direct Experience | Related Experience | Performance Capability (1-5) | Implementation Approach |
|---|---|---|---|---|
| [Example: Build ML models] | Yes - customer segmentation | Multiple personal projects | 4 | Leverage scikit-learn, pandas expertise for rapid prototyping |
| [Example: Database optimization] | Partial - query optimization | VPS performance tuning | 4 | Apply DevOps optimization mindset to database performance |
| [Example: Stakeholder reporting] | Yes - executive dashboards | Cross-departmental communication | 3 | Combine technical depth with business communication skills |
**Performance Capability Legend:**
- 5: Expert level, immediate impact
- 4: Proficient, minimal ramp-up
- 3: Competent, moderate learning
- 2: Developing, significant growth needed
- 1: Beginner, extensive training required
---
## 4. Strategic Skill Transferability Analysis
### Hidden Value Opportunities
**Automation Capabilities:**
- Job mentions: [Example: "streamline reporting processes"]
- Leo's advantage: Python automation, VBA scripting, and DevOps practices enable sophisticated solutions beyond standard tools
**Technical Infrastructure:**
- Job mentions: [Example: "manage data systems"]
- Leo's advantage: VPS/DevOps background provides infrastructure perspective often missing in pure data science roles
**Innovation Potential:**
- Job mentions: [Example: "improve data accuracy"]
- Leo's advantage: AI/ML expertise can introduce predictive validation and anomaly detection beyond traditional QA methods
### Cross-Domain Value Creation
| Job Area | Standard Approach | Leo's Enhanced Approach | Competitive Advantage |
|---|---|---|---|
| [Example: Data Analysis] | Excel/BI tools | Python automation + statistical modeling | Deeper insights, scalable solutions |
| [Example: System Integration] | Manual processes | DevOps automation + API development | Efficiency gains, reduced errors |
---
## 5. Keywords & Messaging Strategy
### Primary Keywords (Must Include)
- [List of critical terms from job description]
### Secondary Keywords (Should Include)
- [Supporting terms and industry language]
### Leo's Unique Keywords (Differentiators)
- [Technical terms that showcase Leo's unique skill combination]
### Messaging Themes
1. **Primary Theme:** [Main positioning message]
2. **Supporting Themes:** [2-3 additional value propositions]
3. **Proof Points:** [Specific achievements that support themes]
---
## 6. Competitive Positioning
### Leo's Unique Advantages
1. **[Advantage 1]:** [Description and impact]
2. **[Advantage 2]:** [Description and impact]
3. **[Advantage 3]:** [Description and impact]
### Potential Differentiators
- **Technical Depth:** [How Leo's technical skills exceed typical requirements]
- **Cross-Functional Value:** [How multiple skill areas create synergy]
- **Growth Trajectory:** [Self-taught journey demonstrates adaptability]
### Gap Mitigation Strategies
| Identified Gap | Mitigation Approach | Supporting Evidence |
|---|---|---|
| [Example: Formal ML education] | Emphasize practical application and continuous learning | Project portfolio, certifications, results achieved |
---
## 7. Application Strategy Recommendations
### Resume Optimization Priorities
1. **Lead with:** [Primary skill/experience to emphasize]
2. **Quantify:** [Specific achievements to highlight with metrics]
3. **Technical Focus:** [Key technologies to prominently feature]
4. **Experience Narrative:** [How to frame career progression]
### Cover Letter Strategy
1. **Opening Hook:** [Compelling way to start]
2. **Core Message:** [Central value proposition]
3. **Supporting Examples:** [2-3 specific achievements to highlight]
4. **Company Connection:** [How to demonstrate company-specific interest]
### Potential Red Flags to Address
- [Any concerns from gap analysis and how to proactively address them]
---
## 8. Phase 2 Handoff Information
### Resume Content Priorities (High to Low)
1. [Most important experiences/skills to feature prominently]
2. [Secondary content to include]
3. [Supporting content if space allows]
### Key Messages for Integration
- **Primary Value Prop:** [Main selling point]
- **Technical Emphasis:** [Technologies to highlight]
- **Achievement Focus:** [Quantifiable results to feature]
### Style Guidance
- **Tone:** [Professional, technical, innovative, etc.]
- **Emphasis:** [What aspects of background to stress]
- **Keywords:** [Critical terms for ATS optimization]
---
## 9. Research Quality Metrics
**Analysis Completeness:**
- Job requirements coverage: [X%]
- Skills assessment depth: [Comprehensive/Moderate/Basic]
- Company research depth: [Comprehensive/Moderate/Basic]
- Strategic insights quality: [High/Medium/Low]
**Evidence Base:**
- All assessments tied to resume evidence: [Yes/No]
- Transferability analysis completed: [Yes/No]
- Competitive advantages identified: [X advantages found]
**Source Documentation Quality:**
- Original job description preserved intact: [✅/❌]
- Formatting improvements applied appropriately: [✅/❌]
- Research version comprehensively categorized: [✅/❌]
- Cross-reference accuracy verified: [✅/❌]
**Readiness for Phase 2:**
- Clear content priorities established: [Yes/No]
- Strategic direction defined: [Yes/No]
- All handoff information complete: [Yes/No]
- Original source material available for reference: [✅/❌]
---
## 10. Final Validation Against Original Source
**Cross-Reference Check:**
- [ ] All analyzed requirements traced back to `original-job-description`
- [ ] No requirements missed or misinterpreted
- [ ] Analysis accurately reflects original posting intent
- [ ] Strategic recommendations align with actual job needs
**Original Source Integrity:**
- [ ] `original-job-description` contains exact text as provided
- [ ] Only formatting/organization improvements applied
- [ ] No content modifications or interpretations added
- [ ] Serves as reliable reference for future phases
---
**Phase 1 Status:** ✅ Complete
**Next Phase:** Resume Optimization
**Analyst:** Job Application Research Agent
**Review Required:** [Yes/No - pending user feedback]
**Documentation Archive:**
- ✅ `original-job-description` preserved and formatted
- ✅ `research-final-version` created and analyzed
- ✅ Strategic analysis completed
- ✅ Ready for Phase 2 handoff

172
docs/ai/research_prompt.md Normal file
View File

@@ -0,0 +1,172 @@
# Phase 1: Job Application Research Agent
You are an expert Job Application Research Agent, specialized in deep analysis of job descriptions and comprehensive candidate-role matching. You will conduct thorough research for Leo Miranda's job applications, leveraging his complete professional background and proven application strategies.
## Core Mission
Perform comprehensive research and analysis to understand job requirements, assess candidate fit, and identify strategic positioning opportunities for the application process.
## Available Resources
- **'complete_resume'**: Leo's comprehensive professional experience document
- **Files starting with 'Leonardo-Miranda'**: Past successful job applications for style and approach analysis
- **Web search capabilities**: For company research and job posting analysis
- **Leo's professional context**: Neurodivergent data scientist, Toronto-based, expertise in VPS/DevOps/AI web apps, Raspberry Pi enthusiast
## Research Workflow
### Step 1: Job Description Processing & Variable Creation
**CRITICAL FIRST STEP - Create Two Required Variables:**
**Variable 1: `original-job-description`**
- Capture the EXACT job description text as provided by the user
- Make NO content changes whatsoever - preserve every word, phrase, and detail
- ONLY apply formatting improvements:
- Clean up spacing and line breaks
- Add bullet points for better readability
- Add relevant icons (📋 for responsibilities, 🔧 for technical skills, etc.)
- Organize sections with headers if structure is unclear
- Fix obvious formatting issues (missing line breaks, inconsistent spacing)
- **RULE: Original meaning and text must remain 100% intact**
**Variable 2: `research-final-version`**
- This will contain your analytical processing and categorization
- Extract and organize information for analysis purposes
- This is where you apply your analytical framework
**Job Description Acquisition:**
**If URL provided:**
1. Use web_search to access and analyze the job posting
2. If link is inaccessible or insufficient, request full content from Leo
3. Create both variables from the acquired content
**If content provided directly:**
1. Create `original-job-description` with formatting-only improvements
2. Create `research-final-version` with analytical processing
3. Confirm completeness and request missing sections if needed
**Analysis Framework for `research-final-version`:**
- **Company/Department Profile**: Mission, culture, team structure, recent news
- **Role Definition**: Title, level, reporting structure, team dynamics
- **Core Responsibilities**: Primary duties, expected outcomes, project types
- **Technical Requirements**: Hard skills, tools, technologies, methodologies
- **Soft Skills**: Communication, leadership, collaboration requirements
- **Experience Criteria**: Years, industries, specific background preferences
- **Keywords Extraction**: Critical terms, buzzwords, industry language
- **Implicit Requirements**: Underlying expectations, cultural fit indicators
### Step 2: Comprehensive Skills Assessment
**Action:** Access 'complete_resume' via google_drive_search
Create detailed skills assessment table:
| Required Skill | Skill Type | Explicitly Met? | Evidence Location | Strength Level | Transferability Notes |
|---|---|---|---|---|---|
| [Skill] | Technical/Soft/Domain | Yes/Partial/No | [Resume Section] | Strong/Moderate/Developing | [How related skills apply] |
**Assessment Criteria:**
- **Explicitly Met**: Direct match found in resume
- **Partial**: Related experience that could transfer
- **Transferability Notes**: How Leo's adjacent skills could fulfill this requirement
### Step 3: Responsibilities Matching & Performance Analysis
Create comprehensive responsibilities analysis:
| Job Responsibility | Direct Experience | Related Experience | Performance Capability | Implementation Approach |
|---|---|---|---|---|
| [Responsibility] | Yes/No | [Description] | [1-5 scale] | [How Leo would execute this] |
**Performance Capability Scale:**
- 5: Expert level, immediate impact
- 4: Proficient, minimal ramp-up time
- 3: Competent, moderate learning curve
- 2: Developing, significant growth needed
- 1: Beginner, extensive training required
**Implementation Approach Examples:**
- "Could leverage Python automation skills for manual process optimization"
- "VPS/DevOps background enables infrastructure scaling responsibilities"
- "Data science expertise translates to business intelligence requirements"
### Step 4: Strategic Skill Transferability Analysis
**NEW REQUIREMENT**: Analyze how Leo's unique skill combination can address job requirements creatively:
**Hidden Value Opportunities:**
- Identify responsibilities that don't specify technical approaches
- Map Leo's technical skills to unspecified implementation methods
- Highlight cross-functional capabilities that exceed basic requirements
**Example Analysis:**
```
Job Requirement: "Automate reporting processes"
Leo's Advantage: "While job doesn't specify programming languages, Leo's Python expertise with pandas, SQL integration, and VBA skills enable sophisticated automation solutions beyond basic tools"
```
### Step 5: Company Intelligence Gathering
**Action:** Use web_search for company research
- Recent company news and developments
- Industry position and competitive landscape
- Company culture indicators from public content
- Leadership team background
- Recent initiatives or strategic directions
### Step 6: Competitive Positioning Analysis
**Determine Leo's unique value proposition:**
- Skill combinations that differentiate from typical candidates
- Experience intersections that solve multiple job requirements
- Technical depth that enables innovation beyond standard approaches
- Cross-domain expertise advantages
### Step 7: Application Strategy Recommendations
**Based on complete analysis:**
- Primary positioning strategy (how to present Leo's candidacy)
- Key messaging themes for resume and cover letter
- Specific achievements to emphasize
- Potential concerns to address proactively
- Unique value propositions to highlight
## Quality Standards
- **Accuracy**: All assessments must be evidence-based from resume content
- **Depth**: Go beyond surface-level matching to find strategic advantages
- **Specificity**: Provide concrete examples and implementation approaches
- **Honesty**: Acknowledge gaps while highlighting transferable strengths
- **Strategic**: Focus on positioning for maximum competitive advantage
## Output Requirements
Generate comprehensive research report using the standardized output format, ensuring:
**MANDATORY Variable Inclusion:**
1. **`original-job-description`**: Must be included in "Source Documentation" section
- Preserve 100% of original text content
- Apply ONLY formatting improvements (bullets, icons, spacing, headers)
- Serve as reference point for all analysis
2. **`research-final-version`**: Include in "Source Documentation" section
- Show your analytical processing and categorization
- Extract key elements for systematic analysis
- Cross-reference with original to ensure nothing is missed
**Documentation Standards:**
- Both variables must be clearly labeled and separated
- Original text integrity is paramount - any modifications beyond formatting are strictly prohibited
- Final report should seamlessly reference both versions
- All analysis must be traceable back to original source material
All other analysis documented for seamless handoff to Phase 2 (Resume Optimization).
## Operational Rules
1. **Evidence-Based**: Every assessment must reference specific resume content
2. **No Fabrication**: Never invent experiences or capabilities
3. **Original Preservation**: `original-job-description` must remain content-identical to user input
4. **Strategic Focus**: Emphasize competitive advantages and unique value
5. **Transferability**: Actively look for skill applications beyond obvious matches
6. **Completeness**: Address every significant job requirement
7. **Dual Documentation**: Always maintain both original and processed versions
8. **User Feedback**: Present findings for Leo's review and input before finalizing
**Success Metrics:**
- Complete coverage of all job requirements
- Strategic positioning identified
- Transferable skills mapped effectively
- Original job description perfectly preserved
- Clear handoff documentation for Phase 2
- Actionable insights for application strategy

100
docs/api_specification.md
View File

@@ -1,9 +1,9 @@
# JobForge MVP - API Specification
# Job Forge - FastAPI Web Application API Specification
**Version:** 1.0.0 MVP
**Base URL:** `http://localhost:8000`
**Target Audience:** Backend Developers
**Last Updated:** July 2025
**Version:** 1.0.0 Prototype
**Base URL:** `http://localhost:8000` (Development), `https://yourdomain.com` (Production)
**Target Audience:** Full-Stack Developers and API Consumers
**Last Updated:** August 2025
---
@@ -11,9 +11,10 @@
### Overview
- **Method:** JWT Bearer tokens
- **Token Expiry:** 24 hours
- **Refresh:** Not implemented in MVP (re-login required)
- **Token Expiry:** 24 hours (configurable)
- **Refresh:** Token refresh endpoint available
- **Header Format:** `Authorization: Bearer <jwt_token>`
- **Security:** HTTPS required in production
### Authentication Endpoints
@@ -25,18 +26,25 @@ Register new user account.
{
"email": "user@example.com",
"password": "SecurePass123!",
"full_name": "John Doe"
"first_name": "John",
"last_name": "Doe"
}
```
**Response (201):**
```json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "user@example.com",
"full_name": "John Doe",
"user": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"is_active": true,
"created_at": "2025-08-02T10:00:00Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
"token_type": "bearer",
"expires_in": 86400
}
```
@@ -58,11 +66,17 @@ Authenticate user and return JWT token.
**Response (200):**
```json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "user@example.com",
"full_name": "John Doe",
"user": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"is_active": true,
"created_at": "2025-08-02T10:00:00Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
"token_type": "bearer",
"expires_in": 86400
}
```
@@ -80,8 +94,28 @@ Get current user profile (requires authentication).
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "user@example.com",
"full_name": "John Doe",
"created_at": "2025-07-01T10:00:00Z"
"first_name": "John",
"last_name": "Doe",
"is_active": true,
"created_at": "2025-08-02T10:00:00Z",
"updated_at": "2025-08-02T10:00:00Z"
}
```
**Errors:**
- `401` - Invalid or expired token
#### POST /api/v1/auth/refresh
Refresh JWT access token.
**Headers:** `Authorization: Bearer <token>`
**Response (200):**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 86400
}
```
@@ -572,26 +606,46 @@ Delete resume from library.
## 🔧 Development Notes
### Rate Limiting (Future)
- Not implemented in MVP
- Will be added in Phase 2 for SaaS
### Environment Configuration
- Development: `http://localhost:8000`
- Production: HTTPS required with proper SSL certificates
- Environment variables for API keys and database connections
### Rate Limiting
- Implemented for AI endpoints to prevent abuse
- Authentication endpoints have basic rate limiting
- Configurable limits based on deployment environment
### Pagination
- Default limit: 50
- Maximum limit: 100
- Use `offset` for pagination
- Consider cursor-based pagination for future versions
### Content Validation
- Job description: 50-10000 characters
- Resume content: 100-50000 characters
- Names: 1-255 characters
- URLs: Valid HTTP/HTTPS format
- Email: RFC 5322 compliant
### Background Processing
- AI operations run asynchronously
- AI operations run asynchronously via background tasks
- Use `/processing/applications/{id}/status` to check progress
- Frontend should poll every 2-3 seconds during processing
- Proper error handling and retry mechanisms implemented
### Security Considerations
- JWT tokens signed with secure secret keys
- Row Level Security (RLS) enforced at database level
- Input validation and sanitization on all endpoints
- CORS properly configured for web application
### Monitoring and Logging
- Structured logging with request IDs
- Performance monitoring for AI service calls
- Error tracking and alerting configured
---
*This API specification covers all endpoints required for MVP implementation. Use the OpenAPI documentation at `/docs` for interactive testing during development.*
*This API specification covers all endpoints for the Job Forge web application. Interactive API documentation is available at `/docs` (Swagger UI) and `/redoc` (ReDoc) for development and testing.*

161
docs/database_design.md
View File

@@ -1,9 +1,9 @@
# JobForge MVP - Database Design & Schema
# Job Forge - Database Design & Schema
**Version:** 1.0.0 MVP
**Version:** 1.0.0 Prototype
**Database:** PostgreSQL 16 with pgvector
**Target Audience:** Backend Developers
**Last Updated:** July 2025
**Target Audience:** Full-Stack Developers
**Last Updated:** August 2025
---
@@ -11,17 +11,18 @@
### Technology Stack
- **Database:** PostgreSQL 16
- **Extensions:** pgvector (for AI embeddings)
- **Security:** Row Level Security (RLS) for multi-tenancy
- **Connection:** AsyncPG with SQLAlchemy 2.0
- **Migrations:** Direct SQL for MVP (Alembic in Phase 2)
- **Extensions:** pgvector (for AI embeddings), uuid-ossp (for UUID generation)
- **Security:** Row Level Security (RLS) for multi-tenant architecture
- **Connection:** AsyncPG with SQLAlchemy 2.0 async ORM
- **Migrations:** Alembic for database schema versioning
### Design Principles
- **User Isolation:** Complete data separation between users
- **Data Integrity:** Foreign key constraints and validation
- **Performance:** Optimized indexes for common queries
- **Security:** RLS policies prevent cross-user data access
- **Scalability:** Schema designed for future SaaS features
- **Multi-Tenancy:** Complete data isolation between users via RLS
- **Data Integrity:** Foreign key constraints and comprehensive validation
- **Performance:** Strategic indexes for query optimization
- **Security:** Defense-in-depth with RLS policies and input validation
- **Scalability:** Schema designed for horizontal scaling and future features
- **Maintainability:** Clear naming conventions and well-documented structure
---
@@ -38,27 +39,24 @@ erDiagram
uuid id PK
varchar email UK
varchar password_hash
varchar full_name
timestamp created_at
timestamp updated_at
varchar first_name
varchar last_name
boolean is_active
timestamptz created_at
timestamptz updated_at
}
APPLICATIONS {
uuid id PK
uuid user_id FK
varchar name
varchar company_name
varchar role_title
text job_url
text job_description
text job_url
varchar location
varchar priority_level
varchar status
boolean research_completed
boolean resume_optimized
boolean cover_letter_generated
timestamp created_at
timestamp updated_at
timestamptz created_at
timestamptz updated_at
}
DOCUMENTS {
@@ -66,8 +64,8 @@ erDiagram
uuid application_id FK
varchar document_type
text content
timestamp created_at
timestamp updated_at
timestamptz created_at
timestamptz updated_at
}
USER_RESUMES {
@@ -77,15 +75,15 @@ erDiagram
text content
varchar focus_area
boolean is_primary
timestamp created_at
timestamp updated_at
timestamptz created_at
timestamptz updated_at
}
DOCUMENT_EMBEDDINGS {
uuid id PK
uuid document_id FK
vector embedding
timestamp created_at
vector_1536 embedding
timestamptz created_at
}
```
@@ -100,12 +98,12 @@ CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS vector;
-- Create custom types
CREATE TYPE priority_level_type AS ENUM ('low', 'medium', 'high');
CREATE TYPE application_status_type AS ENUM (
'draft',
'research_complete',
'resume_ready',
'cover_letter_ready'
'draft',
'applied',
'interview',
'rejected',
'offer'
);
CREATE TYPE document_type_enum AS ENUM (
'research_report',
@@ -129,17 +127,21 @@ CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
full_name VARCHAR(255) NOT NULL,
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-- Constraints
CONSTRAINT email_format CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'),
CONSTRAINT name_not_empty CHECK (LENGTH(TRIM(full_name)) > 0)
CONSTRAINT first_name_not_empty CHECK (LENGTH(TRIM(first_name)) > 0),
CONSTRAINT last_name_not_empty CHECK (LENGTH(TRIM(last_name)) > 0)
);
-- Indexes
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_active ON users(is_active);
CREATE INDEX idx_users_created_at ON users(created_at);
-- Row Level Security
@@ -156,20 +158,13 @@ CREATE POLICY users_own_data ON users
CREATE TABLE applications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
company_name VARCHAR(255) NOT NULL,
role_title VARCHAR(255) NOT NULL,
job_url TEXT,
job_description TEXT NOT NULL,
job_url TEXT,
location VARCHAR(255),
priority_level priority_level_type DEFAULT 'medium',
status application_status_type DEFAULT 'draft',
-- Phase tracking
research_completed BOOLEAN DEFAULT FALSE,
resume_optimized BOOLEAN DEFAULT FALSE,
cover_letter_generated BOOLEAN DEFAULT FALSE,
-- Timestamps
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
@@ -181,21 +176,12 @@ CREATE TABLE applications (
CONSTRAINT valid_job_url CHECK (
job_url IS NULL OR
job_url ~* '^https?://[^\s/$.?#].[^\s]*$'
),
-- Business logic constraints
CONSTRAINT resume_requires_research CHECK (
NOT resume_optimized OR research_completed
),
CONSTRAINT cover_letter_requires_resume CHECK (
NOT cover_letter_generated OR resume_optimized
)
);
-- Indexes
CREATE INDEX idx_applications_user_id ON applications(user_id);
CREATE INDEX idx_applications_status ON applications(status);
CREATE INDEX idx_applications_priority ON applications(priority_level);
CREATE INDEX idx_applications_created_at ON applications(created_at);
CREATE INDEX idx_applications_company_name ON applications(company_name);
@@ -420,48 +406,26 @@ BEGIN
END;
$$ LANGUAGE plpgsql;
-- Update application phases trigger
CREATE OR REPLACE FUNCTION update_application_phases()
-- Application status validation function
CREATE OR REPLACE FUNCTION validate_application_status()
RETURNS TRIGGER AS $$
BEGIN
-- Auto-update phase completion based on document existence
IF TG_OP = 'INSERT' OR TG_OP = 'UPDATE' THEN
UPDATE applications SET
research_completed = EXISTS (
SELECT 1 FROM documents
WHERE application_id = NEW.application_id
AND document_type = 'research_report'
),
resume_optimized = EXISTS (
SELECT 1 FROM documents
WHERE application_id = NEW.application_id
AND document_type = 'optimized_resume'
),
cover_letter_generated = EXISTS (
SELECT 1 FROM documents
WHERE application_id = NEW.application_id
AND document_type = 'cover_letter'
)
WHERE id = NEW.application_id;
-- Update status based on completion
UPDATE applications SET
status = CASE
WHEN cover_letter_generated THEN 'cover_letter_ready'
WHEN resume_optimized THEN 'resume_ready'
WHEN research_completed THEN 'research_complete'
ELSE 'draft'
END
WHERE id = NEW.application_id;
-- Ensure status transitions are logical
IF NEW.status = OLD.status THEN
RETURN NEW;
END IF;
RETURN COALESCE(NEW, OLD);
-- Log status changes for audit purposes
RAISE NOTICE 'Application % status changed from % to %',
NEW.id, OLD.status, NEW.status;
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER documents_update_phases
AFTER INSERT OR UPDATE OR DELETE ON documents
FOR EACH ROW EXECUTE FUNCTION update_application_phases();
CREATE TRIGGER validate_application_status_trigger
BEFORE UPDATE ON applications
FOR EACH ROW EXECUTE FUNCTION validate_application_status();
```
---
@@ -518,11 +482,13 @@ engine = create_async_engine(
### Development Seed Data
```sql
-- Insert test user (password: "testpass123")
INSERT INTO users (id, email, password_hash, full_name) VALUES (
INSERT INTO users (id, email, password_hash, first_name, last_name, is_active) VALUES (
'123e4567-e89b-12d3-a456-426614174000',
'test@example.com',
'$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewgdyN8yF5V4M2kq',
'Test User'
'Test',
'User',
true
);
-- Insert test resume
@@ -536,16 +502,15 @@ INSERT INTO user_resumes (user_id, name, content, focus_area, is_primary) VALUES
-- Insert test application
INSERT INTO applications (
user_id, name, company_name, role_title,
job_description, status, research_completed
user_id, company_name, role_title,
job_description, job_url, status
) VALUES (
'123e4567-e89b-12d3-a456-426614174000',
'google_senior_developer_2025_07_01',
'Google',
'Senior Developer',
'We are seeking an experienced software developer to join our team...',
'research_complete',
true
'We are seeking an experienced software developer to join our team building cutting-edge applications. You will work with Python, FastAPI, and modern web technologies.',
'https://careers.google.com/jobs/results/123456789/',
'draft'
);
```
@@ -648,4 +613,4 @@ GROUP BY state;
---
*This database design provides a solid foundation for the MVP while being prepared for future SaaS features. The RLS policies ensure complete user data isolation, and the schema is optimized for the expected query patterns.*
*This database design provides a robust foundation for the Job Forge web application with strong security, performance optimization, and scalability. The RLS policies ensure complete multi-tenant data isolation, while the schema supports efficient AI-powered document generation workflows.*

894
docs/development/coding_standards.md Normal file
View File

@@ -0,0 +1,894 @@
# Coding Standards - Job Forge
## Overview
This document outlines the coding standards and best practices for the Job Forge Python/FastAPI web application. Following these standards ensures code consistency, maintainability, and quality across the project.
## Python Code Style
### 1. PEP 8 Compliance
Job Forge follows [PEP 8](https://pep8.org/) with the following tools:
- **Black** for code formatting
- **Ruff** for linting and import sorting
- **mypy** for type checking
### 2. Code Formatting with Black
```bash
# Install black
pip install black
# Format all Python files
black .
# Check formatting without making changes
black --check .
# Format specific file
black app/main.py
```
#### Black Configuration (.pyproject.toml)
```toml
[tool.black]
line-length = 88
target-version = ['py312']
include = '\.pyi?$'
extend-exclude = '''
/(
# directories
\.eggs
| \.git
| \.hg
| \.mypy_cache
| \.tox
| \.venv
| build
| dist
)/
'''
```
### 3. Linting with Ruff
```bash
# Install ruff
pip install ruff
# Lint all files
ruff check .
# Fix auto-fixable issues
ruff check --fix .
# Check specific file
ruff check app/main.py
```
#### Ruff Configuration (.pyproject.toml)
```toml
[tool.ruff]
target-version = "py312"
line-length = 88
select = [
"E", # pycodestyle errors
"W", # pycodestyle warnings
"F", # pyflakes
"I", # isort
"B", # flake8-bugbear
"C4", # flake8-comprehensions
"UP", # pyupgrade
]
ignore = [
"E501", # line too long, handled by black
"B008", # do not perform function calls in argument defaults
"C901", # too complex
]
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".hg",
".mypy_cache",
".nox",
".pants.d",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"venv",
]
[tool.ruff.mccabe]
max-complexity = 10
[tool.ruff.isort]
known-first-party = ["app"]
```
### 4. Type Checking with mypy
```bash
# Install mypy
pip install mypy
# Check types
mypy app/
# Check specific file
mypy app/main.py
```
#### mypy Configuration (mypy.ini)
```ini
[mypy]
python_version = 3.12
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
disallow_incomplete_defs = True
check_untyped_defs = True
disallow_untyped_decorators = True
no_implicit_optional = True
warn_redundant_casts = True
warn_unused_ignores = True
warn_no_return = True
warn_unreachable = True
strict_equality = True
[mypy-tests.*]
disallow_untyped_defs = False
disallow_incomplete_defs = False
[mypy-alembic.*]
ignore_errors = True
```
## FastAPI Coding Standards
### 1. API Endpoint Structure
```python
# Good: Clear, consistent endpoint structure
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from typing import List
from app.core.database import get_db
from app.core.security import get_current_user
from app.models.user import User
from app.schemas.application import ApplicationCreate, ApplicationResponse
from app.crud.application import create_application, get_user_applications
router = APIRouter(prefix="/api/v1/applications", tags=["applications"])
@router.post("/", response_model=ApplicationResponse, status_code=status.HTTP_201_CREATED)
async def create_job_application(
application_data: ApplicationCreate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> ApplicationResponse:
"""
Create a new job application with AI-generated cover letter.
Args:
application_data: Application creation data
current_user: Authenticated user from JWT token
db: Database session
Returns:
Created application with generated content
Raises:
HTTPException: If application creation fails
"""
try:
application = await create_application(db, application_data, current_user.id)
return ApplicationResponse.from_orm(application)
except Exception as e:
logger.error(f"Failed to create application: {str(e)}")
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="Failed to create application"
)
@router.get("/", response_model=List[ApplicationResponse])
async def get_applications(
skip: int = 0,
limit: int = 100,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> List[ApplicationResponse]:
"""Get user's job applications with pagination."""
applications = await get_user_applications(
db, user_id=current_user.id, skip=skip, limit=limit
)
return [ApplicationResponse.from_orm(app) for app in applications]
```
### 2. Error Handling Standards
```python
# Good: Consistent error handling
from app.core.exceptions import JobForgeException
class ApplicationNotFoundError(JobForgeException):
"""Raised when application is not found."""
pass
class ApplicationAccessDeniedError(JobForgeException):
"""Raised when user doesn't have access to application."""
pass
@router.get("/{application_id}", response_model=ApplicationResponse)
async def get_application(
application_id: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> ApplicationResponse:
"""Get specific job application by ID."""
try:
application = await get_application_by_id(db, application_id, current_user.id)
if not application:
raise ApplicationNotFoundError(f"Application {application_id} not found")
return ApplicationResponse.from_orm(application)
except ApplicationNotFoundError:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Application not found"
)
except Exception as e:
logger.error(f"Error retrieving application {application_id}: {str(e)}")
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="Internal server error"
)
```
### 3. Dependency Injection
```python
# Good: Proper dependency injection
from app.services.ai.claude_service import ClaudeService
from app.services.ai.openai_service import OpenAIService
async def get_claude_service() -> ClaudeService:
"""Dependency for Claude AI service."""
return ClaudeService()
async def get_openai_service() -> OpenAIService:
"""Dependency for OpenAI service."""
return OpenAIService()
@router.post("/{application_id}/generate-cover-letter")
async def generate_cover_letter(
application_id: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
claude_service: ClaudeService = Depends(get_claude_service),
) -> dict:
"""Generate AI cover letter for application."""
application = await get_application_by_id(db, application_id, current_user.id)
if not application:
raise HTTPException(status_code=404, detail="Application not found")
cover_letter = await claude_service.generate_cover_letter(
user_profile=current_user.profile,
job_description=application.job_description
)
application.cover_letter = cover_letter
await db.commit()
return {"cover_letter": cover_letter}
```
## Pydantic Model Standards
### 1. Schema Definitions
```python
# Good: Clear schema definitions with validation
from pydantic import BaseModel, Field, EmailStr, validator
from typing import Optional, List
from datetime import datetime
from enum import Enum
class ApplicationStatus(str, Enum):
"""Application status enumeration."""
DRAFT = "draft"
APPLIED = "applied"
INTERVIEW = "interview"
REJECTED = "rejected"
OFFER = "offer"
class ApplicationBase(BaseModel):
"""Base application schema."""
company_name: str = Field(..., min_length=1, max_length=255, description="Company name")
role_title: str = Field(..., min_length=1, max_length=255, description="Job role title")
job_description: Optional[str] = Field(None, max_length=5000, description="Job description")
status: ApplicationStatus = Field(ApplicationStatus.DRAFT, description="Application status")
class ApplicationCreate(ApplicationBase):
"""Schema for creating applications."""
@validator('company_name')
def validate_company_name(cls, v):
if not v.strip():
raise ValueError('Company name cannot be empty')
return v.strip()
@validator('role_title')
def validate_role_title(cls, v):
if not v.strip():
raise ValueError('Role title cannot be empty')
return v.strip()
class ApplicationUpdate(BaseModel):
"""Schema for updating applications."""
company_name: Optional[str] = Field(None, min_length=1, max_length=255)
role_title: Optional[str] = Field(None, min_length=1, max_length=255)
job_description: Optional[str] = Field(None, max_length=5000)
status: Optional[ApplicationStatus] = None
class ApplicationResponse(ApplicationBase):
"""Schema for application responses."""
id: str = Field(..., description="Application ID")
user_id: str = Field(..., description="User ID")
cover_letter: Optional[str] = Field(None, description="Generated cover letter")
created_at: datetime = Field(..., description="Creation timestamp")
updated_at: datetime = Field(..., description="Last update timestamp")
class Config:
from_attributes = True # For SQLAlchemy model conversion
```
### 2. Model Validation
```python
# Good: Custom validation methods
from pydantic import BaseModel, validator, root_validator
import re
class UserCreate(BaseModel):
"""User creation schema with validation."""
email: EmailStr
password: str = Field(..., min_length=8, max_length=128)
first_name: str = Field(..., min_length=1, max_length=50)
last_name: str = Field(..., min_length=1, max_length=50)
@validator('password')
def validate_password_strength(cls, v):
"""Validate password strength."""
if len(v) < 8:
raise ValueError('Password must be at least 8 characters long')
if not re.search(r'[A-Z]', v):
raise ValueError('Password must contain at least one uppercase letter')
if not re.search(r'[a-z]', v):
raise ValueError('Password must contain at least one lowercase letter')
if not re.search(r'\d', v):
raise ValueError('Password must contain at least one digit')
return v
@validator('first_name', 'last_name')
def validate_names(cls, v):
"""Validate name fields."""
if not v.strip():
raise ValueError('Name cannot be empty')
if not re.match(r'^[a-zA-Z\s\'-]+$', v):
raise ValueError('Name contains invalid characters')
return v.strip().title()
```
## Database Model Standards
### 1. SQLAlchemy Models
```python
# Good: Well-structured SQLAlchemy models
from sqlalchemy import Column, String, Text, DateTime, ForeignKey, Enum
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import relationship
from sqlalchemy.sql import func
import uuid
from app.core.database import Base
from app.models.application import ApplicationStatus
class User(Base):
"""User model with proper relationships and constraints."""
__tablename__ = "users"
id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4, index=True)
email = Column(String(255), unique=True, nullable=False, index=True)
password_hash = Column(String(255), nullable=False)
first_name = Column(String(100), nullable=False)
last_name = Column(String(100), nullable=False)
is_active = Column(Boolean, default=True, nullable=False)
created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
# Relationships
applications = relationship("Application", back_populates="user", cascade="all, delete-orphan")
def __repr__(self) -> str:
return f"<User(id={self.id}, email={self.email})>"
class Application(Base):
"""Application model with RLS and proper indexing."""
__tablename__ = "applications"
id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4, index=True)
user_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
company_name = Column(String(255), nullable=False, index=True)
role_title = Column(String(255), nullable=False)
job_description = Column(Text)
cover_letter = Column(Text)
status = Column(Enum(ApplicationStatus), default=ApplicationStatus.DRAFT, nullable=False, index=True)
created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)
updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
# Relationships
user = relationship("User", back_populates="applications")
def __repr__(self) -> str:
return f"<Application(id={self.id}, company={self.company_name}, status={self.status})>"
```
### 2. Database Operations (CRUD)
```python
# Good: Async database operations with proper error handling
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select, update, delete
from sqlalchemy.orm import selectinload
from typing import Optional, List
from app.models.application import Application
from app.schemas.application import ApplicationCreate, ApplicationUpdate
async def create_application(
db: AsyncSession,
application_data: ApplicationCreate,
user_id: str
) -> Application:
"""Create a new job application."""
application = Application(
user_id=user_id,
**application_data.dict()
)
db.add(application)
await db.commit()
await db.refresh(application)
return application
async def get_application_by_id(
db: AsyncSession,
application_id: str,
user_id: str
) -> Optional[Application]:
"""Get application by ID with user validation."""
query = select(Application).where(
Application.id == application_id,
Application.user_id == user_id
)
result = await db.execute(query)
return result.scalar_one_or_none()
async def get_user_applications(
db: AsyncSession,
user_id: str,
skip: int = 0,
limit: int = 100,
status_filter: Optional[ApplicationStatus] = None
) -> List[Application]:
"""Get user applications with filtering and pagination."""
query = select(Application).where(Application.user_id == user_id)
if status_filter:
query = query.where(Application.status == status_filter)
query = query.offset(skip).limit(limit).order_by(Application.created_at.desc())
result = await db.execute(query)
return list(result.scalars().all())
async def update_application(
db: AsyncSession,
application_id: str,
application_data: ApplicationUpdate,
user_id: str
) -> Optional[Application]:
"""Update application with user validation."""
# Update only provided fields
update_data = application_data.dict(exclude_unset=True)
if not update_data:
return None
query = (
update(Application)
.where(Application.id == application_id, Application.user_id == user_id)
.values(**update_data)
.returning(Application)
)
result = await db.execute(query)
await db.commit()
return result.scalar_one_or_none()
```
## Async Programming Standards
### 1. Async/Await Usage
```python
# Good: Proper async/await usage
import asyncio
from typing import List, Optional
async def process_multiple_applications(
applications: List[Application],
ai_service: ClaudeService
) -> List[str]:
"""Process multiple applications concurrently."""
async def process_single_application(app: Application) -> str:
"""Process a single application."""
if not app.job_description:
return ""
return await ai_service.generate_cover_letter(
user_profile=app.user.profile,
job_description=app.job_description
)
# Process applications concurrently
tasks = [process_single_application(app) for app in applications]
results = await asyncio.gather(*tasks, return_exceptions=True)
# Handle exceptions
cover_letters = []
for i, result in enumerate(results):
if isinstance(result, Exception):
logger.error(f"Failed to process application {applications[i].id}: {result}")
cover_letters.append("")
else:
cover_letters.append(result)
return cover_letters
```
### 2. Context Managers
```python
# Good: Proper async context manager usage
from contextlib import asynccontextmanager
from typing import AsyncGenerator
@asynccontextmanager
async def get_ai_service_with_retry(
max_retries: int = 3
) -> AsyncGenerator[ClaudeService, None]:
"""Context manager for AI service with retry logic."""
service = ClaudeService()
retries = 0
try:
while retries < max_retries:
try:
await service.test_connection()
yield service
break
except Exception as e:
retries += 1
if retries >= max_retries:
raise e
await asyncio.sleep(2 ** retries) # Exponential backoff
finally:
await service.close()
# Usage
async def generate_with_retry(job_description: str) -> str:
async with get_ai_service_with_retry() as ai_service:
return await ai_service.generate_cover_letter(
user_profile={},
job_description=job_description
)
```
## Testing Standards
### 1. Test Structure
```python
# Good: Well-structured tests
import pytest
from httpx import AsyncClient
from unittest.mock import AsyncMock, patch
class TestApplicationAPI:
"""Test suite for application API endpoints."""
@pytest.mark.asyncio
async def test_create_application_success(
self,
async_client: AsyncClient,
test_user_token: str
):
"""Test successful application creation."""
# Arrange
application_data = {
"company_name": "Test Corp",
"role_title": "Software Developer",
"job_description": "Python developer position",
"status": "draft"
}
headers = {"Authorization": f"Bearer {test_user_token}"}
# Act
response = await async_client.post(
"/api/v1/applications/",
json=application_data,
headers=headers
)
# Assert
assert response.status_code == 201
data = response.json()
assert data["company_name"] == "Test Corp"
assert data["role_title"] == "Software Developer"
assert data["status"] == "draft"
assert "id" in data
assert "created_at" in data
@pytest.mark.asyncio
async def test_create_application_with_ai_generation(
self,
async_client: AsyncClient,
test_user_token: str,
mock_claude_service: AsyncMock
):
"""Test application creation with AI cover letter generation."""
# Arrange
mock_claude_service.generate_cover_letter.return_value = "Mock cover letter"
application_data = {
"company_name": "AI Corp",
"role_title": "ML Engineer",
"job_description": "Machine learning position with Python",
"status": "draft"
}
headers = {"Authorization": f"Bearer {test_user_token}"}
# Act
with patch('app.services.ai.claude_service.ClaudeService', return_value=mock_claude_service):
response = await async_client.post(
"/api/v1/applications/",
json=application_data,
headers=headers
)
# Assert
assert response.status_code == 201
data = response.json()
assert data["cover_letter"] == "Mock cover letter"
mock_claude_service.generate_cover_letter.assert_called_once()
```
### 2. Test Fixtures
```python
# Good: Reusable test fixtures
import pytest
from typing import AsyncGenerator
from httpx import AsyncClient
from fastapi.testclient import TestClient
@pytest.fixture
async def test_application(
test_db: AsyncSession,
test_user: User
) -> Application:
"""Create a test application."""
from app.crud.application import create_application
from app.schemas.application import ApplicationCreate
app_data = ApplicationCreate(
company_name="Test Company",
role_title="Test Role",
job_description="Test job description",
status="draft"
)
application = await create_application(test_db, app_data, test_user.id)
await test_db.commit()
return application
@pytest.fixture
def mock_ai_services():
"""Mock all AI services."""
with patch('app.services.ai.claude_service.ClaudeService') as mock_claude, \
patch('app.services.ai.openai_service.OpenAIService') as mock_openai:
mock_claude.return_value.generate_cover_letter = AsyncMock(
return_value="Mock cover letter"
)
mock_openai.return_value.create_embedding = AsyncMock(
return_value=[0.1] * 1536
)
yield {
'claude': mock_claude.return_value,
'openai': mock_openai.return_value
}
```
## Documentation Standards
### 1. Docstring Format
```python
# Good: Comprehensive docstrings
def calculate_job_match_score(
user_skills: List[str],
job_requirements: List[str],
experience_years: int
) -> float:
"""
Calculate job match score based on skills and experience.
Args:
user_skills: List of user's skills
job_requirements: List of job requirements
experience_years: Years of relevant experience
Returns:
Match score between 0.0 and 1.0
Raises:
ValueError: If experience_years is negative
Example:
>>> calculate_job_match_score(
... ["Python", "FastAPI"],
... ["Python", "Django"],
... 3
... )
0.75
"""
if experience_years < 0:
raise ValueError("Experience years cannot be negative")
# Implementation...
return 0.75
```
### 2. API Documentation
```python
# Good: Comprehensive API documentation
@router.post(
"/",
response_model=ApplicationResponse,
status_code=status.HTTP_201_CREATED,
summary="Create job application",
description="Create a new job application with optional AI-generated cover letter",
responses={
201: {"description": "Application created successfully"},
400: {"description": "Invalid application data"},
401: {"description": "Authentication required"},
422: {"description": "Validation error"},
500: {"description": "Internal server error"}
}
)
async def create_job_application(
application_data: ApplicationCreate = Body(
...,
example={
"company_name": "Google",
"role_title": "Senior Python Developer",
"job_description": "We are looking for an experienced Python developer...",
"status": "draft"
}
),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> ApplicationResponse:
"""Create a new job application."""
# Implementation...
```
## Performance Standards
### 1. Database Query Optimization
```python
# Good: Optimized database queries
async def get_applications_with_stats(
db: AsyncSession,
user_id: str
) -> dict:
"""Get applications with statistics in a single query."""
from sqlalchemy import func, case
query = select(
func.count(Application.id).label('total_applications'),
func.count(case((Application.status == 'applied', 1))).label('applied_count'),
func.count(case((Application.status == 'interview', 1))).label('interview_count'),
func.count(case((Application.status == 'offer', 1))).label('offer_count'),
func.avg(
case((Application.created_at.isnot(None),
func.extract('epoch', func.now() - Application.created_at)))
).label('avg_age_days')
).where(Application.user_id == user_id)
result = await db.execute(query)
row = result.first()
return {
'total_applications': row.total_applications or 0,
'applied_count': row.applied_count or 0,
'interview_count': row.interview_count or 0,
'offer_count': row.offer_count or 0,
'avg_age_days': round((row.avg_age_days or 0) / 86400, 1) # Convert to days
}
```
### 2. Caching Strategies
```python
# Good: Implement caching for expensive operations
from functools import lru_cache
from typing import Dict, Any
import asyncio
@lru_cache(maxsize=128)
def get_job_keywords(job_description: str) -> List[str]:
"""Extract keywords from job description (cached)."""
# Expensive NLP processing here
return extract_keywords(job_description)
class CachedAIService:
"""AI service with caching."""
def __init__(self):
self._cache: Dict[str, Any] = {}
self._cache_ttl = 3600 # 1 hour
async def generate_cover_letter_cached(
self,
user_profile: dict,
job_description: str
) -> str:
"""Generate cover letter with caching."""
cache_key = f"{hash(str(user_profile))}_{hash(job_description)}"
if cache_key in self._cache:
cached_result, timestamp = self._cache[cache_key]
if time.time() - timestamp < self._cache_ttl:
return cached_result
# Generate new cover letter
result = await self.generate_cover_letter(user_profile, job_description)
# Cache result
self._cache[cache_key] = (result, time.time())
return result
```
These coding standards ensure that Job Forge maintains high code quality, consistency, and performance across all components of the application.

446
docs/development_setup.md
View File

@@ -1,446 +0,0 @@
# JobForge MVP - Development Setup Guide
**Version:** 1.0.0 MVP
**Target Audience:** Developers
**Last Updated:** July 2025
---
## 🎯 Prerequisites
### Required Software
- **Docker Desktop** 4.20+ with Docker Compose
- **Git** 2.30+
- **Text Editor** (VS Code recommended)
- **API Keys** (Claude, OpenAI)
### System Requirements
- **RAM:** 8GB minimum (Docker containers + database)
- **Storage:** 10GB free space
- **OS:** Windows 10+, macOS 12+, or Linux
---
## 🚀 Quick Start (5 Minutes)
### 1. Clone Repository
```bash
git clone https://github.com/your-org/jobforge-mvp.git
cd jobforge-mvp
```
### 2. Environment Configuration
```bash
# Copy environment template
cp .env.example .env
# Edit .env file with your API keys
nano .env # or use your preferred editor
```
**Required Environment Variables:**
```bash
# API Keys (REQUIRED)
CLAUDE_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
# Database (Auto-configured for local development)
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
# JWT Secret (Generate random string)
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
# Development Settings
DEBUG=true
LOG_LEVEL=INFO
```
### 3. Start Development Environment
```bash
# Start all services (PostgreSQL, Backend, Frontend)
docker-compose up -d
# View logs to ensure everything started correctly
docker-compose logs -f
```
### 4. Verify Installation
- **Frontend:** http://localhost:8501
- **Backend API:** http://localhost:8000
- **API Documentation:** http://localhost:8000/docs
- **Database:** localhost:5432
---
## 🔧 Detailed Setup Instructions
### Getting API Keys
#### Claude API Key
1. Visit https://console.anthropic.com/
2. Create account or log in
3. Go to "API Keys" section
4. Create new key with name "JobForge Development"
5. Copy key to `.env` file
#### OpenAI API Key
1. Visit https://platform.openai.com/api-keys
2. Create account or log in
3. Click "Create new secret key"
4. Name it "JobForge Development"
5. Copy key to `.env` file
### Environment File Setup
```bash
# .env file (copy from .env.example)
# =============================================================================
# API KEYS - REQUIRED FOR DEVELOPMENT
# =============================================================================
CLAUDE_API_KEY=sk-ant-api03-xxx...
OPENAI_API_KEY=sk-xxx...
# =============================================================================
# DATABASE CONFIGURATION
# =============================================================================
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
POSTGRES_DB=jobforge_mvp
POSTGRES_USER=jobforge_user
POSTGRES_PASSWORD=jobforge_password
# =============================================================================
# AUTHENTICATION
# =============================================================================
JWT_SECRET_KEY=super-secret-jwt-key-minimum-32-characters-long
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24
# =============================================================================
# APPLICATION SETTINGS
# =============================================================================
DEBUG=true
LOG_LEVEL=INFO
BACKEND_URL=http://backend:8000
# =============================================================================
# AI PROCESSING SETTINGS
# =============================================================================
CLAUDE_MODEL=claude-sonnet-4-20250514
OPENAI_EMBEDDING_MODEL=text-embedding-3-large
MAX_PROCESSING_TIME_SECONDS=120
```
---
## 🐳 Docker Setup
### Docker Compose Configuration
The `docker-compose.yml` file configures three main services:
#### PostgreSQL Database
- **Port:** 5432
- **Database:** jobforge_mvp
- **Extensions:** pgvector for AI embeddings
- **Data:** Persisted in Docker volume
#### Backend API (FastAPI)
- **Port:** 8000
- **Auto-reload:** Enabled for development
- **API Docs:** http://localhost:8000/docs
#### Frontend App (Dash)
- **Port:** 8501
- **Auto-reload:** Enabled for development
### Docker Commands
#### Start Services
```bash
# Start all services in background
docker-compose up -d
# Start with logs visible
docker-compose up
# Start specific service
docker-compose up backend
```
#### View Logs
```bash
# All services logs
docker-compose logs -f
# Specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
```
#### Stop Services
```bash
# Stop all services
docker-compose down
# Stop and remove volumes (WARNING: Deletes database data)
docker-compose down -v
```
#### Rebuild Services
```bash
# Rebuild after code changes
docker-compose build
# Rebuild specific service
docker-compose build backend
# Rebuild and restart
docker-compose up --build
```
---
## 🗄️ Database Setup
### Automatic Database Initialization
The database is automatically set up when you first run `docker-compose up`:
1. **PostgreSQL starts** with pgvector extension
2. **Database created** with name `jobforge_mvp`
3. **Tables created** from `database/init.sql`
4. **Row Level Security** policies applied
5. **Sample data** inserted (optional)
### Manual Database Operations
#### Connect to Database
```bash
# Connect via Docker
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
# Connect from host (if PostgreSQL client installed)
psql -h localhost -p 5432 -U jobforge_user -d jobforge_mvp
```
#### Reset Database
```bash
# WARNING: This deletes all data
docker-compose down -v
docker-compose up -d postgres
```
#### Database Migrations (Future)
```bash
# When Alembic is added
docker-compose exec backend alembic upgrade head
```
### Database Schema Verification
After startup, verify tables exist:
```sql
-- Connect to database and run:
\dt
-- Expected tables:
-- users
-- applications
-- documents
-- user_resumes
-- document_embeddings
```
---
## 🔍 Development Workflow
### Code Organization
```
src/
├── backend/ # FastAPI backend code
│ ├── main.py # FastAPI app entry point
│ ├── api/ # API route handlers
│ ├── services/ # Business logic
│ ├── database/ # Database models and connection
│ └── models/ # Pydantic request/response models
├── frontend/ # Dash frontend code
│ ├── main.py # Dash app entry point
│ ├── components/ # Reusable UI components
│ ├── pages/ # Page components
│ └── api_client/ # Backend API client
├── agents/ # AI processing agents
└── helpers/ # Shared utilities
```
### Making Code Changes
#### Backend Changes
1. **Modify code** in `src/backend/`
2. **FastAPI auto-reloads** automatically
3. **Test changes** at http://localhost:8000/docs
#### Frontend Changes
1. **Modify code** in `src/frontend/`
2. **Dash auto-reloads** automatically
3. **Test changes** at http://localhost:8501
#### Database Changes
1. **Modify** `database/init.sql`
2. **Reset database:** `docker-compose down -v && docker-compose up -d`
### Testing Your Setup
#### 1. Backend Health Check
```bash
curl http://localhost:8000/health
# Expected: {"status": "healthy", "service": "jobforge-backend"}
```
#### 2. Database Connection
```bash
curl http://localhost:8000/api/v1/auth/me
# Expected: {"detail": "Not authenticated"} (this is correct - no token)
```
#### 3. Frontend Access
Visit http://localhost:8501 - should see login page
#### 4. API Documentation
Visit http://localhost:8000/docs - should see Swagger UI
---
## 🐛 Troubleshooting
### Common Issues
#### "Port already in use"
```bash
# Check what's using the port
lsof -i :8501 # or :8000, :5432
# Kill the process or change ports in docker-compose.yml
```
#### "API Key Invalid"
```bash
# Verify API key format
echo $CLAUDE_API_KEY # Should start with "sk-ant-api03-"
echo $OPENAI_API_KEY # Should start with "sk-"
# Test API key manually
curl -H "Authorization: Bearer $CLAUDE_API_KEY" https://api.anthropic.com/v1/messages
```
#### "Database Connection Failed"
```bash
# Check if PostgreSQL is running
docker-compose ps postgres
# Check database logs
docker-compose logs postgres
# Try connecting manually
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
```
#### "Frontend Won't Load"
```bash
# Check frontend logs
docker-compose logs frontend
# Common issue: Backend not ready
curl http://localhost:8000/health
# Restart frontend
docker-compose restart frontend
```
#### "AI Processing Fails"
```bash
# Check backend logs for API errors
docker-compose logs backend | grep -i error
# Verify API keys are loaded
docker-compose exec backend env | grep API_KEY
```
### Development Tips
#### Hot Reloading
- Both backend and frontend support hot reloading
- Database schema changes require full restart
- Environment variable changes require restart
#### Debugging
```bash
# Backend debugging with detailed logs
DEBUG=true LOG_LEVEL=DEBUG docker-compose up backend
# Frontend debugging
docker-compose exec frontend python src/frontend/main.py --debug
```
#### Performance Monitoring
```bash
# View container resource usage
docker stats
# View database performance
docker-compose exec postgres pg_stat_activity
```
---
## 📊 Development Tools
### Recommended VS Code Extensions
- **Python** (Microsoft)
- **Docker** (Microsoft)
- **PostgreSQL** (Chris Kolkman)
- **REST Client** (Huachao Mao)
- **GitLens** (GitKraken)
### API Testing Tools
- **Built-in Swagger UI:** http://localhost:8000/docs
- **curl commands** (see API specification)
- **Postman** (import OpenAPI spec from `/openapi.json`)
### Database Tools
- **pgAdmin** (web-based PostgreSQL admin)
- **DBeaver** (database IDE)
- **psql** (command line client)
---
## 🚀 Next Steps
Once your environment is running:
1. **Create test account** at http://localhost:8501
2. **Review API documentation** at http://localhost:8000/docs
3. **Follow Database Design** document for schema details
4. **Check Testing Strategy** document for testing approach
5. **Start development** following the 8-week roadmap
---
## 📞 Getting Help
### Development Issues
- Check this troubleshooting section first
- Review Docker logs: `docker-compose logs`
- Verify environment variables: `docker-compose exec backend env`
### API Issues
- Use Swagger UI for interactive testing
- Check API specification document
- Verify authentication headers
### Database Issues
- Connect directly: `docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp`
- Check database logs: `docker-compose logs postgres`
- Review database design document
---
*This setup guide should get you from zero to a working development environment in under 10 minutes. If you encounter issues not covered here, please update this document for future developers.*

631
docs/git_branch_strategy.md
View File

@@ -1,631 +0,0 @@
# JobForge MVP - Git Branch Management Strategy
**Version:** 1.0.0 MVP
**Repository:** Single monorepo approach
**Platform:** Gitea
**Target Audience:** Development Team
**Last Updated:** July 2025
---
## 🎯 Branching Strategy Overview
### Repository Structure
**Single Monorepo** containing:
- Frontend (Dash + Mantine)
- Backend (FastAPI)
- Database schemas and migrations
- Docker configuration
- Documentation
- Tests
### Core Branching Model
```
main (production-ready)
├── develop (integration branch)
│ ├── feature/user-authentication
│ ├── feature/job-application-crud
│ ├── feature/ai-research-agent
│ ├── feature/resume-optimization
│ └── feature/cover-letter-generator
├── hotfix/critical-security-patch
└── release/v1.0.0-mvp
```
---
## 🌿 Branch Types & Purposes
### 1. **main** (Production Branch)
- **Purpose:** Production-ready code only
- **Protection:** Fully protected, requires PR approval
- **Deployment:** Auto-deploys to production environment
- **Merge Strategy:** Squash and merge from release branches only
**Rules:**
- No direct commits allowed
- All changes via Pull Request from `develop` or `hotfix/*`
- Must pass all CI/CD checks
- Requires at least 1 code review approval
- Must be deployable at any time
### 2. **develop** (Integration Branch)
- **Purpose:** Integration of completed features
- **Protection:** Protected, requires PR approval
- **Deployment:** Auto-deploys to staging environment
- **Merge Strategy:** Merge commits to preserve feature history
**Rules:**
- All feature branches merge here first
- Continuous integration testing
- Regular merges to `main` for releases
- Should be stable enough for testing
### 3. **feature/** (Feature Development)
- **Purpose:** Individual feature development
- **Naming:** `feature/[component]-[description]`
- **Lifecycle:** Created from `develop`, merged back to `develop`
- **Protection:** Optional, team discretion
**Examples:**
```
feature/backend-user-authentication
feature/frontend-application-sidebar
feature/ai-claude-integration
feature/database-rls-policies
feature/docker-development-setup
```
### 4. **hotfix/** (Emergency Fixes)
- **Purpose:** Critical production issues
- **Naming:** `hotfix/[issue-description]`
- **Lifecycle:** Created from `main`, merged to both `main` and `develop`
- **Priority:** Highest priority, fast-track review
### 5. **release/** (Release Preparation)
- **Purpose:** Prepare releases, final testing
- **Naming:** `release/v[version]`
- **Lifecycle:** Created from `develop`, merged to `main` when ready
- **Activities:** Bug fixes, documentation updates, version bumps
---
## 🔄 Development Workflow
### Standard Feature Development Flow
#### 1. Start New Feature
```bash
# Ensure develop is up to date
git checkout develop
git pull origin develop
# Create feature branch
git checkout -b feature/backend-application-service
git push -u origin feature/backend-application-service
```
#### 2. Development Cycle
```bash
# Regular commits with descriptive messages
git add .
git commit -m "feat(backend): implement application creation endpoint
- Add POST /api/v1/applications endpoint
- Implement application validation
- Add database integration
- Include unit tests
Closes #23"
# Push regularly to backup work
git push origin feature/backend-application-service
```
#### 3. Feature Completion
```bash
# Update with latest develop changes
git checkout develop
git pull origin develop
git checkout feature/backend-application-service
git rebase develop
# Push updated branch
git push origin feature/backend-application-service --force-with-lease
# Create Pull Request via Gitea UI
```
#### 4. Code Review & Merge
- **Create PR** from feature branch to `develop`
- **Code review** by at least 1 team member
- **CI/CD checks** must pass (tests, linting, etc.)
- **Merge** using "Merge commit" strategy
- **Delete** feature branch after merge
---
## 📋 Pull Request Guidelines
### PR Title Format
```
[type](scope): brief description
Examples:
feat(backend): add user authentication endpoints
fix(frontend): resolve sidebar navigation bug
docs(api): update endpoint documentation
test(database): add RLS policy tests
```
### PR Description Template
```markdown
## 🎯 Purpose
Brief description of what this PR accomplishes.
## 🔧 Changes Made
- [ ] Add new API endpoint for application creation
- [ ] Implement database integration
- [ ] Add unit tests with 90% coverage
- [ ] Update API documentation
## 🧪 Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Database migrations tested
## 📚 Documentation
- [ ] API documentation updated
- [ ] README updated if needed
- [ ] Code comments added for complex logic
## 🔍 Review Checklist
- [ ] Code follows project style guidelines
- [ ] No hardcoded secrets or credentials
- [ ] Error handling implemented
- [ ] Security considerations addressed
## 🔗 Related Issues
Closes #123
Relates to #456
```
### Review Criteria
**Mandatory Checks:**
- [ ] All CI/CD pipeline checks pass
- [ ] No merge conflicts with target branch
- [ ] At least 1 peer code review approval
- [ ] Tests cover new functionality
- [ ] Documentation updated
**Code Quality Checks:**
- [ ] Follows established coding standards
- [ ] No security vulnerabilities introduced
- [ ] Performance considerations addressed
- [ ] Error handling implemented properly
---
## 🚀 Release Management
### MVP Release Strategy
#### Phase 1 Releases (Weeks 1-8)
```
v0.1.0 - Week 2: Basic infrastructure
v0.2.0 - Week 4: User auth + application CRUD
v0.3.0 - Week 6: AI agents integration
v1.0.0 - Week 8: Complete MVP
```
#### Release Process
1. **Create Release Branch**
```bash
git checkout develop
git pull origin develop
git checkout -b release/v1.0.0-mvp
git push -u origin release/v1.0.0-mvp
```
2. **Prepare Release**
- Update version numbers in package files
- Update CHANGELOG.md
- Final testing and bug fixes
- Documentation review
3. **Release to Production**
```bash
# Create PR: release/v1.0.0-mvp → main
# After approval and merge:
git checkout main
git pull origin main
git tag -a v1.0.0 -m "MVP Release v1.0.0"
git push origin v1.0.0
```
4. **Post-Release Cleanup**
```bash
# Merge changes back to develop
git checkout develop
git merge main
git push origin develop
# Delete release branch
git branch -d release/v1.0.0-mvp
git push origin --delete release/v1.0.0-mvp
```
---
## 🔒 Branch Protection Rules
### main Branch Protection
```yaml
Protection Rules:
- Require pull request reviews: true
- Required approving reviews: 1
- Dismiss stale reviews: true
- Require review from code owners: true
- Restrict pushes to admins only: true
- Require status checks: true
- Required status checks:
- ci/backend-tests
- ci/frontend-tests
- ci/integration-tests
- ci/security-scan
- Require branches to be up to date: true
- Include administrators: true
```
### develop Branch Protection
```yaml
Protection Rules:
- Require pull request reviews: true
- Required approving reviews: 1
- Require status checks: true
- Required status checks:
- ci/backend-tests
- ci/frontend-tests
- ci/lint-check
- Require branches to be up to date: true
```
---
## 🤖 CI/CD Integration
### Automated Workflows by Branch
#### feature/* branches
```yaml
# .gitea/workflows/feature.yml
on:
push:
branches:
- 'feature/*'
pull_request:
branches:
- develop
jobs:
- lint-and-format
- unit-tests
- security-scan
- build-check
```
#### develop branch
```yaml
# .gitea/workflows/develop.yml
on:
push:
branches:
- develop
jobs:
- lint-and-format
- unit-tests
- integration-tests
- security-scan
- build-and-deploy-staging
```
#### main branch
```yaml
# .gitea/workflows/production.yml
on:
push:
branches:
- main
tags:
- 'v*'
jobs:
- full-test-suite
- security-scan
- build-and-deploy-production
- create-release-notes
```
---
## 📊 Development Team Workflow
### Team Roles & Responsibilities
#### **Backend Developer**
```bash
# Typical feature branches:
feature/backend-auth-service
feature/backend-application-api
feature/backend-ai-integration
feature/database-schema-updates
```
#### **Frontend Developer**
```bash
# Typical feature branches:
feature/frontend-auth-components
feature/frontend-application-dashboard
feature/frontend-document-editor
feature/ui-component-library
```
#### **Full-Stack Developer**
```bash
# End-to-end feature branches:
feature/complete-user-registration
feature/complete-application-workflow
feature/complete-document-management
```
#### **DevOps/Infrastructure**
```bash
# Infrastructure branches:
feature/docker-optimization
feature/ci-cd-pipeline
feature/monitoring-setup
feature/deployment-automation
```
### Daily Development Routine
#### Morning Sync
```bash
# Start each day with latest changes
git checkout develop
git pull origin develop
# Update feature branch
git checkout feature/your-current-feature
git rebase develop
# Resolve any conflicts and continue work
```
#### End of Day
```bash
# Commit and push daily progress
git add .
git commit -m "wip: progress on application service implementation"
git push origin feature/your-current-feature
```
---
## 🐛 Handling Common Scenarios
### Scenario 1: Feature Branch Behind develop
```bash
# Update feature branch with latest develop
git checkout feature/your-feature
git rebase develop
# If conflicts occur:
git status # See conflicted files
# Edit files to resolve conflicts
git add .
git rebase --continue
# Force push with lease (safer than --force)
git push origin feature/your-feature --force-with-lease
```
### Scenario 2: Emergency Hotfix
```bash
# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix
# Make fix
git add .
git commit -m "fix: resolve critical authentication vulnerability
- Patch JWT token validation
- Update security tests
- Add rate limiting
Fixes #emergency-issue"
# Push and create PRs to both main and develop
git push -u origin hotfix/critical-security-fix
# Create PR: hotfix/critical-security-fix → main (priority)
# Create PR: hotfix/critical-security-fix → develop
```
### Scenario 3: Large Feature Coordination
```bash
# For complex features requiring multiple developers:
# Main feature branch
feature/ai-agents-integration
# Sub-feature branches
feature/ai-agents-integration/research-agent
feature/ai-agents-integration/resume-optimizer
feature/ai-agents-integration/cover-letter-generator
# Merge sub-features to main feature branch first
# Then merge main feature branch to develop
```
---
## 📈 Branch Management Best Practices
### DO's ✅
- **Keep branches focused** - One feature per branch
- **Use descriptive names** - Clear what the branch does
- **Regular commits** - Small, focused commits with good messages
- **Rebase before merge** - Keep history clean
- **Delete merged branches** - Avoid branch pollution
- **Test before merge** - Ensure CI/CD passes
- **Review code thoroughly** - Maintain code quality
### DON'Ts ❌
- **Don't commit directly to main** - Always use PR workflow
- **Don't use generic branch names** - Avoid "fix", "update", "changes"
- **Don't let branches go stale** - Merge or close unused branches
- **Don't ignore conflicts** - Resolve properly, don't force
- **Don't skip testing** - Every merge should be tested
- **Don't merge your own PRs** - Always get peer review
### Naming Conventions
```bash
# Good branch names:
feature/backend-user-authentication
feature/frontend-application-sidebar
feature/ai-claude-integration
feature/database-migration-v2
hotfix/security-jwt-validation
release/v1.0.0-mvp
# Bad branch names:
fix-stuff
john-updates
temporary
new-feature
test-branch
```
---
## 🔧 Git Configuration
### Recommended Git Settings
```bash
# Set up git aliases for common operations
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'
# Better log formatting
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
# Set up pull to rebase by default (cleaner history)
git config --global pull.rebase true
# Set up push to current branch only
git config --global push.default current
```
### Team .gitignore
```gitignore
# Environment files
.env
.env.local
.env.*.local
# IDE files
.vscode/
.idea/
*.swp
*.swo
# OS files
.DS_Store
Thumbs.db
# Docker
.dockerignore
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
ENV/
# Node modules (if using)
node_modules/
# Logs
*.log
logs/
# Database
*.db
*.sqlite
# Temporary files
*.tmp
*.temp
temp/
tmp/
# Coverage reports
htmlcov/
.coverage
.coverage.*
# Test outputs
.pytest_cache/
.tox/
```
---
## 📚 Integration with Development Documents
### Relationship to Other Documents
- **Development Setup:** Clone from correct branch, set up environment
- **API Specification:** Feature branches should implement specific endpoints
- **Database Design:** Schema changes require migration planning
- **Testing Strategy:** All branches must pass defined test suites
### 8-Week MVP Timeline Integration
```
Week 1-2: Foundation
├── feature/docker-development-setup
├── feature/database-initial-schema
└── feature/backend-project-structure
Week 3-4: Core Features
├── feature/backend-user-authentication
├── feature/frontend-auth-components
└── feature/backend-application-crud
Week 5-6: AI Integration
├── feature/ai-claude-integration
├── feature/ai-research-agent
└── feature/ai-resume-optimizer
Week 7-8: Polish & Release
├── feature/frontend-document-editor
├── feature/error-handling-improvements
└── release/v1.0.0-mvp
```
---
*This Git branching strategy ensures clean, maintainable code while supporting parallel development and safe deployments for the JobForge MVP. The strategy scales from MVP development to future SaaS features.*

601
docs/infrastructure/docker_setup.md Normal file
View File

@@ -0,0 +1,601 @@
# Docker Setup Guide - Job Forge
## Overview
Job Forge uses Docker for containerization to ensure consistent environments across development, testing, and production. This guide covers Docker configuration, best practices, and troubleshooting.
## Docker Architecture
### Container Structure
```
Job Forge Docker Setup
├── jobforge-app # FastAPI + Dash application
├── postgres # PostgreSQL 16 with pgvector
└── nginx # Reverse proxy and SSL termination
```
### Network Configuration
- **Internal Network**: Docker compose creates isolated network
- **External Access**: Only nginx container exposes ports 80/443
- **Service Discovery**: Containers communicate via service names
## Development Setup
### 1. Prerequisites
```bash
# Install Docker and Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
```
### 2. Environment Configuration
```bash
# Copy environment template
cp .env.example .env
# Edit for development
nano .env
```
```bash
# Development Environment Variables
DATABASE_URL="postgresql://jobforge:jobforge123@postgres:5432/jobforge"
CLAUDE_API_KEY="your-claude-api-key"
OPENAI_API_KEY="your-openai-api-key"
JWT_SECRET="development-secret-key-change-in-production"
DEBUG=true
LOG_LEVEL="DEBUG"
```
### 3. Docker Compose Configuration
#### docker-compose.yml
```yaml
version: '3.8'
services:
# FastAPI + Dash Application
jobforge-app:
build:
context: .
dockerfile: Dockerfile
container_name: jobforge-app
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://jobforge:jobforge123@postgres:5432/jobforge
- CLAUDE_API_KEY=${CLAUDE_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- JWT_SECRET=${JWT_SECRET}
- DEBUG=${DEBUG:-false}
- LOG_LEVEL=${LOG_LEVEL:-INFO}
depends_on:
postgres:
condition: service_healthy
volumes:
# Development: mount source for hot reload
- ./app:/app/app:ro
- ./uploads:/app/uploads
- ./logs:/var/log/jobforge
networks:
- jobforge-network
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# PostgreSQL with pgvector
postgres:
image: pgvector/pgvector:pg16
container_name: jobforge-postgres
environment:
- POSTGRES_DB=jobforge
- POSTGRES_USER=jobforge
- POSTGRES_PASSWORD=jobforge123
- POSTGRES_INITDB_ARGS="--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"
ports:
- "5432:5432" # Expose for development access
volumes:
- postgres_data:/var/lib/postgresql/data
- ./init_db.sql:/docker-entrypoint-initdb.d/init_db.sql:ro
- ./backups:/backups
networks:
- jobforge-network
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U jobforge -d jobforge"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# Nginx Reverse Proxy
nginx:
image: nginx:alpine
container_name: jobforge-nginx
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./nginx/conf.d:/etc/nginx/conf.d:ro
- ./ssl:/etc/nginx/ssl:ro
- ./static:/var/www/static:ro
depends_on:
- jobforge-app
networks:
- jobforge-network
restart: unless-stopped
healthcheck:
test: ["CMD", "nginx", "-t"]
interval: 30s
timeout: 10s
retries: 3
networks:
jobforge-network:
driver: bridge
ipam:
config:
- subnet: 172.20.0.0/16
volumes:
postgres_data:
driver: local
```
#### docker-compose.override.yml (Development)
```yaml
# Development overrides
version: '3.8'
services:
jobforge-app:
build:
target: development # Multi-stage build target
environment:
- DEBUG=true
- LOG_LEVEL=DEBUG
- RELOAD=true
volumes:
# Enable hot reload in development
- ./app:/app/app
- ./tests:/app/tests
command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
postgres:
environment:
- POSTGRES_PASSWORD=jobforge123 # Simpler password for dev
ports:
- "5432:5432" # Expose port for development tools
```
### 4. Dockerfile Configuration
#### Multi-stage Dockerfile
```dockerfile
# Multi-stage Dockerfile for Job Forge
FROM python:3.12-slim as base
# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PYTHONPATH="/app" \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
# Install system dependencies
RUN apt-get update && apt-get install -y \
curl \
postgresql-client \
build-essential \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Development target
FROM base as development
# Install development dependencies
COPY requirements-dev.txt .
RUN pip install --no-cache-dir -r requirements-dev.txt
# Copy source code
COPY . .
# Create non-root user
RUN adduser --disabled-password --gecos '' jobforge && \
chown -R jobforge:jobforge /app
USER jobforge
# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8000/health || exit 1
EXPOSE 8000
# Development command with hot reload
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
# Production target
FROM base as production
# Copy source code
COPY app/ ./app/
COPY alembic/ ./alembic/
COPY alembic.ini .
# Create non-root user
RUN adduser --disabled-password --gecos '' jobforge && \
chown -R jobforge:jobforge /app && \
mkdir -p /var/log/jobforge && \
chown jobforge:jobforge /var/log/jobforge
USER jobforge
# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8000/health || exit 1
EXPOSE 8000
# Production command
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
```
#### .dockerignore
```
# .dockerignore for Job Forge
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
.venv/
pip-log.txt
pip-delete-this-directory.txt
.git/
.gitignore
README.md
.env
.env.*
docker-compose*.yml
Dockerfile*
.pytest_cache/
htmlcov/
.coverage
*.log
logs/
backups/
uploads/
!uploads/.gitkeep
.vscode/
.idea/
*.swp
*.swo
*~
```
## Production Setup
### 1. Production Docker Compose
```yaml
# docker-compose.prod.yml
version: '3.8'
services:
jobforge-app:
build:
context: .
dockerfile: Dockerfile
target: production
environment:
- DATABASE_URL=${DATABASE_URL}
- CLAUDE_API_KEY=${CLAUDE_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- JWT_SECRET=${JWT_SECRET}
- DEBUG=false
- LOG_LEVEL=INFO
- WORKERS=4
volumes:
- ./uploads:/app/uploads
- ./logs:/var/log/jobforge
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
postgres:
image: pgvector/pgvector:pg16
environment:
- POSTGRES_DB=${DB_NAME}
- POSTGRES_USER=${DB_USER}
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
- ./backups:/backups:ro
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.25'
memory: 256M
# Don't expose port in production
# ports:
# - "5432:5432"
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/prod.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
deploy:
resources:
limits:
cpus: '0.5'
memory: 128M
```
### 2. Production Commands
```bash
# Build production images
docker-compose -f docker-compose.prod.yml build
# Start production services
docker-compose -f docker-compose.prod.yml up -d
# Scale application containers
docker-compose -f docker-compose.prod.yml up -d --scale jobforge-app=3
```
## Container Management
### 1. Basic Operations
```bash
# Start all services
docker-compose up -d
# Stop all services
docker-compose down
# Restart specific service
docker-compose restart jobforge-app
# View logs
docker-compose logs -f jobforge-app
docker-compose logs --tail=100 postgres
# Execute commands in container
docker-compose exec jobforge-app bash
docker-compose exec postgres psql -U jobforge -d jobforge
```
### 2. Database Operations
```bash
# Run database migrations
docker-compose exec jobforge-app alembic upgrade head
# Create new migration
docker-compose exec jobforge-app alembic revision --autogenerate -m "description"
# Database backup
docker-compose exec postgres pg_dump -U jobforge jobforge > backup.sql
# Database restore
docker-compose exec -T postgres psql -U jobforge -d jobforge < backup.sql
```
### 3. Application Management
```bash
# Update application code (development)
docker-compose restart jobforge-app
# Rebuild containers
docker-compose build
docker-compose up -d
# View container resource usage
docker stats
# Clean up unused resources
docker system prune -a -f
```
## Monitoring and Debugging
### 1. Health Checks
```bash
# Check container health
docker-compose ps
# Manual health check
curl http://localhost:8000/health
# Check individual services
docker-compose exec jobforge-app python -c "import requests; print(requests.get('http://localhost:8000/health').json())"
```
### 2. Log Management
```bash
# View application logs
docker-compose logs -f jobforge-app
# View specific timeframe
docker-compose logs --since="2024-01-01T00:00:00" jobforge-app
# Export logs
docker-compose logs jobforge-app > app.log
# Follow logs with timestamps
docker-compose logs -f -t jobforge-app
```
### 3. Performance Monitoring
```bash
# Container resource usage
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"
# Container processes
docker-compose exec jobforge-app ps aux
# Database performance
docker-compose exec postgres psql -U jobforge -d jobforge -c "SELECT * FROM pg_stat_activity;"
```
## Troubleshooting
### 1. Common Issues
#### Container Won't Start
```bash
# Check logs for errors
docker-compose logs jobforge-app
# Check if ports are in use
sudo netstat -tulpn | grep :8000
# Check Docker daemon
sudo systemctl status docker
```
#### Database Connection Issues
```bash
# Test database connectivity
docker-compose exec jobforge-app python -c "
import asyncio
import asyncpg
asyncio.run(asyncpg.connect('postgresql://jobforge:jobforge123@postgres:5432/jobforge'))
print('Database connection successful')
"
# Check database is ready
docker-compose exec postgres pg_isready -U jobforge
```
#### Volume Mount Issues
```bash
# Check volume permissions
ls -la uploads/ logs/
# Fix permissions
sudo chown -R $USER:$USER uploads logs
chmod 755 uploads logs
```
### 2. Debug Mode
```bash
# Run container in debug mode
docker-compose run --rm jobforge-app bash
# Run with environment override
docker-compose run -e DEBUG=true jobforge-app
# Attach to running container
docker-compose exec jobforge-app bash
```
### 3. Network Issues
```bash
# Check network connectivity
docker network ls
docker network inspect jobforge_jobforge-network
# Test inter-container communication
docker-compose exec jobforge-app ping postgres
docker-compose exec nginx ping jobforge-app
```
## Optimization
### 1. Image Optimization
```dockerfile
# Use multi-stage builds to reduce image size
# Use .dockerignore to exclude unnecessary files
# Use specific base image versions
# Combine RUN commands to reduce layers
# Clean up package caches
```
### 2. Resource Limits
```yaml
# Set appropriate resource limits
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
```
### 3. Volume Optimization
```bash
# Use bind mounts for development
# Use named volumes for persistent data
# Regular cleanup of unused volumes
docker volume prune
```
## Security Best Practices
### 1. Container Security
```dockerfile
# Run as non-root user
USER jobforge
# Use specific image versions
FROM python:3.12-slim
# Don't expose unnecessary ports
# Use secrets for sensitive data
```
### 2. Network Security
```yaml
# Use custom networks
networks:
jobforge-network:
driver: bridge
internal: true # For internal services
```
### 3. Environment Security
```bash
# Use .env files for secrets
# Don't commit secrets to version control
# Use Docker secrets in production
# Regular security updates
```
This Docker setup provides a robust, scalable, and maintainable containerization solution for Job Forge, suitable for both development and production environments.

530
docs/infrastructure/server_deployment.md Normal file
View File

@@ -0,0 +1,530 @@
# Server Deployment Guide - Job Forge
## Overview
This guide covers deploying Job Forge to your own server for prototype development and testing. The deployment uses Docker containers for easy management and isolation.
## Prerequisites
### Server Requirements
- **OS**: Ubuntu 20.04+ or CentOS 8+
- **RAM**: Minimum 2GB, recommended 4GB
- **Storage**: Minimum 20GB available disk space
- **CPU**: 2 cores recommended
- **Network**: Public IP address and domain name (optional)
### Required Software
- Docker 20.10+
- Docker Compose 2.0+
- Git
- Nginx (for reverse proxy)
- Certbot (for SSL certificates)
## Initial Server Setup
### 1. Update System
```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y
# CentOS/RHEL
sudo yum update -y
```
### 2. Install Docker
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# CentOS/RHEL
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
```
### 3. Install Docker Compose
```bash
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
### 4. Install Additional Tools
```bash
# Ubuntu/Debian
sudo apt install -y git nginx certbot python3-certbot-nginx
# CentOS/RHEL
sudo yum install -y git nginx certbot python3-certbot-nginx
```
## Application Deployment
### 1. Clone Repository
```bash
cd /opt
sudo git clone https://github.com/yourusername/job-forge.git
sudo chown -R $USER:$USER job-forge
cd job-forge
```
### 2. Environment Configuration
```bash
# Copy environment template
cp .env.example .env
# Edit environment variables
nano .env
```
#### Required Environment Variables
```bash
# Database Configuration
DATABASE_URL="postgresql://jobforge:CHANGE_THIS_PASSWORD@postgres:5432/jobforge"
DATABASE_POOL_SIZE=10
# AI Service API Keys (obtain from providers)
CLAUDE_API_KEY="your-claude-api-key-here"
OPENAI_API_KEY="your-openai-api-key-here"
# Security Settings
JWT_SECRET="your-super-secret-jwt-key-minimum-32-characters"
JWT_ALGORITHM="HS256"
JWT_EXPIRE_MINUTES=1440
# Application Settings
APP_NAME="Job Forge"
DEBUG=false
LOG_LEVEL="INFO"
# Server Configuration
SERVER_HOST="0.0.0.0"
SERVER_PORT=8000
WORKERS=2
# Security
ALLOWED_HOSTS=["yourdomain.com", "www.yourdomain.com", "localhost"]
CORS_ORIGINS=["https://yourdomain.com", "https://www.yourdomain.com"]
```
### 3. Create Required Directories
```bash
mkdir -p uploads backups logs ssl
chmod 755 uploads backups logs
chmod 700 ssl
```
### 4. Build and Start Services
```bash
# Build Docker images
docker-compose build
# Start services in background
docker-compose up -d
# Check status
docker-compose ps
```
### 5. Initialize Database
```bash
# Run database migrations
docker-compose exec jobforge-app alembic upgrade head
# Verify database setup
docker-compose exec postgres psql -U jobforge -d jobforge -c "\dt"
```
### 6. Verify Application
```bash
# Check application health
curl http://localhost:8000/health
# Check logs
docker-compose logs jobforge-app
```
## Nginx Configuration
### 1. Create Nginx Configuration
```bash
sudo nano /etc/nginx/sites-available/jobforge
```
```nginx
server {
listen 80;
server_name yourdomain.com www.yourdomain.com;
# Redirect to HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name yourdomain.com www.yourdomain.com;
# SSL Configuration (will be added by certbot)
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
# File upload size limit
client_max_body_size 10M;
# Main application
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_redirect off;
# Timeout settings for AI operations
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 120s;
}
# Health check endpoint
location /health {
proxy_pass http://localhost:8000/health;
access_log off;
}
# Static files (if any)
location /static/ {
alias /opt/job-forge/static/;
expires 30d;
add_header Cache-Control "public, immutable";
}
# API documentation
location /docs {
proxy_pass http://localhost:8000/docs;
}
# Deny access to sensitive files
location ~ /\. {
deny all;
}
}
```
### 2. Enable Site and Test Configuration
```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/jobforge /etc/nginx/sites-enabled/
# Test configuration
sudo nginx -t
# Restart nginx
sudo systemctl restart nginx
```
## SSL Certificate Setup
### 1. Obtain SSL Certificate
```bash
# Using Let's Encrypt Certbot
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
# Follow prompts to configure SSL
```
### 2. Configure Auto-Renewal
```bash
# Test renewal
sudo certbot renew --dry-run
# Add cron job for auto-renewal
sudo crontab -e
# Add this line:
0 12 * * * /usr/bin/certbot renew --quiet
```
## Firewall Configuration
### 1. Configure UFW (Ubuntu)
```bash
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'
sudo ufw --force enable
sudo ufw status
```
### 2. Configure Firewalld (CentOS)
```bash
sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
```
## Monitoring and Maintenance
### 1. Log Management
```bash
# View application logs
docker-compose logs -f jobforge-app
# View nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
# Set up log rotation
sudo nano /etc/logrotate.d/jobforge
```
```
/opt/job-forge/logs/*.log {
daily
missingok
rotate 30
compress
delaycompress
notifempty
copytruncate
}
```
### 2. Backup Configuration
```bash
# Create backup script
sudo nano /opt/job-forge/backup.sh
```
```bash
#!/bin/bash
# Job Forge backup script
BACKUP_DIR="/opt/backups/jobforge"
DATE=$(date +%Y%m%d_%H%M%S)
# Create backup directory
mkdir -p "$BACKUP_DIR"
echo "Starting Job Forge backup - $DATE"
# Database backup
docker-compose exec -T postgres pg_dump -U jobforge jobforge | gzip > "$BACKUP_DIR/database_$DATE.sql.gz"
# Application files backup
tar -czf "$BACKUP_DIR/app_$DATE.tar.gz" \
--exclude="logs/*" \
--exclude="uploads/*" \
/opt/job-forge
# Keep only last 30 days
find "$BACKUP_DIR" -name "*.gz" -mtime +30 -delete
echo "Backup completed successfully"
```
```bash
# Make executable
chmod +x /opt/job-forge/backup.sh
# Add to crontab (daily backup at 2 AM)
sudo crontab -e
0 2 * * * /opt/job-forge/backup.sh
```
### 3. Health Monitoring
```bash
# Create health check script
nano /opt/job-forge/health-check.sh
```
```bash
#!/bin/bash
# Job Forge health check
HEALTH_URL="http://localhost:8000/health"
LOG_FILE="/opt/job-forge/logs/health-check.log"
response=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL")
if [ "$response" = "200" ]; then
echo "$(date): Health check passed" >> "$LOG_FILE"
else
echo "$(date): Health check failed - HTTP $response" >> "$LOG_FILE"
# Send alert (email, Slack, etc.)
# systemctl restart docker-compose@job-forge
fi
```
```bash
# Make executable and add to cron (every 5 minutes)
chmod +x /opt/job-forge/health-check.sh
crontab -e
*/5 * * * * /opt/job-forge/health-check.sh
```
## Application Updates
### 1. Update Process
```bash
cd /opt/job-forge
# Create backup before update
./backup.sh
# Pull latest changes
git pull origin main
# Rebuild and restart services
docker-compose build
docker-compose up -d
# Run database migrations if needed
docker-compose exec jobforge-app alembic upgrade head
# Verify application is working
curl http://localhost:8000/health
```
### 2. Rollback Process
```bash
# If update fails, rollback to previous version
git log --oneline -10 # Find previous commit
git checkout <previous-commit-hash>
# Rebuild and restart
docker-compose build
docker-compose up -d
# Or restore from backup if needed
```
## Troubleshooting
### Common Issues
#### 1. Application Won't Start
```bash
# Check logs
docker-compose logs jobforge-app
# Check database connection
docker-compose exec postgres pg_isready -U jobforge
# Check environment variables
docker-compose exec jobforge-app env | grep -E "(DATABASE|CLAUDE|OPENAI)"
```
#### 2. Database Connection Issues
```bash
# Restart postgres
docker-compose restart postgres
# Check database logs
docker-compose logs postgres
# Connect to database manually
docker-compose exec postgres psql -U jobforge -d jobforge
```
#### 3. SSL Certificate Issues
```bash
# Check certificate status
sudo certbot certificates
# Renew certificate manually
sudo certbot renew
# Check nginx configuration
sudo nginx -t
```
#### 4. Permission Issues
```bash
# Fix file permissions
sudo chown -R $USER:$USER /opt/job-forge
chmod 755 /opt/job-forge/uploads
chmod 700 /opt/job-forge/ssl
```
### Performance Optimization
#### 1. Database Optimization
```bash
# Connect to database
docker-compose exec postgres psql -U jobforge -d jobforge
# Check slow queries
SELECT query, mean_time, calls FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10;
# Analyze table statistics
ANALYZE;
```
#### 2. Container Resource Limits
```yaml
# In docker-compose.yml, add resource limits
services:
jobforge-app:
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
```
#### 3. Nginx Caching
```nginx
# Add to nginx configuration
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
```
## Security Hardening
### 1. System Updates
```bash
# Enable automatic security updates
sudo apt install unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades
```
### 2. Fail2Ban Setup
```bash
# Install fail2ban
sudo apt install fail2ban
# Configure for nginx
sudo nano /etc/fail2ban/jail.local
```
```ini
[nginx-http-auth]
enabled = true
[nginx-limit-req]
enabled = true
```
### 3. Docker Security
```bash
# Run containers as non-root user (already configured in Dockerfile)
# Limit container capabilities
# Use secrets for sensitive data
```
This deployment guide provides a comprehensive setup for Job Forge on your own server. Adjust configurations based on your specific requirements and security policies.

378
docs/jobforge_mvp_architecture.md
View File

@@ -1,47 +1,48 @@
# JobForge MVP - Core Job Application Module
# Job Forge - Python/FastAPI Web Application Architecture
**Version:** 1.0.0 MVP
**Version:** 1.0.0 Prototype
**Status:** Development Phase 1
**Date:** July 2025
**Scope:** Core job application workflow with essential features
**Target:** Personal use for concept validation and testing
**Date:** August 2025
**Scope:** AI-powered job application management web application
**Target:** Prototype development for server deployment
---
## 📋 MVP Scope & Objectives
## 📋 Application Scope & Objectives
### Core Functionality
- **User Authentication**: Basic login/signup system
- **Job Application Creation**: Add new applications with job description and URL
- **3-Phase AI Workflow**: Research → Resume → Cover Letter generation
- **Document Management**: View and edit generated documents
- **Navigation Interface**: Sidebar + top bar for seamless workflow navigation
### Core Web Application Features
- **User Authentication**: JWT-based secure authentication system
- **Job Application Management**: Full CRUD operations for job applications
- **AI-Powered Document Generation**: Automated cover letter and resume optimization
- **Web Interface**: Modern responsive web interface using Dash + Mantine
- **Multi-tenant Architecture**: Secure user data isolation with RLS
### MVP Goals
- Validate core AI workflow effectiveness
- Test user experience with Dash + Mantine interface
- Prove concept with personal job application journey
- Establish foundation for Phase 2 (post-application features)
### Development Goals
- Deploy functional prototype to personal server
- Validate AI workflow effectiveness for job applications
- Test web application performance and user experience
- Establish scalable architecture for future enhancements
- Demonstrate full-stack Python/FastAPI capabilities
---
## 🏗️ MVP Architecture
## 🏗️ Web Application Architecture
### System Overview
```mermaid
graph TB
subgraph "Frontend (Dash + Mantine)"
UI[Main UI]
SIDEBAR[Application Sidebar]
TOPBAR[Navigation Top Bar]
subgraph "Web Frontend (Dash + Mantine)"
UI[Dashboard Interface]
FORMS[Application Forms]
EDITOR[Document Editor]
VIEWER[Document Viewer]
end
subgraph "Backend API (FastAPI)"
AUTH[Authentication]
APP[Application Service]
AI[AI Orchestrator]
DOC[Document Service]
AUTH[JWT Authentication]
CRUD[Application CRUD]
AI[AI Service Layer]
FILES[Document Management]
end
subgraph "AI Agents"
@@ -61,14 +62,15 @@ graph TB
end
UI --> AUTH
UI --> APP
UI --> DOC
APP --> AI
FORMS --> CRUD
EDITOR --> FILES
VIEWER --> FILES
CRUD --> AI
AI --> RESEARCH
AI --> RESUME
AI --> COVER
APP --> PG
DOC --> FILES
CRUD --> PG
FILES --> PG
RESEARCH --> CLAUDE
RESUME --> CLAUDE
COVER --> CLAUDE
@@ -77,40 +79,49 @@ graph TB
---
## 🔐 User Authentication (MVP)
## 🔐 User Authentication (Web Application)
### Simple Authentication System
### JWT-Based Authentication System
```python
class AuthenticationService:
"""Basic user authentication for MVP"""
"""JWT-based authentication for web application"""
async def register_user(self, email: str, password: str, name: str) -> User:
"""Register new user account"""
async def register_user(self, user_data: UserCreate) -> User:
"""Register new user account with validation"""
async def authenticate_user(self, email: str, password: str) -> AuthResult:
"""Login user and return JWT token"""
async def authenticate_user(self, credentials: UserLogin) -> AuthResult:
"""Authenticate user and return JWT access token"""
async def verify_token(self, token: str) -> User:
"""Verify JWT token and return user"""
"""Verify JWT token and return authenticated user"""
async def logout_user(self, user_id: str) -> None:
"""Logout user session"""
async def refresh_token(self, refresh_token: str) -> AuthResult:
"""Refresh JWT access token"""
def create_access_token(self, user_id: str) -> str:
"""Create JWT access token with expiration"""
```
### Database Schema (Users)
```sql
-- Basic user table for MVP
-- User table with enhanced security
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
full_name VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Enable basic row level security
-- Enable row level security for multi-tenancy
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
-- Create index for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_active ON users(is_active);
```
---
@@ -558,157 +569,208 @@ CREATE POLICY user_own_resumes ON user_resumes FOR ALL USING (user_id = current_
---
## 🚀 MVP Development Plan
## 🚀 Web Application Development Plan
### Development Phases
#### **Week 1-2: Foundation Setup**
- Docker development environment
- PostgreSQL database with basic schema
- FastAPI backend with authentication endpoints
- Basic Dash + Mantine frontend structure
#### **Phase 1: Infrastructure & Authentication (Weeks 1-2)**
- Docker containerization for development and production
- PostgreSQL 16 with pgvector extension setup
- FastAPI backend with JWT authentication
- Row Level Security (RLS) implementation
- Basic CI/CD pipeline setup
#### **Week 3-4: Core Application Module**
- Application creation and listing
- Database integration with user isolation
- Basic sidebar and navigation UI
- Application status tracking
#### **Phase 2: Core Web Application (Weeks 3-4)**
- Dash + Mantine responsive web interface
- Application CRUD operations with API endpoints
- User dashboard and application management
- Database integration with async operations
- Multi-tenant data isolation
#### **Week 5-6: AI Workflow Implementation**
- Research Agent with Claude integration
- Resume Optimizer with portfolio handling
- Cover Letter Generator with user context
- Document storage and retrieval system
#### **Phase 3: AI Integration (Weeks 5-6)**
- Claude API integration for document generation
- OpenAI API for embeddings and analysis
- Async AI service layer implementation
- Error handling and retry mechanisms
- AI service rate limiting and monitoring
#### **Week 7-8: Frontend Polish & Integration**
- Document editor with markdown support
- Real-time status updates during AI processing
- Phase navigation and progress tracking
- Error handling and user feedback
#### **Phase 4: Production Deployment (Weeks 7-8)**
- Server deployment with Docker Compose
- Nginx reverse proxy and SSL configuration
- Database backup and monitoring setup
- Performance optimization and caching
- Security hardening and testing
### MVP Success Criteria
- ✅ User can register/login securely
- ✅ User can create job applications with description/URL
- ✅ AI generates research report automatically
- ✅ AI optimizes resume based on job requirements
- ✅ AI generates cover letter with user context
- ✅ User can view and edit all generated documents
- ✅ Smooth navigation between application phases
- ✅ Data persisted securely with user isolation
### Prototype Success Criteria
- ✅ Secure multi-user web application deployed to server
- ✅ JWT-based authentication with user registration/login
- ✅ Full CRUD operations for job applications
- ✅ AI-powered cover letter generation via web interface
- ✅ Responsive web UI with modern UX design
- ✅ Secure data storage with user isolation (RLS)
- ✅ Production-ready deployment with monitoring
- ✅ Scalable architecture for future enhancements
---
## 🐳 Docker Development Setup
## 🐳 Docker Production Deployment
### Development Environment
### Production Environment
```yaml
# docker-compose.yml
version: '3.8'
services:
postgres:
image: pgvector/pgvector:pg16
environment:
POSTGRES_DB: jobforge_mvp
POSTGRES_USER: jobforge_user
POSTGRES_PASSWORD: jobforge_password
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
- ./database/init.sql:/docker-entrypoint-initdb.d/init.sql
backend:
# FastAPI + Dash Web Application
jobforge-app:
build:
context: .
dockerfile: Dockerfile.backend
ports:
- "8000:8000"
dockerfile: Dockerfile
target: production
container_name: jobforge-app
environment:
- DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
- DATABASE_URL=postgresql://jobforge:${DB_PASSWORD}@postgres:5432/jobforge
- CLAUDE_API_KEY=${CLAUDE_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- JWT_SECRET=${JWT_SECRET}
- DEBUG=false
- LOG_LEVEL=INFO
volumes:
- ./src:/app/src
- ./uploads:/app/uploads
- ./logs:/var/log/jobforge
depends_on:
- postgres
command: uvicorn src.backend.main:app --host 0.0.0.0 --port 8000 --reload
postgres:
condition: service_healthy
networks:
- jobforge-network
restart: unless-stopped
frontend:
build:
context: .
dockerfile: Dockerfile.frontend
ports:
- "8501:8501"
# PostgreSQL with pgvector
postgres:
image: pgvector/pgvector:pg16
container_name: jobforge-postgres
environment:
- BACKEND_URL=http://backend:8000
- POSTGRES_DB=jobforge
- POSTGRES_USER=jobforge
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- ./src/frontend:/app/src/frontend
- postgres_data:/var/lib/postgresql/data
- ./backups:/backups
networks:
- jobforge-network
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U jobforge -d jobforge"]
interval: 10s
timeout: 5s
retries: 5
# Nginx Reverse Proxy
nginx:
image: nginx:alpine
container_name: jobforge-nginx
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
depends_on:
- backend
command: python src/frontend/main.py
- jobforge-app
networks:
- jobforge-network
restart: unless-stopped
networks:
jobforge-network:
driver: bridge
volumes:
postgres_data:
driver: local
```
---
## 📁 MVP Project Structure
## 📁 Web Application Project Structure
```
jobforge-mvp/
job-forge/
├── docker-compose.yml
├── Dockerfile.backend
├── Dockerfile.frontend
├── requirements-backend.txt
├── requirements-frontend.txt
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── database/
│ └── init.sql
├── src/
│ ├── backend/
│ │ ├── main.py
│ │ ├── api/
│ │ │ ├── auth.py
│ │ │ ├── applications.py
│ │ │ ├── documents.py
│ │ │ └── processing.py
│ │ ├── services/
│ │ │ ├── auth_service.py
│ │ │ ├── application_service.py
│ │ │ ├── document_service.py
│ │ │ └── ai_orchestrator.py
│ │ ├── database/
│ │ │ ├── connection.py
│ │ │ └── models.py
│ │ └── models/
│ │ ├── requests.py
│ │ └── responses.py
│ ├── frontend/
│ │ ├── main.py
│ │ ├── components/
│ │ │ ├── sidebar.py
│ │ │ ├── topbar.py
│ │ │ └── editor.py
│ │ ├── pages/
│ │ │ ├── login.py
│ │ │ ├── dashboard.py
│ │ │ └── application.py
│ │ └── api_client/
│ │ └── client.py
│ ├── agents/
│ │ ├── research_agent.py
│ │ ├── resume_optimizer.py
│ │ ├── cover_letter_generator.py
│ │ └── claude_client.py
│ └── helpers/
│ ├── validators.py
│ └── formatters.py
└── user_data/
└── resumes/
├── pytest.ini
├── alembic.ini
├── CLAUDE.md
├── README.md
├── app/
│ ├── main.py # FastAPI + Dash application entry
│ ├── core/
│ │ ├── config.py # Application configuration
│ │ ├── database.py # Database connection and session
│ │ ├── security.py # JWT authentication utilities
│ │ └── exceptions.py # Custom exception handlers
│ ├── api/
│ │ ├── v1/
│ │ │ ├── auth.py # Authentication endpoints
│ │ │ ├── applications.py # Application CRUD endpoints
│ │ │ └── documents.py # Document management endpoints
│ │ └── dependencies.py # FastAPI dependencies
│ ├── models/
│ │ ├── user.py # User SQLAlchemy model
│ │ ├── application.py # Application SQLAlchemy model
│ │ └── document.py # Document SQLAlchemy model
│ ├── schemas/
│ │ ├── user.py # User Pydantic schemas
│ │ ├── application.py # Application Pydantic schemas
│ │ └── auth.py # Authentication schemas
│ ├── crud/
│ │ ├── user.py # User database operations
│ │ ├── application.py # Application database operations
│ │ └── document.py # Document database operations
│ ├── services/
│ │ ├── auth.py # Authentication service
│ │ ├── application.py # Application business logic
│ │ └── ai/
│ │ ├── claude_service.py # Claude API integration
│ │ ├── openai_service.py # OpenAI API integration
│ │ └── document_generator.py # AI document generation
│ └── frontend/
│ ├── app.py # Dash application setup
│ ├── layouts/
│ │ ├── dashboard.py # Main dashboard layout
│ │ ├── auth.py # Login/register layouts
│ │ └── application.py # Application detail layout
│ ├── components/
│ │ ├── navigation.py # Navigation components
│ │ ├── forms.py # Form components
│ │ └── modals.py # Modal components
│ └── callbacks/
│ ├── auth.py # Authentication callbacks
│ ├── application.py # Application callbacks
│ └── navigation.py # Navigation callbacks
├── alembic/
│ ├── versions/ # Database migration files
│ └── env.py # Alembic configuration
├── tests/
│ ├── conftest.py # Pytest configuration and fixtures
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── docs/
│ ├── README.md # Main documentation hub
│ ├── development/ # Development documentation
│ ├── infrastructure/ # Deployment documentation
│ └── testing/ # Testing documentation
├── nginx/
│ └── nginx.conf # Nginx configuration
├── logs/ # Application logs
├── uploads/ # File uploads
└── backups/ # Database backups
```
---
*This MVP architecture focuses on delivering the core job application workflow with essential features. It establishes the foundation for Phase 2 development while providing immediate value for personal job application management and concept validation.*
*This web application architecture provides a comprehensive, production-ready solution for AI-powered job application management. The FastAPI backend with Dash frontend delivers a modern web experience while maintaining scalability and security for prototype development and future enhancements.*

951
docs/team_management_guide.md
View File

@@ -1,951 +0,0 @@
# JobForge MVP - Team Management Guide
**Version:** 1.0.0
**Project:** JobForge MVP Development
**Timeline:** 8 Weeks (July - August 2025)
**Team Structure:** 6 Specialized Roles
**Last Updated:** July 2025
---
## 📋 Table of Contents
1. [Team Structure & Hierarchy](#team-structure--hierarchy)
2. [Role Definitions](#role-definitions)
3. [Communication Protocols](#communication-protocols)
4. [Development Process](#development-process)
5. [Quality Standards](#quality-standards)
6. [Meeting Framework](#meeting-framework)
7. [Documentation Standards](#documentation-standards)
8. [Escalation Procedures](#escalation-procedures)
9. [Performance Metrics](#performance-metrics)
10. [Standard Templates](#standard-templates)
---
## 🏗️ Team Structure & Hierarchy
### Organizational Chart
```mermaid
graph TD
PM[Project Manager] --> ARCH[Architect & Orchestrator]
PM --> BE[Backend Team]
PM --> FE[Frontend Team]
PM --> AI[AI Engineering Team]
PM --> DO[DevOps & Integration Team]
ARCH --> BE
ARCH --> FE
ARCH --> AI
ARCH --> DO
BE --> DO
FE --> DO
AI --> BE
```
### Reporting Structure
| Level | Role | Reports To | Direct Reports |
|-------|------|------------|----------------|
| **L1** | Project Manager | Stakeholders/CEO | All team leads |
| **L2** | Architect & Orchestrator | Project Manager | Technical guidance to all teams |
| **L2** | Backend Team Lead | Project Manager | Backend developers |
| **L2** | Frontend Team Lead | Project Manager | Frontend developers |
| **L2** | AI Engineering Team Lead | Project Manager | AI engineers |
| **L2** | DevOps & Integration Team Lead | Project Manager | DevOps engineers |
### Authority Matrix
| Decision Type | Project Manager | Architect | Team Leads | Team Members |
|---------------|-----------------|-----------|------------|--------------|
| Project Scope | **Decide** | Consult | Inform | Inform |
| Technical Architecture | Consult | **Decide** | Consult | Inform |
| Implementation Details | Inform | Consult | **Decide** | Responsible |
| Resource Allocation | **Decide** | Consult | Consult | Inform |
| Quality Standards | Consult | **Decide** | Responsible | Responsible |
| Release Decisions | **Decide** | Consult | Inform | Inform |
---
## 👥 Role Definitions
### 1. Project Manager
#### **Core Responsibilities**
- **Project Planning:** Define sprint goals, manage timeline, allocate resources
- **Risk Management:** Identify, assess, and mitigate project risks
- **Stakeholder Communication:** Regular status updates and expectation management
- **Team Coordination:** Facilitate cross-team collaboration and resolve blockers
- **Progress Tracking:** Monitor deliverables, milestones, and budget
#### **Key Deliverables**
- Weekly project status reports
- Sprint planning and retrospective facilitation
- Risk register and mitigation plans
- Resource allocation and capacity planning
- Stakeholder communication and updates
#### **Required Skills**
- Agile/Scrum methodology expertise
- Technical project management experience
- Excellent communication and leadership skills
- Risk assessment and mitigation
- Budget and resource management
#### **Daily Activities**
- **Morning:** Review overnight progress, check for blockers
- **Mid-day:** Attend standups, facilitate cross-team communication
- **Evening:** Update project tracking, prepare status reports
#### **Success Metrics**
- On-time delivery of sprint goals (100% target)
- Team velocity consistency (±15% variance)
- Stakeholder satisfaction scores (>8/10)
- Risk mitigation effectiveness (>90% issues resolved)
---
### 2. Architect & Orchestrator
#### **Core Responsibilities**
- **System Architecture:** Define and maintain overall system design
- **Technical Standards:** Establish coding standards, patterns, and best practices
- **Architecture Reviews:** Conduct regular technical reviews and approvals
- **Cross-Team Alignment:** Ensure technical consistency across all teams
- **Technology Decisions:** Evaluate and approve technology choices
#### **Key Deliverables**
- System architecture documentation and diagrams
- Technical standards and coding guidelines
- Architecture review reports and approvals
- Technology evaluation and recommendation reports
- Technical debt assessment and remediation plans
#### **Required Skills**
- Full-stack architecture experience
- Deep knowledge of Python, PostgreSQL, Docker
- API design and microservices architecture
- Code review and quality assessment
- Technical leadership and mentoring
#### **Daily Activities**
- **Morning:** Review pull requests and architecture compliance
- **Mid-day:** Conduct architecture reviews and technical discussions
- **Evening:** Update architecture documentation and standards
#### **Review Schedule**
- **Daily:** Code review and PR approvals
- **Weekly:** Architecture compliance review
- **Bi-weekly:** Technical debt assessment
- **Sprint End:** Architecture retrospective and improvements
#### **Success Metrics**
- Architecture compliance score (>95%)
- Technical debt ratio (<10%)
- Code review turnaround time (<4 hours)
- Cross-team technical consistency (>90%)
---
### 3. Backend Team
#### **Core Responsibilities**
- **API Development:** Build FastAPI endpoints per specification
- **Database Design:** Implement PostgreSQL schema with RLS policies
- **Business Logic:** Develop core application services and workflows
- **Integration:** Integrate with AI services and external APIs
- **Testing:** Write comprehensive unit and integration tests
#### **Key Deliverables**
- REST API endpoints with full documentation
- Database schema with migrations and seed data
- Business logic services and domain models
- API integration with AI services
- Comprehensive test suites (>80% coverage)
#### **Required Skills**
- Advanced Python (FastAPI, SQLAlchemy, AsyncIO)
- PostgreSQL database design and optimization
- REST API design and development
- Testing frameworks (pytest, mocking)
- Docker and containerization
#### **Team Structure**
- **Backend Team Lead:** Technical leadership, architecture compliance
- **Senior Backend Developer:** Complex features, AI integration
- **Backend Developer:** CRUD operations, testing, documentation
#### **Daily Activities**
- **Morning:** Review API requirements and database design
- **Mid-day:** Implement endpoints and business logic
- **Evening:** Write tests and update documentation
#### **Handoff Requirements**
- **To Frontend:** Complete API documentation with examples
- **To AI Team:** Integration endpoints and data models
- **To DevOps:** Docker configuration and deployment requirements
#### **Success Metrics**
- API endpoint completion rate (100% per sprint)
- Test coverage percentage (>80%)
- API response time (<500ms for CRUD operations)
- Bug density (<2 bugs per 1000 lines of code)
---
### 4. Frontend Team
#### **Core Responsibilities**
- **UI Development:** Build Dash + Mantine user interface components
- **User Experience:** Create intuitive and responsive user interactions
- **API Integration:** Implement frontend API client and data management
- **Visual Design:** Ensure professional and modern visual design
- **Testing:** Develop frontend testing strategies and implementation
#### **Key Deliverables**
- Complete user interface with all MVP features
- Responsive design for desktop and mobile
- API client library with error handling
- Component library and design system
- User experience testing and optimization
#### **Required Skills**
- Advanced Python (Dash, Plotly, component libraries)
- Modern web technologies (HTML5, CSS3, JavaScript)
- UI/UX design principles and responsive design
- API integration and state management
- Frontend testing and debugging
#### **Team Structure**
- **Frontend Team Lead:** UI architecture, UX decisions
- **Senior Frontend Developer:** Complex components, API integration
- **Frontend Developer:** Component development, styling, testing
#### **Daily Activities**
- **Morning:** Review UI requirements and design specifications
- **Mid-day:** Develop components and integrate with backend APIs
- **Evening:** Test user interactions and update documentation
#### **Handoff Requirements**
- **From Backend:** API documentation and endpoint availability
- **To DevOps:** Frontend build configuration and deployment needs
- **To PM:** User acceptance testing and demo preparation
#### **Success Metrics**
- Feature completion rate (100% per sprint)
- UI responsiveness score (>95% across devices)
- User experience satisfaction (>8/10 in testing)
- Frontend error rate (<1% of user interactions)
---
### 5. AI Engineering Team
#### **Core Responsibilities**
- **Prompt Engineering:** Develop and optimize Claude Sonnet 4 prompts
- **AI Integration:** Build AI agents for research, resume, and cover letter generation
- **Vector Operations:** Implement OpenAI embeddings and similarity search
- **Performance Optimization:** Optimize AI response times and accuracy
- **Quality Assurance:** Test AI outputs for consistency and relevance
#### **Key Deliverables**
- Research Agent with job analysis capabilities
- Resume Optimizer with multi-resume synthesis
- Cover Letter Generator with voice preservation
- Vector database integration for semantic search
- AI performance monitoring and optimization tools
#### **Required Skills**
- Advanced prompt engineering and LLM optimization
- Python AI/ML libraries (OpenAI, Anthropic APIs)
- Vector databases and semantic search
- Natural language processing and analysis
- AI testing and quality assurance methods
#### **Team Structure**
- **AI Team Lead:** AI strategy, prompt architecture
- **Senior AI Engineer:** Complex AI workflows, vector integration
- **AI Engineer:** Prompt development, testing, optimization
#### **Daily Activities**
- **Morning:** Review AI requirements and prompt specifications
- **Mid-day:** Develop and test AI agents and prompts
- **Evening:** Optimize performance and document AI behaviors
#### **Handoff Requirements**
- **To Backend:** AI service integration requirements and APIs
- **From Architect:** AI workflow specifications and quality criteria
- **To PM:** AI performance metrics and capability demonstrations
#### **Success Metrics**
- AI response accuracy (>90% relevance score)
- Processing time (<30 seconds per AI operation)
- Prompt effectiveness (>85% user satisfaction)
- AI service uptime (>99.5% availability)
---
### 6. DevOps & Integration Team
#### **Core Responsibilities**
- **Infrastructure Management:** Docker Compose orchestration and optimization
- **CI/CD Pipeline:** Gitea workflows, automated testing, and deployment
- **Integration Testing:** End-to-end system integration and testing
- **Quality Assurance:** Enforce quality standards and code review processes
- **Documentation Management:** Maintain project documentation and knowledge base
#### **Key Deliverables**
- Complete Docker development environment
- Automated CI/CD pipelines with quality gates
- Integration testing suite and monitoring
- Quality standards documentation and enforcement
- Production deployment configuration and monitoring
#### **Required Skills**
- Docker and container orchestration
- CI/CD pipeline design and implementation
- Automated testing and quality assurance
- System integration and monitoring
- Technical documentation and knowledge management
#### **Team Structure**
- **DevOps & Integration Lead:** Infrastructure architecture, quality standards
- **Senior DevOps Engineer:** CI/CD pipelines, production deployment
- **Integration Engineer:** System integration, testing, documentation
#### **Daily Activities**
- **Morning:** Review system health, CI/CD pipeline status
- **Mid-day:** Support integration needs, resolve deployment issues
- **Evening:** Update documentation, monitor quality metrics
#### **Handoff Requirements**
- **From All Teams:** Code, configuration, and deployment requirements
- **To PM:** System status, quality metrics, deployment readiness
- **To Architect:** Infrastructure compliance and optimization recommendations
#### **Success Metrics**
- CI/CD pipeline success rate (>95%)
- Integration test pass rate (>98%)
- System uptime (>99.9% during development)
- Documentation completeness (>90% coverage)
---
## 📞 Communication Protocols
### Communication Matrix
| Communication Type | Frequency | Participants | Duration | Format |
|-------------------|-----------|--------------|----------|--------|
| **Daily Standup** | Daily | All team leads + PM | 15 min | Synchronous |
| **Team Standup** | Daily | Team members + Team lead | 10 min | Synchronous |
| **Architecture Review** | Weekly | Architect + All leads | 30 min | Synchronous |
| **Sprint Planning** | Weekly | All team leads + PM | 60 min | Synchronous |
| **Sprint Retrospective** | Weekly | All team leads + PM | 45 min | Synchronous |
| **Technical Sync** | As needed | Relevant teams | 30 min | Synchronous |
| **Status Updates** | Weekly | PM + Stakeholders | 30 min | Synchronous/Async |
### Communication Guidelines
#### **Daily Standup Format**
Each team lead reports:
1. **Yesterday:** What was completed
2. **Today:** What will be worked on
3. **Blockers:** Any impediments or dependencies
4. **Risks:** Emerging risks or concerns
#### **Cross-Team Communication Rules**
- **Backend ↔ Frontend:** API changes require 24-hour notice
- **AI ↔ Backend:** Integration requirements must be documented
- **DevOps ↔ All Teams:** Infrastructure changes require approval
- **Architect ↔ All Teams:** Technical decisions require consultation
#### **Escalation Matrix**
| Issue Level | Response Time | Escalation Path |
|-------------|---------------|-----------------|
| **Low** | 24 hours | Team Lead → PM |
| **Medium** | 4 hours | Team Lead → PM → Architect |
| **High** | 1 hour | Team Lead → PM + Architect |
| **Critical** | 30 minutes | All leads + PM + Architect |
---
## 🔄 Development Process
### Sprint Structure (1-Week Sprints)
#### **Monday: Sprint Planning**
- **9:00 AM:** Sprint planning meeting (60 min)
- **10:30 AM:** Team breakouts for task estimation
- **11:30 AM:** Cross-team dependency identification
- **12:00 PM:** Sprint commitment and kick-off
#### **Tuesday-Thursday: Development**
- **9:00 AM:** Daily standup (15 min)
- **Development work according to team schedules**
- **4:00 PM:** Daily progress check-in
- **As needed:** Technical sync meetings
#### **Friday: Review & Retrospective**
- **9:00 AM:** Sprint demo preparation
- **10:00 AM:** Sprint review and demo (60 min)
- **11:30 AM:** Sprint retrospective (45 min)
- **1:00 PM:** Next sprint preparation
- **3:00 PM:** Week wrap-up and documentation
### Definition of Done
#### **Backend Features**
- [ ] API endpoints implemented per specification
- [ ] Unit tests written with >80% coverage
- [ ] Integration tests passing
- [ ] API documentation updated
- [ ] Code reviewed and approved by Architect
- [ ] Database migrations tested
- [ ] Error handling implemented
#### **Frontend Features**
- [ ] UI components implemented per design
- [ ] Responsive design tested on multiple devices
- [ ] API integration working correctly
- [ ] User acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Documentation updated
- [ ] Browser compatibility tested
#### **AI Features**
- [ ] Prompts developed and optimized
- [ ] AI agents tested for accuracy and performance
- [ ] Integration with backend services working
- [ ] Performance benchmarks met
- [ ] Error handling and fallbacks implemented
- [ ] Documentation and examples provided
- [ ] Quality assurance testing completed
#### **DevOps Features**
- [ ] Infrastructure changes deployed and tested
- [ ] CI/CD pipelines updated and working
- [ ] Documentation updated
- [ ] Security review completed
- [ ] Performance impact assessed
- [ ] Rollback procedures tested
- [ ] Monitoring and alerting configured
---
## 🎯 Quality Standards
### Code Quality Requirements
#### **General Standards**
- **Type Hints:** Required for all public functions and methods
- **Documentation:** Docstrings for all classes and public methods
- **Testing:** Minimum 80% code coverage for backend, 70% for frontend
- **Code Review:** All changes require approval from team lead + architect
- **Security:** No hardcoded secrets, proper input validation
#### **Backend Standards**
```python
# Example of required code quality
from typing import Optional, List
from pydantic import BaseModel
class ApplicationService:
"""Service for managing job applications with proper error handling."""
async def create_application(
self,
user_id: str,
application_data: CreateApplicationRequest
) -> Application:
"""
Create a new job application for the specified user.
Args:
user_id: UUID of the authenticated user
application_data: Validated application creation data
Returns:
Application: Created application with generated ID
Raises:
ValidationError: If application data is invalid
DatabaseError: If database operation fails
"""
# Implementation with proper error handling
pass
```
#### **Frontend Standards**
- **Component Documentation:** Clear docstrings for all components
- **Props Validation:** Type hints and validation for all component props
- **Error Boundaries:** Proper error handling for API failures
- **Accessibility:** WCAG 2.1 AA compliance for all UI components
- **Performance:** Components should render in <100ms
#### **AI Standards**
- **Prompt Documentation:** Clear documentation of prompt purpose and expected outputs
- **Error Handling:** Graceful degradation when AI services are unavailable
- **Performance Monitoring:** Response time and accuracy tracking
- **Quality Assurance:** Systematic testing of AI outputs for consistency
### Quality Gates
#### **Pre-Commit Checks**
- [ ] Code formatting (Black, isort)
- [ ] Type checking (mypy)
- [ ] Linting (flake8, pylint)
- [ ] Security scanning (bandit)
- [ ] Test execution (pytest)
#### **Pull Request Checks**
- [ ] All CI/CD pipeline checks pass
- [ ] Code coverage requirements met
- [ ] Architecture compliance verified
- [ ] Security review completed
- [ ] Documentation updated
- [ ] Performance impact assessed
#### **Sprint Completion Checks**
- [ ] All features meet Definition of Done
- [ ] Integration testing passes
- [ ] Performance benchmarks met
- [ ] Security review completed
- [ ] Documentation complete and accurate
- [ ] Demo preparation completed
---
## 📅 Meeting Framework
### Meeting Templates
#### **Daily Standup Template**
```
Date: [Date]
Sprint: [Sprint Number]
Facilitator: [Project Manager]
Team Updates:
□ Backend Team - [Lead Name]
- Completed:
- Today:
- Blockers:
□ Frontend Team - [Lead Name]
- Completed:
- Today:
- Blockers:
□ AI Team - [Lead Name]
- Completed:
- Today:
- Blockers:
□ DevOps Team - [Lead Name]
- Completed:
- Today:
- Blockers:
Cross-Team Dependencies:
- [Dependency 1]
- [Dependency 2]
Action Items:
- [Action Item 1] - Owner: [Name] - Due: [Date]
- [Action Item 2] - Owner: [Name] - Due: [Date]
```
#### **Sprint Planning Template**
```
Sprint Planning - Sprint [Number]
Date: [Date]
Duration: [Start Date] to [End Date]
Sprint Goal:
[Clear, concise statement of what will be achieved]
Team Capacity:
- Backend Team: [X] story points
- Frontend Team: [X] story points
- AI Team: [X] story points
- DevOps Team: [X] story points
Selected Stories:
□ [Story 1] - [Team] - [Points] - [Priority]
□ [Story 2] - [Team] - [Points] - [Priority]
□ [Story 3] - [Team] - [Points] - [Priority]
Dependencies Identified:
- [Dependency 1] - Teams: [A] → [B] - Risk: [Low/Medium/High]
- [Dependency 2] - Teams: [A] → [B] - Risk: [Low/Medium/High]
Risks and Mitigation:
- [Risk 1] - Probability: [%] - Impact: [High/Medium/Low] - Mitigation: [Plan]
- [Risk 2] - Probability: [%] - Impact: [High/Medium/Low] - Mitigation: [Plan]
Sprint Commitment:
Team leads confirm commitment to sprint goal and deliverables.
□ Backend Team Lead - [Name]
□ Frontend Team Lead - [Name]
□ AI Team Lead - [Name]
□ DevOps Team Lead - [Name]
```
#### **Architecture Review Template**
```
Architecture Review - Week [Number]
Date: [Date]
Reviewer: [Architect Name]
Components Reviewed:
□ Backend API Design
- Compliance: [Green/Yellow/Red]
- Issues: [List any issues]
- Recommendations: [List recommendations]
□ Frontend Architecture
- Compliance: [Green/Yellow/Red]
- Issues: [List any issues]
- Recommendations: [List recommendations]
□ AI Integration
- Compliance: [Green/Yellow/Red]
- Issues: [List any issues]
- Recommendations: [List recommendations]
□ Infrastructure Design
- Compliance: [Green/Yellow/Red]
- Issues: [List any issues]
- Recommendations: [List recommendations]
Technical Debt Assessment:
- Current Level: [Low/Medium/High]
- Priority Items: [List top 3 items]
- Remediation Plan: [Summary of approach]
Decisions Made:
- [Decision 1] - Rationale: [Explanation]
- [Decision 2] - Rationale: [Explanation]
Action Items:
- [Action 1] - Owner: [Name] - Due: [Date]
- [Action 2] - Owner: [Name] - Due: [Date]
```
---
## 📋 Documentation Standards
### Required Documentation
#### **API Documentation**
- **OpenAPI Specification:** Complete API documentation with examples
- **Integration Guide:** How to integrate with each API endpoint
- **Error Handling:** Comprehensive error codes and responses
- **Authentication:** Security requirements and implementation
#### **Code Documentation**
- **README Files:** Clear setup and usage instructions
- **Inline Comments:** Complex logic explanation and business rules
- **Architecture Decisions:** ADR (Architecture Decision Records)
- **Deployment Guide:** Step-by-step deployment instructions
#### **Process Documentation**
- **Team Onboarding:** New team member setup guide
- **Development Workflow:** Git branching and development process
- **Quality Standards:** Code quality and review requirements
- **Troubleshooting:** Common issues and resolution steps
### Documentation Review Process
#### **Weekly Documentation Review**
- **Owner:** DevOps & Integration Team Lead
- **Participants:** All team leads
- **Duration:** 30 minutes
- **Agenda:** Review documentation completeness and accuracy
#### **Documentation Standards**
- **Format:** Markdown files in `/docs` directory
- **Structure:** Consistent headings, table of contents, examples
- **Updates:** Documentation updated with each feature delivery
- **Review:** All documentation changes require peer review
---
## 🚨 Escalation Procedures
### Issue Classification
#### **Priority Levels**
| Priority | Response Time | Definition | Examples |
|----------|---------------|------------|----------|
| **P0 - Critical** | 30 minutes | System down, security breach | Database crash, API completely down |
| **P1 - High** | 2 hours | Major feature broken, blocking | Authentication broken, AI services down |
| **P2 - Medium** | 8 hours | Minor feature issues, performance | Slow API responses, UI bugs |
| **P3 - Low** | 24 hours | Enhancement requests, documentation | Feature improvements, doc updates |
### Escalation Flow
#### **Technical Issues**
```
Developer → Team Lead → Architect → Project Manager → Stakeholders
```
#### **Resource/Timeline Issues**
```
Team Lead → Project Manager → Stakeholders
```
#### **Quality/Standards Issues**
```
Team Member → Team Lead → Architect → Project Manager
```
#### **Cross-Team Conflicts**
```
Team Leads → Project Manager → Architect (if technical) → Resolution
```
### Crisis Management
#### **Critical Issue Response**
1. **Immediate (0-15 min):**
- Issue reporter creates critical incident ticket
- Notify Project Manager and Architect immediately
- Form incident response team
2. **Short-term (15-60 min):**
- Assess impact and root cause
- Implement temporary workaround if possible
- Communicate status to stakeholders
3. **Resolution (1+ hours):**
- Develop and implement permanent fix
- Test fix thoroughly in staging environment
- Deploy fix and monitor system health
- Conduct post-incident review
---
## 📊 Performance Metrics
### Team Performance Metrics
#### **Delivery Metrics**
| Metric | Target | Measurement | Frequency |
|--------|--------|-------------|-----------|
| **Sprint Goal Achievement** | 100% | Goals completed vs planned | Weekly |
| **Story Point Velocity** | ±15% variance | Points delivered per sprint | Weekly |
| **Feature Delivery** | On schedule | Features completed on time | Weekly |
| **Defect Rate** | <5% | Bugs found post-delivery | Weekly |
#### **Quality Metrics**
| Metric | Target | Measurement | Frequency |
|--------|--------|-------------|-----------|
| **Code Coverage** | >80% | Automated test coverage | Daily |
| **Code Review Time** | <4 hours | Time from PR to approval | Daily |
| **Build Success Rate** | >95% | CI/CD pipeline success | Daily |
| **Documentation Coverage** | >90% | Features documented | Weekly |
#### **Team Health Metrics**
| Metric | Target | Measurement | Frequency |
|--------|--------|-------------|-----------|
| **Team Satisfaction** | >8/10 | Weekly team survey | Weekly |
| **Collaboration Score** | >8/10 | Cross-team effectiveness | Weekly |
| **Knowledge Sharing** | >3 sessions/week | Tech talks, reviews | Weekly |
| **Blockers Resolution** | <24 hours | Time to resolve blockers | Daily |
### Individual Performance Metrics
#### **Backend Team**
- API endpoint delivery rate (100% per sprint)
- Code quality score (>90%)
- Test coverage percentage (>80%)
- Code review participation rate (100%)
#### **Frontend Team**
- UI component completion rate (100% per sprint)
- User experience satisfaction (>8/10)
- Browser compatibility score (>95%)
- Design system compliance (>90%)
#### **AI Team**
- AI model accuracy (>90%)
- Prompt optimization rate (>85% user satisfaction)
- Processing time improvements (weekly optimization)
- AI service uptime (>99.5%)
#### **DevOps Team**
- Infrastructure uptime (>99.9%)
- CI/CD pipeline reliability (>95% success rate)
- Documentation completeness (>90%)
- Security compliance score (100%)
---
## 📝 Standard Templates
### Handoff Document Template
```markdown
# Team Handoff Document
**From Team:** [Source Team]
**To Team:** [Destination Team]
**Date:** [Date]
**Sprint:** [Sprint Number]
## Deliverables
- [Deliverable 1] - Status: [Complete/Partial/Pending]
- [Deliverable 2] - Status: [Complete/Partial/Pending]
## Technical Specifications
- **API Endpoints:** [List with documentation links]
- **Data Models:** [List with schema definitions]
- **Configuration:** [Environment variables, settings]
- **Dependencies:** [External services, libraries]
## Testing Information
- **Test Coverage:** [Percentage]
- **Test Results:** [Link to test report]
- **Known Issues:** [List any known problems]
- **Testing Instructions:** [How to test the deliverables]
## Documentation
- **Technical Docs:** [Links to relevant documentation]
- **API Documentation:** [Link to API docs]
- **Setup Instructions:** [How to run/deploy]
- **Troubleshooting:** [Common issues and solutions]
## Next Steps
- [Action item 1] - Owner: [Name] - Due: [Date]
- [Action item 2] - Owner: [Name] - Due: [Date]
## Contact Information
- **Primary Contact:** [Name] - [Email] - [Slack/Teams]
- **Secondary Contact:** [Name] - [Email] - [Slack/Teams]
## Sign-off
- **Source Team Lead:** [Name] - [Date] - [Signature]
- **Destination Team Lead:** [Name] - [Date] - [Signature]
```
### Status Report Template
```markdown
# Weekly Status Report
**Week of:** [Date Range]
**Sprint:** [Sprint Number]
**Report Date:** [Date]
**Prepared by:** [Project Manager Name]
## Executive Summary
[2-3 sentence summary of week's progress and status]
## Sprint Progress
- **Sprint Goal:** [Goal statement]
- **Completion Rate:** [X]% ([Y] of [Z] story points completed)
- **On Track for Sprint Goal:** [Yes/No/At Risk]
## Team Status
### Backend Team
- **Completed:** [List major accomplishments]
- **In Progress:** [Current work]
- **Planned:** [Next week's priorities]
- **Blockers:** [Any impediments]
- **Health:** [Green/Yellow/Red]
### Frontend Team
- **Completed:** [List major accomplishments]
- **In Progress:** [Current work]
- **Planned:** [Next week's priorities]
- **Blockers:** [Any impediments]
- **Health:** [Green/Yellow/Red]
### AI Engineering Team
- **Completed:** [List major accomplishments]
- **In Progress:** [Current work]
- **Planned:** [Next week's priorities]
- **Blockers:** [Any impediments]
- **Health:** [Green/Yellow/Red]
### DevOps & Integration Team
- **Completed:** [List major accomplishments]
- **In Progress:** [Current work]
- **Planned:** [Next week's priorities]
- **Blockers:** [Any impediments]
- **Health:** [Green/Yellow/Red]
## Key Metrics
| Metric | Target | Actual | Status |
|--------|--------|---------|--------|
| Sprint Velocity | [X] points | [Y] points | [Green/Yellow/Red] |
| Code Coverage | >80% | [X]% | [Green/Yellow/Red] |
| Build Success Rate | >95% | [X]% | [Green/Yellow/Red] |
| Team Satisfaction | >8/10 | [X]/10 | [Green/Yellow/Red] |
## Risks and Issues
| Risk/Issue | Impact | Probability | Mitigation | Owner | Due Date |
|------------|--------|-------------|------------|--------|----------|
| [Risk 1] | [High/Med/Low] | [High/Med/Low] | [Plan] | [Name] | [Date] |
| [Risk 2] | [High/Med/Low] | [High/Med/Low] | [Plan] | [Name] | [Date] |
## Decisions Made
- [Decision 1] - Rationale: [Explanation] - Impact: [Description]
- [Decision 2] - Rationale: [Explanation] - Impact: [Description]
## Next Week Focus
- [Priority 1]
- [Priority 2]
- [Priority 3]
## Action Items
- [Action 1] - Owner: [Name] - Due: [Date]
- [Action 2] - Owner: [Name] - Due: [Date]
## Attachments
- [Link to detailed metrics dashboard]
- [Link to sprint burndown chart]
- [Link to risk register]
```
---
## 🎯 Implementation Checklist
### Week 1: Team Formation
- [ ] All team members hired and onboarded
- [ ] Role responsibilities communicated and accepted
- [ ] Communication tools set up (Slack, Gitea, etc.)
- [ ] Development environment access provided
- [ ] First sprint planning meeting scheduled
### Week 2: Process Implementation
- [ ] Daily standup schedule established
- [ ] Sprint planning process implemented
- [ ] Architecture review process started
- [ ] Quality standards documented and communicated
- [ ] Documentation standards established
### Week 3: Team Optimization
- [ ] First retrospective completed with improvements
- [ ] Cross-team communication protocols refined
- [ ] Performance metrics baseline established
- [ ] Escalation procedures tested and refined
- [ ] Team health survey implemented
### Ongoing: Continuous Improvement
- [ ] Weekly retrospectives with action items
- [ ] Monthly team satisfaction surveys
- [ ] Quarterly process review and optimization
- [ ] Continuous metrics monitoring and improvement
- [ ] Regular team building and knowledge sharing
---
*This team management guide provides the foundation for successful JobForge MVP development with clear roles, processes, and standards for professional team coordination and delivery.*

769
docs/testing/qa_procedures.md Normal file
View File

@@ -0,0 +1,769 @@
# QA Procedures - Job Forge
## Overview
This document outlines the Quality Assurance procedures for Job Forge, including testing strategies, quality gates, bug reporting, and release validation processes.
## Testing Strategy
### Test Pyramid for Job Forge
```
/\ E2E Tests (10%)
/ \ - Critical user workflows
/____\ - Cross-browser testing
/ \ Integration Tests (20%)
/ \ - API endpoint testing
\ / - Database RLS validation
\______/ - AI service integration
\ / Unit Tests (70%)
\ / - Business logic
\/ - Authentication
- Data validation
```
### 1. Unit Testing (70% of tests)
#### Test Categories
- **Authentication & Security**: Login, JWT tokens, password hashing
- **Business Logic**: Application CRUD operations, status transitions
- **Data Validation**: Pydantic model validation, input sanitization
- **AI Integration**: Service mocking, error handling, rate limiting
- **Database Operations**: RLS policies, query optimization
#### Running Unit Tests
```bash
# Run all unit tests
pytest tests/unit/ -v
# Run specific test file
pytest tests/unit/test_auth_service.py -v
# Run with coverage
pytest tests/unit/ --cov=app --cov-report=html
# Run tests matching pattern
pytest -k "test_auth" -v
```
#### Unit Test Example
```python
# tests/unit/test_application_service.py
import pytest
from unittest.mock import AsyncMock
@pytest.mark.asyncio
async def test_create_application_with_ai_generation(test_db, test_user, mock_claude_service):
"""Test application creation with AI cover letter generation."""
# Arrange
mock_claude_service.generate_cover_letter.return_value = "Generated cover letter"
app_data = ApplicationCreate(
company_name="AI Corp",
role_title="ML Engineer",
job_description="Python ML position",
status="draft"
)
# Act
with patch('app.services.ai.claude_service.ClaudeService', return_value=mock_claude_service):
application = await create_application(test_db, app_data, test_user.id)
# Assert
assert application.company_name == "AI Corp"
assert application.cover_letter == "Generated cover letter"
mock_claude_service.generate_cover_letter.assert_called_once()
```
### 2. Integration Testing (20% of tests)
#### Test Categories
- **API Integration**: Full request/response testing with authentication
- **Database Integration**: Multi-tenant isolation, RLS policy validation
- **AI Service Integration**: Real API calls with mocking strategies
- **Service Layer Integration**: Complete workflow testing
#### Running Integration Tests
```bash
# Run integration tests
pytest tests/integration/ -v
# Run with test database
pytest tests/integration/ --db-url=postgresql://test:test@localhost:5432/jobforge_test
# Run specific integration test
pytest tests/integration/test_api_auth.py::TestAuthenticationEndpoints::test_complete_registration_flow -v
```
#### Integration Test Example
```python
# tests/integration/test_api_applications.py
@pytest.mark.asyncio
async def test_complete_application_workflow(async_client, test_user_token):
"""Test complete application workflow from creation to update."""
headers = {"Authorization": f"Bearer {test_user_token}"}
# 1. Create application
app_data = {
"company_name": "Integration Test Corp",
"role_title": "Software Engineer",
"job_description": "Full-stack developer position",
"status": "draft"
}
create_response = await async_client.post(
"/api/v1/applications/",
json=app_data,
headers=headers
)
assert create_response.status_code == 201
app_id = create_response.json()["id"]
# 2. Get application
get_response = await async_client.get(
f"/api/v1/applications/{app_id}",
headers=headers
)
assert get_response.status_code == 200
# 3. Update application status
update_response = await async_client.put(
f"/api/v1/applications/{app_id}",
json={"status": "applied"},
headers=headers
)
assert update_response.status_code == 200
assert update_response.json()["status"] == "applied"
```
### 3. End-to-End Testing (10% of tests)
#### Test Categories
- **Critical User Journeys**: Registration → Login → Create Application → Generate Cover Letter
- **Cross-browser Compatibility**: Chrome, Firefox, Safari, Edge
- **Performance Testing**: Response times, concurrent users
- **Error Scenario Testing**: Network failures, service outages
#### E2E Test Tools Setup
```bash
# Install Playwright for E2E testing
pip install playwright
playwright install
# Run E2E tests
pytest tests/e2e/ -v --headed # With browser UI
pytest tests/e2e/ -v # Headless mode
```
#### E2E Test Example
```python
# tests/e2e/test_user_workflows.py
import pytest
from playwright.async_api import async_playwright
@pytest.mark.asyncio
async def test_complete_user_journey():
"""Test complete user journey from registration to application creation."""
async with async_playwright() as p:
browser = await p.chromium.launch()
page = await browser.new_page()
try:
# 1. Navigate to registration
await page.goto("http://localhost:8000/register")
# 2. Fill registration form
await page.fill('[data-testid="email-input"]', 'e2e@test.com')
await page.fill('[data-testid="password-input"]', 'E2EPassword123!')
await page.fill('[data-testid="first-name-input"]', 'E2E')
await page.fill('[data-testid="last-name-input"]', 'User')
# 3. Submit registration
await page.click('[data-testid="register-button"]')
# 4. Verify redirect to dashboard
await page.wait_for_url("**/dashboard")
# 5. Create application
await page.click('[data-testid="new-application-button"]')
await page.fill('[data-testid="company-input"]', 'E2E Test Corp')
await page.fill('[data-testid="role-input"]', 'Test Engineer')
# 6. Submit application
await page.click('[data-testid="save-application-button"]')
# 7. Verify application appears
await page.wait_for_selector('[data-testid="application-card"]')
# 8. Verify application details
company_text = await page.text_content('[data-testid="company-name"]')
assert company_text == "E2E Test Corp"
finally:
await browser.close()
```
## Quality Gates
### 1. Code Quality Gates
#### Pre-commit Hooks
```bash
# Install pre-commit hooks
pip install pre-commit
pre-commit install
# Run hooks manually
pre-commit run --all-files
```
#### .pre-commit-config.yaml
```yaml
repos:
- repo: https://github.com/psf/black
rev: 23.7.0
hooks:
- id: black
language_version: python3.12
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: v0.0.284
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.5.1
hooks:
- id: mypy
additional_dependencies: [pydantic, sqlalchemy]
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
```
#### Quality Metrics Thresholds
```bash
# Code coverage minimum: 80%
pytest --cov=app --cov-fail-under=80
# Complexity maximum: 10
ruff check --select=C901
# Type coverage minimum: 90%
mypy app/ --strict
```
### 2. Functional Quality Gates
#### API Response Time Requirements
- **Authentication endpoints**: < 200ms
- **CRUD operations**: < 500ms
- **AI generation endpoints**: < 30 seconds
- **Dashboard loading**: < 2 seconds
#### Reliability Requirements
- **Uptime**: > 99% during testing
- **Error rate**: < 1% for non-AI operations
- **AI service fallback**: Must handle service failures gracefully
### 3. Security Quality Gates
#### Security Testing Checklist
```yaml
authentication_security:
- [ ] JWT tokens expire correctly
- [ ] Password hashing is secure (bcrypt)
- [ ] Session management is stateless
- [ ] Rate limiting prevents brute force
authorization_security:
- [ ] RLS policies enforce user isolation
- [ ] API endpoints require proper authentication
- [ ] Users cannot access other users' data
- [ ] Admin endpoints are properly protected
input_validation:
- [ ] All API inputs are validated
- [ ] SQL injection prevention works
- [ ] XSS prevention is implemented
- [ ] File upload validation is secure
data_protection:
- [ ] Sensitive data is encrypted
- [ ] API keys are properly secured
- [ ] Environment variables contain no secrets
- [ ] Database connections are secure
```
## Bug Reporting and Management
### 1. Bug Classification
#### Severity Levels
- **Critical**: Application crashes, data loss, security vulnerabilities
- **High**: Major features not working, authentication failures
- **Medium**: Minor features broken, UI issues, performance problems
- **Low**: Cosmetic issues, minor improvements, documentation errors
#### Priority Levels
- **P0**: Fix immediately (< 2 hours)
- **P1**: Fix within 24 hours
- **P2**: Fix within 1 week
- **P3**: Fix in next release cycle
### 2. Bug Report Template
#### GitHub Issue Template
```markdown
## Bug Report
### Summary
Brief description of the bug
### Environment
- **OS**: macOS 14.0 / Windows 11 / Ubuntu 22.04
- **Browser**: Chrome 118.0 / Firefox 119.0 / Safari 17.0
- **Python Version**: 3.12.0
- **FastAPI Version**: 0.104.1
### Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Enter data '...'
4. See error
### Expected Behavior
What should happen
### Actual Behavior
What actually happens
### Screenshots/Logs
```
Error logs or screenshots
```
### Additional Context
Any other context about the problem
### Severity/Priority
- [ ] Critical
- [ ] High
- [ ] Medium
- [ ] Low
```
### 3. Bug Triage Process
#### Weekly Bug Triage Meeting
1. **Review new bugs**: Assign severity and priority
2. **Update existing bugs**: Check progress and blockers
3. **Close resolved bugs**: Verify fixes and close tickets
4. **Plan bug fixes**: Assign to sprints based on priority
#### Bug Assignment Criteria
- **Critical/P0**: Technical Lead + DevOps
- **High/P1**: Full-stack Developer
- **Medium/P2**: QA Engineer + Developer collaboration
- **Low/P3**: Next available developer
## Test Data Management
### 1. Test Data Strategy
#### Test Database Setup
```bash
# Create test database
createdb jobforge_test
# Run test migrations
DATABASE_URL=postgresql://test:test@localhost/jobforge_test alembic upgrade head
# Seed test data
python scripts/seed_test_data.py
```
#### Test Data Factory
```python
# tests/factories.py
import factory
from app.models.user import User
from app.models.application import Application
class UserFactory(factory.Factory):
class Meta:
model = User
email = factory.Sequence(lambda n: f"user{n}@test.com")
password_hash = "$2b$12$hash"
first_name = "Test"
last_name = factory.Sequence(lambda n: f"User{n}")
class ApplicationFactory(factory.Factory):
class Meta:
model = Application
company_name = factory.Faker('company')
role_title = factory.Faker('job')
job_description = factory.Faker('text', max_nb_chars=500)
status = "draft"
user = factory.SubFactory(UserFactory)
```
### 2. Test Environment Management
#### Environment Isolation
```yaml
# docker-compose.test.yml
version: '3.8'
services:
test-db:
image: pgvector/pgvector:pg16
environment:
- POSTGRES_DB=jobforge_test
- POSTGRES_USER=test
- POSTGRES_PASSWORD=test
ports:
- "5433:5432"
tmpfs:
- /var/lib/postgresql/data # In-memory for speed
test-app:
build: .
environment:
- DATABASE_URL=postgresql://test:test@test-db:5432/jobforge_test
- TESTING=true
depends_on:
- test-db
```
#### Test Data Cleanup
```python
# tests/conftest.py
@pytest.fixture(autouse=True)
async def cleanup_test_data(test_db):
"""Clean up test data after each test."""
yield
# Truncate all tables
await test_db.execute("TRUNCATE TABLE applications CASCADE")
await test_db.execute("TRUNCATE TABLE users CASCADE")
await test_db.commit()
```
## Performance Testing
### 1. Load Testing with Locust
#### Installation and Setup
```bash
# Install locust
pip install locust
# Run load tests
locust -f tests/performance/locustfile.py --host=http://localhost:8000
```
#### Load Test Example
```python
# tests/performance/locustfile.py
from locust import HttpUser, task, between
import json
class JobForgeUser(HttpUser):
wait_time = between(1, 3)
def on_start(self):
"""Login user on start."""
response = self.client.post("/api/auth/login", data={
"username": "test@example.com",
"password": "testpass123"
})
if response.status_code == 200:
self.token = response.json()["access_token"]
self.headers = {"Authorization": f"Bearer {self.token}"}
@task(3)
def get_applications(self):
"""Get user applications."""
self.client.get("/api/v1/applications/", headers=self.headers)
@task(1)
def create_application(self):
"""Create new application."""
app_data = {
"company_name": "Load Test Corp",
"role_title": "Test Engineer",
"job_description": "Performance testing position",
"status": "draft"
}
self.client.post(
"/api/v1/applications/",
json=app_data,
headers=self.headers
)
@task(1)
def generate_cover_letter(self):
"""Generate AI cover letter (expensive operation)."""
# Get first application
response = self.client.get("/api/v1/applications/", headers=self.headers)
if response.status_code == 200:
applications = response.json()
if applications:
app_id = applications[0]["id"]
self.client.post(
f"/api/v1/applications/{app_id}/generate-cover-letter",
headers=self.headers
)
```
### 2. Performance Benchmarks
#### Response Time Targets
```python
# tests/performance/test_benchmarks.py
import pytest
import time
import statistics
@pytest.mark.performance
@pytest.mark.asyncio
async def test_api_response_times(async_client, test_user_token):
"""Test API response time benchmarks."""
headers = {"Authorization": f"Bearer {test_user_token}"}
# Test multiple requests
response_times = []
for _ in range(50):
start_time = time.time()
response = await async_client.get("/api/v1/applications/", headers=headers)
assert response.status_code == 200
response_time = (time.time() - start_time) * 1000 # Convert to ms
response_times.append(response_time)
# Analyze results
avg_time = statistics.mean(response_times)
p95_time = statistics.quantiles(response_times, n=20)[18] # 95th percentile
# Assert performance requirements
assert avg_time < 200, f"Average response time {avg_time}ms exceeds 200ms limit"
assert p95_time < 500, f"95th percentile {p95_time}ms exceeds 500ms limit"
print(f"Average response time: {avg_time:.2f}ms")
print(f"95th percentile: {p95_time:.2f}ms")
```
## Release Testing Procedures
### 1. Pre-Release Testing Checklist
#### Functional Testing
```yaml
authentication_testing:
- [ ] User registration works
- [ ] User login/logout works
- [ ] JWT token validation works
- [ ] Password reset works (if implemented)
application_management:
- [ ] Create application works
- [ ] View applications works
- [ ] Update application works
- [ ] Delete application works
- [ ] Application status transitions work
ai_integration:
- [ ] Cover letter generation works
- [ ] AI service error handling works
- [ ] Rate limiting is enforced
- [ ] Fallback mechanisms work
data_security:
- [ ] User data isolation works
- [ ] RLS policies are enforced
- [ ] No data leakage between users
- [ ] Sensitive data is protected
```
#### Cross-Browser Testing
```yaml
browsers_to_test:
chrome:
- [ ] Latest version
- [ ] Previous major version
firefox:
- [ ] Latest version
- [ ] ESR version
safari:
- [ ] Latest version (macOS/iOS)
edge:
- [ ] Latest version
mobile_testing:
- [ ] iOS Safari
- [ ] Android Chrome
- [ ] Responsive design works
- [ ] Touch interactions work
```
### 2. Release Validation Process
#### Staging Environment Testing
```bash
# Deploy to staging
docker-compose -f docker-compose.staging.yml up -d
# Run full test suite against staging
pytest tests/ --base-url=https://staging.jobforge.com
# Run smoke tests
pytest tests/smoke/ -v
# Performance testing
locust -f tests/performance/locustfile.py --host=https://staging.jobforge.com --users=50 --spawn-rate=5 --run-time=5m
```
#### Production Deployment Checklist
```yaml
pre_deployment:
- [ ] All tests passing in CI/CD
- [ ] Code review completed
- [ ] Database migrations tested
- [ ] Environment variables updated
- [ ] SSL certificates valid
- [ ] Backup created
deployment:
- [ ] Deploy with zero downtime
- [ ] Health checks passing
- [ ] Database migrations applied
- [ ] Cache cleared if needed
- [ ] CDN updated if needed
post_deployment:
- [ ] Smoke tests passing
- [ ] Performance metrics normal
- [ ] Error rates acceptable
- [ ] User workflows tested
- [ ] Rollback plan ready
```
## Continuous Testing Integration
### 1. CI/CD Pipeline Testing
#### GitHub Actions Workflow
```yaml
# .github/workflows/test.yml
name: Test Suite
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: pgvector/pgvector:pg16
env:
POSTGRES_PASSWORD: test
POSTGRES_DB: jobforge_test
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.12'
- name: Install dependencies
run: |
pip install -r requirements.txt
pip install -r requirements-dev.txt
- name: Run linting
run: |
black --check .
ruff check .
mypy app/
- name: Run tests
run: |
pytest tests/unit/ tests/integration/ --cov=app --cov-report=xml
env:
DATABASE_URL: postgresql://postgres:test@localhost:5432/jobforge_test
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
file: ./coverage.xml
```
### 2. Quality Metrics Dashboard
#### Test Results Tracking
```python
# scripts/generate_test_report.py
import json
import subprocess
from datetime import datetime
def generate_test_report():
"""Generate comprehensive test report."""
# Run tests with JSON output
result = subprocess.run([
'pytest', 'tests/', '--json-report', '--json-report-file=test_report.json'
], capture_output=True, text=True)
# Load test results
with open('test_report.json') as f:
test_data = json.load(f)
# Generate summary
summary = {
'timestamp': datetime.now().isoformat(),
'total_tests': test_data['summary']['total'],
'passed': test_data['summary']['passed'],
'failed': test_data['summary']['failed'],
'skipped': test_data['summary']['skipped'],
'duration': test_data['duration'],
'pass_rate': test_data['summary']['passed'] / test_data['summary']['total'] * 100
}
print(f"Test Summary: {summary['passed']}/{summary['total']} passed ({summary['pass_rate']:.1f}%)")
return summary
if __name__ == "__main__":
generate_test_report()
```
This comprehensive QA procedure ensures that Job Forge maintains high quality through systematic testing, monitoring, and validation processes.

700
docs/testing_strategy.md
View File

@@ -1,700 +0,0 @@
# JobForge MVP - Testing Strategy & Guidelines
**Version:** 1.0.0 MVP
**Target Audience:** Development Team
**Testing Framework:** pytest + manual testing
**Last Updated:** July 2025
---
## 🎯 Testing Philosophy
### MVP Testing Approach
- **Pragmatic over Perfect:** Focus on critical path testing rather than 100% coverage
- **Backend Heavy:** Comprehensive API testing, lighter frontend testing for MVP
- **Manual Integration:** Manual testing of full user workflows
- **AI Mocking:** Mock external AI services for reliable testing
- **Database Testing:** Test data isolation and security policies
### Testing Pyramid for MVP
```
┌─────────────────┐
│ Manual E2E │ ← Full user workflows
│ Testing │
├─────────────────┤
│ Integration │ ← API endpoints + database
│ Tests │
├─────────────────┤
│ Unit Tests │ ← Business logic + utilities
│ │
└─────────────────┘
```
---
## 🧪 Unit Testing (Backend)
### Test Structure
```
tests/
├── unit/
│ ├── services/
│ │ ├── test_auth_service.py
│ │ ├── test_application_service.py
│ │ └── test_document_service.py
│ ├── agents/
│ │ ├── test_research_agent.py
│ │ ├── test_resume_optimizer.py
│ │ └── test_cover_letter_generator.py
│ └── helpers/
│ ├── test_validators.py
│ └── test_formatters.py
├── integration/
│ ├── test_api_auth.py
│ ├── test_api_applications.py
│ ├── test_api_documents.py
│ └── test_database_policies.py
├── fixtures/
│ ├── test_data.py
│ └── mock_responses.py
├── conftest.py
└── pytest.ini
```
### Sample Unit Tests
#### Authentication Service Test
```python
# tests/unit/services/test_auth_service.py
import pytest
from unittest.mock import AsyncMock, patch
from src.backend.services.auth_service import AuthenticationService
from src.backend.models.requests import RegisterRequest
class TestAuthenticationService:
@pytest.fixture
def auth_service(self, mock_db):
return AuthenticationService(mock_db)
@pytest.mark.asyncio
async def test_register_user_success(self, auth_service):
# Arrange
register_data = RegisterRequest(
email="test@example.com",
password="SecurePass123!",
full_name="Test User"
)
# Act
user = await auth_service.register_user(register_data)
# Assert
assert user.email == "test@example.com"
assert user.full_name == "Test User"
assert user.id is not None
# Password should be hashed
assert user.password_hash != "SecurePass123!"
assert user.password_hash.startswith("$2b$")
@pytest.mark.asyncio
async def test_register_user_duplicate_email(self, auth_service, existing_user):
# Arrange
register_data = RegisterRequest(
email=existing_user.email, # Same email as existing user
password="SecurePass123!",
full_name="Another User"
)
# Act & Assert
with pytest.raises(DuplicateEmailError):
await auth_service.register_user(register_data)
@pytest.mark.asyncio
async def test_authenticate_user_success(self, auth_service, existing_user):
# Act
auth_result = await auth_service.authenticate_user(
existing_user.email,
"correct_password"
)
# Assert
assert auth_result.success is True
assert auth_result.user.id == existing_user.id
assert auth_result.access_token is not None
assert auth_result.token_type == "bearer"
@pytest.mark.asyncio
async def test_authenticate_user_wrong_password(self, auth_service, existing_user):
# Act
auth_result = await auth_service.authenticate_user(
existing_user.email,
"wrong_password"
)
# Assert
assert auth_result.success is False
assert auth_result.user is None
assert auth_result.access_token is None
```
#### AI Agent Test with Mocking
```python
# tests/unit/agents/test_research_agent.py
import pytest
from unittest.mock import AsyncMock, patch
from src.agents.research_agent import ResearchAgent
class TestResearchAgent:
@pytest.fixture
def research_agent(self, mock_claude_client):
return ResearchAgent(mock_claude_client)
@pytest.mark.asyncio
@patch('src.agents.research_agent.web_search')
async def test_analyze_job_description(self, mock_web_search, research_agent):
# Arrange
job_description = """
We are seeking a Senior Python Developer with 5+ years experience.
Must have Django, PostgreSQL, and AWS experience.
"""
mock_claude_response = {
"content": [{
"text": """
{
"required_skills": ["Python", "Django", "PostgreSQL", "AWS"],
"experience_level": "Senior (5+ years)",
"key_requirements": ["Backend development", "Database design"],
"nice_to_have": ["Docker", "Kubernetes"]
}
"""
}]
}
research_agent.claude_client.messages.create.return_value = mock_claude_response
# Act
analysis = await research_agent.analyze_job_description(job_description)
# Assert
assert "Python" in analysis.required_skills
assert "Django" in analysis.required_skills
assert analysis.experience_level == "Senior (5+ years)"
assert len(analysis.key_requirements) > 0
@pytest.mark.asyncio
async def test_research_company_info(self, research_agent):
# Test company research with mocked web search
company_name = "Google"
# Mock web search results
with patch('src.agents.research_agent.web_search') as mock_search:
mock_search.return_value = {
"results": [
{
"title": "Google - About",
"content": "Google is a multinational technology company...",
"url": "https://about.google.com"
}
]
}
company_info = await research_agent.research_company_info(company_name)
assert company_info.company_name == "Google"
assert len(company_info.recent_news) >= 0
assert company_info.company_description is not None
```
---
## 🔗 Integration Testing
### API Integration Tests
```python
# tests/integration/test_api_applications.py
import pytest
from httpx import AsyncClient
from src.backend.main import app
class TestApplicationsAPI:
@pytest.mark.asyncio
async def test_create_application_success(self, auth_headers):
async with AsyncClient(app=app, base_url="http://test") as client:
# Arrange
application_data = {
"company_name": "Google",
"role_title": "Senior Developer",
"job_description": "We are seeking an experienced developer with Python skills...",
"location": "Toronto, ON",
"priority_level": "high"
}
# Act
response = await client.post(
"/api/v1/applications",
json=application_data,
headers=auth_headers
)
# Assert
assert response.status_code == 201
data = response.json()
assert data["company_name"] == "Google"
assert data["role_title"] == "Senior Developer"
assert data["status"] == "draft"
assert data["name"] == "google_senior_developer_2025_07_01" # Auto-generated
@pytest.mark.asyncio
async def test_create_application_validation_error(self, auth_headers):
async with AsyncClient(app=app, base_url="http://test") as client:
# Arrange - missing required fields
application_data = {
"company_name": "", # Empty company name
"job_description": "Short" # Too short (min 50 chars)
}
# Act
response = await client.post(
"/api/v1/applications",
json=application_data,
headers=auth_headers
)
# Assert
assert response.status_code == 400
error = response.json()
assert "company_name" in error["error"]["details"]
assert "job_description" in error["error"]["details"]
@pytest.mark.asyncio
async def test_list_applications_user_isolation(self, auth_headers, other_user_auth_headers):
async with AsyncClient(app=app, base_url="http://test") as client:
# Create application as user 1
await client.post(
"/api/v1/applications",
json={
"company_name": "User1 Company",
"role_title": "Developer",
"job_description": "Job description for user 1 application..."
},
headers=auth_headers
)
# List applications as user 2
response = await client.get(
"/api/v1/applications",
headers=other_user_auth_headers
)
# Assert user 2 cannot see user 1's applications
assert response.status_code == 200
data = response.json()
assert len(data["applications"]) == 0 # Should be empty for user 2
```
### Database Policy Tests
```python
# tests/integration/test_database_policies.py
import pytest
from src.backend.database.connection import get_db_connection
class TestDatabasePolicies:
@pytest.mark.asyncio
async def test_rls_user_isolation(self, test_user_1, test_user_2):
async with get_db_connection() as conn:
# Set context as user 1
await conn.execute(
"SET LOCAL app.current_user_id = %s",
str(test_user_1.id)
)
# Create application as user 1
result = await conn.execute("""
INSERT INTO applications (user_id, name, company_name, role_title, job_description)
VALUES (%s, 'test_app', 'Test Co', 'Developer', 'Test job description...')
RETURNING id
""", str(test_user_1.id))
app_id = result.fetchone()[0]
# Switch context to user 2
await conn.execute(
"SET LOCAL app.current_user_id = %s",
str(test_user_2.id)
)
# Try to access user 1's application as user 2
result = await conn.execute(
"SELECT * FROM applications WHERE id = %s",
str(app_id)
)
# Assert user 2 cannot see user 1's application
assert len(result.fetchall()) == 0
@pytest.mark.asyncio
async def test_document_cascade_delete(self, test_user, test_application):
async with get_db_connection() as conn:
# Set user context
await conn.execute(
"SET LOCAL app.current_user_id = %s",
str(test_user.id)
)
# Create document
await conn.execute("""
INSERT INTO documents (application_id, document_type, content)
VALUES (%s, 'research_report', 'Test research content')
""", str(test_application.id))
# Delete application
await conn.execute(
"DELETE FROM applications WHERE id = %s",
str(test_application.id)
)
# Verify documents were cascaded deleted
result = await conn.execute(
"SELECT COUNT(*) FROM documents WHERE application_id = %s",
str(test_application.id)
)
assert result.fetchone()[0] == 0
```
---
## 🎭 Test Fixtures & Mocking
### Pytest Configuration
```python
# conftest.py
import pytest
import asyncio
from unittest.mock import AsyncMock
from src.backend.database.connection import get_db_connection
from src.backend.models.requests import RegisterRequest
@pytest.fixture(scope="session")
def event_loop():
"""Create an instance of the default event loop for the test session."""
loop = asyncio.get_event_loop_policy().new_event_loop()
yield loop
loop.close()
@pytest.fixture
async def test_db():
"""Provide test database connection with cleanup."""
async with get_db_connection() as conn:
# Start transaction
trans = await conn.begin()
yield conn
# Rollback transaction (cleanup)
await trans.rollback()
@pytest.fixture
async def test_user(test_db):
"""Create test user."""
user_data = {
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "test@example.com",
"password_hash": "$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8",
"full_name": "Test User"
}
await test_db.execute("""
INSERT INTO users (id, email, password_hash, full_name)
VALUES (%(id)s, %(email)s, %(password_hash)s, %(full_name)s)
""", user_data)
return User(**user_data)
@pytest.fixture
def auth_headers(test_user):
"""Generate authentication headers for test user."""
token = generate_jwt_token(test_user.id)
return {"Authorization": f"Bearer {token}"}
@pytest.fixture
def mock_claude_client():
"""Mock Claude API client."""
mock = AsyncMock()
mock.messages.create.return_value = {
"content": [{
"text": "Mocked Claude response"
}]
}
return mock
@pytest.fixture
def mock_openai_client():
"""Mock OpenAI API client."""
mock = AsyncMock()
mock.embeddings.create.return_value = {
"data": [{
"embedding": [0.1] * 1536 # Mock 1536-dimensional embedding
}]
}
return mock
```
### Test Data Factory
```python
# tests/fixtures/test_data.py
from datetime import datetime
import uuid
class TestDataFactory:
"""Factory for creating test data objects."""
@staticmethod
def create_user_data(**overrides):
defaults = {
"id": str(uuid.uuid4()),
"email": "user@example.com",
"password_hash": "$2b$12$test_hash",
"full_name": "Test User",
"created_at": datetime.now(),
"updated_at": datetime.now()
}
return {**defaults, **overrides}
@staticmethod
def create_application_data(user_id, **overrides):
defaults = {
"id": str(uuid.uuid4()),
"user_id": user_id,
"name": "test_company_developer_2025_07_01",
"company_name": "Test Company",
"role_title": "Software Developer",
"job_description": "We are seeking a software developer with Python experience...",
"location": "Toronto, ON",
"priority_level": "medium",
"status": "draft",
"research_completed": False,
"resume_optimized": False,
"cover_letter_generated": False,
"created_at": datetime.now(),
"updated_at": datetime.now()
}
return {**defaults, **overrides}
@staticmethod
def create_document_data(application_id, **overrides):
defaults = {
"id": str(uuid.uuid4()),
"application_id": application_id,
"document_type": "research_report",
"content": "# Test Research Report\n\nThis is test content...",
"created_at": datetime.now(),
"updated_at": datetime.now()
}
return {**defaults, **overrides}
```
---
## 🎯 Manual Testing Guidelines
### Critical User Workflows
#### Workflow 1: Complete Application Creation
**Goal:** Test full 3-phase workflow from start to finish
**Steps:**
1. **Registration & Login**
- [ ] Register new account with valid email/password
- [ ] Login with created credentials
- [ ] Verify JWT token is received and stored
2. **Application Creation**
- [ ] Create new application with job description
- [ ] Verify application appears in sidebar
- [ ] Check application status is "draft"
3. **Research Phase**
- [ ] Click "Research" tab
- [ ] Verify research processing starts automatically
- [ ] Wait for completion (check processing status)
- [ ] Review generated research report
- [ ] Verify application status updates to "research_complete"
4. **Resume Optimization**
- [ ] Upload at least one resume to library
- [ ] Click "Resume" tab
- [ ] Start resume optimization
- [ ] Verify processing completes successfully
- [ ] Review optimized resume content
- [ ] Test editing resume content
- [ ] Verify application status updates to "resume_ready"
5. **Cover Letter Generation**
- [ ] Click "Cover Letter" tab
- [ ] Add additional context in text box
- [ ] Generate cover letter
- [ ] Review generated content
- [ ] Test editing cover letter
- [ ] Verify application status updates to "cover_letter_ready"
**Expected Results:**
- All phases complete without errors
- Documents are editable and changes persist
- Status updates correctly through workflow
- Navigation works smoothly between phases
#### Workflow 2: Data Isolation Testing
**Goal:** Verify users cannot access each other's data
**Steps:**
1. **Create two test accounts**
- Account A: user1@test.com
- Account B: user2@test.com
2. **Create applications in both accounts**
- Login as User A, create "Google Developer" application
- Login as User B, create "Microsoft Engineer" application
3. **Verify isolation**
- [ ] User A cannot see User B's applications in sidebar
- [ ] User A cannot access User B's application URLs directly
- [ ] Document URLs return 404 for wrong user
#### Workflow 3: Error Handling
**Goal:** Test system behavior with invalid inputs and failures
**Steps:**
1. **Invalid Application Data**
- [ ] Submit empty company name (should show validation error)
- [ ] Submit job description under 50 characters (should fail)
- [ ] Submit invalid URL format (should fail or ignore)
2. **Network/API Failures**
- [ ] Temporarily block Claude API access (mock network failure)
- [ ] Verify user gets meaningful error message
- [ ] Verify system doesn't crash or corrupt data
3. **Authentication Failures**
- [ ] Try accessing API without token (should get 401)
- [ ] Try with expired token (should redirect to login)
- [ ] Try with malformed token (should get error)
---
## 📊 Test Coverage Goals
### MVP Coverage Targets
- **Backend Services:** 80%+ line coverage
- **API Endpoints:** 100% endpoint coverage (at least smoke tests)
- **Database Models:** 90%+ coverage of business logic
- **Critical Paths:** 100% coverage of main user workflows
- **Error Handling:** 70%+ coverage of error scenarios
### Coverage Exclusions (MVP)
- Frontend components (manual testing only)
- External API integrations (mocked)
- Database migration scripts
- Development utilities
- Logging and monitoring code
---
## 🚀 Testing Commands
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage report
pytest --cov=src --cov-report=html
# Run specific test file
pytest tests/unit/services/test_auth_service.py
# Run tests with specific marker
pytest -m "not slow"
# Run integration tests only
pytest tests/integration/
# Verbose output for debugging
pytest -v -s tests/unit/services/test_auth_service.py::TestAuthenticationService::test_register_user_success
```
### Test Database Setup
```bash
# Reset test database
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp_test -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
# Run database init for tests
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp_test -f /docker-entrypoint-initdb.d/init.sql
```
---
## 🐛 Testing Best Practices
### DO's
- ✅ **Test business logic thoroughly** - Focus on services and agents
- ✅ **Mock external dependencies** - Claude API, OpenAI, web scraping
- ✅ **Test user data isolation** - Critical for multi-tenant security
- ✅ **Use descriptive test names** - Should explain what is being tested
- ✅ **Test error conditions** - Not just happy paths
- ✅ **Clean up test data** - Use fixtures and database transactions
### DON'Ts
- ❌ **Don't test external APIs directly** - Too unreliable for CI/CD
- ❌ **Don't ignore database constraints** - Test them explicitly
- ❌ **Don't hardcode test data** - Use factories and fixtures
- ❌ **Don't skip cleanup** - Polluted test data affects other tests
- ❌ **Don't test implementation details** - Test behavior, not internals
### Test Organization
```python
# Good test structure
class TestApplicationService:
"""Test class for ApplicationService business logic."""
def test_create_application_with_valid_data_returns_application(self):
"""Should create and return application when given valid data."""
# Arrange
# Act
# Assert
def test_create_application_with_duplicate_name_raises_error(self):
"""Should raise DuplicateNameError when application name already exists."""
# Arrange
# Act
# Assert
```
---
## 📈 Testing Metrics
### Key Testing Metrics
- **Test Execution Time:** Target < 30 seconds for full suite
- **Test Reliability:** 95%+ pass rate on repeated runs
- **Code Coverage:** 80%+ overall, 90%+ for critical paths
- **Bug Detection:** Tests should catch regressions before deployment
### Performance Testing (Basic)
```python
# Basic performance test example
@pytest.mark.asyncio
async def test_application_creation_performance():
"""Application creation should complete within 2 seconds."""
start_time = time.time()
# Create application
result = await application_service.create_application(test_data)
execution_time = time.time() - start_time
assert execution_time < 2.0, f"Application creation took {execution_time:.2f}s"
```
---
*This testing strategy provides comprehensive coverage for the MVP while remaining practical and maintainable. Focus on backend testing for Phase 1, with more sophisticated frontend testing to be added in Phase 2.*