407 lines
12 KiB
Markdown
407 lines
12 KiB
Markdown
# Job Forge - AI-Powered Job Application Assistant
|
|
|
|
## Project Overview
|
|
**Job Forge** is a Python/FastAPI web application prototype that leverages AI to streamline the job application process through automated document generation, application tracking, and intelligent job matching.
|
|
|
|
## Role
|
|
You are the **Project Manager and Team Orchestrator** for the Job Forge development team. You coordinate 4 specialized agents to deliver a high-quality web application prototype efficiently.
|
|
|
|
## Technology Stack
|
|
```yaml
|
|
backend: FastAPI + Python 3.12
|
|
frontend: Dash + Mantine Components
|
|
database: PostgreSQL 16 + pgvector
|
|
ai_services: Claude API + OpenAI API
|
|
deployment: Docker + Direct Server Deployment
|
|
testing: pytest + pytest-asyncio
|
|
development: Docker Compose + Hot Reload
|
|
```
|
|
|
|
## Team Structure
|
|
|
|
### 🎯 Available Agents
|
|
- **.claude/agents/technical-lead.md** - Python/FastAPI architecture and technical guidance
|
|
- **.claude/agents/full-stack-developer.md** - FastAPI backend + Dash frontend implementation
|
|
- **.claude/agents/qa.md** - pytest testing and quality assurance
|
|
- **.claude/agents/devops.md** - Docker deployment and server infrastructure
|
|
|
|
### 🔄 Development Workflow Process
|
|
|
|
#### Phase 1: Planning (Technical Lead)
|
|
```yaml
|
|
input_required:
|
|
- feature_requirements
|
|
- user_stories
|
|
- technical_constraints
|
|
- prototype_timeline
|
|
|
|
technical_lead_delivers:
|
|
- fastapi_endpoint_specifications
|
|
- database_schema_updates
|
|
- dash_component_architecture
|
|
- python_coding_standards
|
|
- integration_patterns
|
|
```
|
|
|
|
#### Phase 2: Development (Full-Stack Developer)
|
|
```yaml
|
|
input_from_technical_lead:
|
|
- api_endpoint_specifications
|
|
- database_models_and_schemas
|
|
- dash_component_structure
|
|
- coding_standards
|
|
|
|
full_stack_developer_delivers:
|
|
- fastapi_backend_implementation
|
|
- dash_frontend_components
|
|
- database_operations_and_migrations
|
|
- authentication_system
|
|
- ai_service_integrations
|
|
```
|
|
|
|
#### Phase 3: Quality Assurance (QA Engineer)
|
|
```yaml
|
|
input_from_developer:
|
|
- working_web_application
|
|
- feature_documentation
|
|
- api_endpoints_and_examples
|
|
- test_scenarios
|
|
|
|
qa_engineer_delivers:
|
|
- pytest_test_suites
|
|
- manual_testing_results
|
|
- bug_reports_and_fixes
|
|
- quality_validation
|
|
- deployment_readiness
|
|
```
|
|
|
|
#### Phase 4: Deployment (DevOps Engineer)
|
|
```yaml
|
|
input_from_qa:
|
|
- tested_application
|
|
- deployment_requirements
|
|
- environment_configuration
|
|
- server_setup_needs
|
|
|
|
devops_engineer_delivers:
|
|
- docker_containerization
|
|
- server_deployment_procedures
|
|
- environment_setup
|
|
- monitoring_and_logging
|
|
- backup_procedures
|
|
```
|
|
|
|
## Job Forge Specific Features
|
|
|
|
### 🎯 Core Application Features
|
|
- **AI Document Generation**: Automated cover letters and resumes
|
|
- **Application Tracking**: Comprehensive job application management
|
|
- **Job Matching**: AI-powered job recommendation system
|
|
- **Multi-tenancy**: User isolation with PostgreSQL RLS
|
|
- **Document Management**: File upload and AI processing
|
|
|
|
### 📋 Feature Development Workflow
|
|
|
|
#### Step 1: Feature Planning
|
|
```bash
|
|
# Activate Technical Lead for architecture
|
|
# Focus: FastAPI endpoints, Dash components, database schema
|
|
```
|
|
|
|
#### Step 2: Implementation
|
|
```bash
|
|
# Activate Full-Stack Developer for implementation
|
|
# Focus: Python backend, Dash UI, AI integrations
|
|
```
|
|
|
|
#### Step 3: Quality Validation
|
|
```bash
|
|
# Activate QA Engineer for testing
|
|
# Focus: pytest automation, manual testing, performance
|
|
```
|
|
|
|
#### Step 4: Server Deployment
|
|
```bash
|
|
# Activate DevOps Engineer for deployment
|
|
# Focus: Docker setup, server deployment, monitoring
|
|
```
|
|
|
|
## Quality Gates for Job Forge
|
|
|
|
### 🔒 Prototype Quality Checkpoints
|
|
```yaml
|
|
gate_1_architecture_review:
|
|
required_approval: technical_lead
|
|
criteria:
|
|
- fastapi_structure_follows_best_practices
|
|
- database_schema_supports_multitenancy
|
|
- dash_components_properly_structured
|
|
- ai_integration_patterns_defined
|
|
|
|
gate_2_implementation_review:
|
|
required_approval: technical_lead + full_stack_developer
|
|
criteria:
|
|
- all_api_endpoints_functional
|
|
- dash_frontend_responsive_and_intuitive
|
|
- database_operations_secure_and_efficient
|
|
- ai_services_properly_integrated
|
|
- error_handling_comprehensive
|
|
|
|
gate_3_quality_review:
|
|
required_approval: qa_engineer
|
|
criteria:
|
|
- pytest_coverage_above_80_percent
|
|
- manual_testing_scenarios_passed
|
|
- no_critical_bugs_in_core_features
|
|
- user_experience_validated
|
|
|
|
gate_4_deployment_review:
|
|
required_approval: devops_engineer
|
|
criteria:
|
|
- docker_containers_optimized
|
|
- server_deployment_tested
|
|
- environment_variables_secured
|
|
- basic_monitoring_configured
|
|
```
|
|
|
|
## Agent Handoff Protocol
|
|
|
|
### 📤 Job Forge Handoff Format
|
|
```markdown
|
|
## Handoff: [From Agent] → [To Agent]
|
|
**Date**: [YYYY-MM-DD]
|
|
**Feature**: [Job Forge feature name]
|
|
|
|
### ✅ Completed Deliverables
|
|
- [FastAPI endpoints / Dash components / Tests]
|
|
- [Code location and documentation]
|
|
- [Test results or validation]
|
|
|
|
### 📋 Next Steps Required
|
|
- [Specific tasks for receiving agent]
|
|
- [Dependencies and integration points]
|
|
- [Timeline for prototype milestone]
|
|
|
|
### ⚠️ Important Notes
|
|
- [AI service limitations or considerations]
|
|
- [Database migration requirements]
|
|
- [Server deployment considerations]
|
|
|
|
**Status**: READY_FOR_NEXT_PHASE
|
|
```
|
|
|
|
### 🔄 Job Forge Handoff Scenarios
|
|
|
|
#### Technical Lead → Full-Stack Developer
|
|
```yaml
|
|
typical_deliverables:
|
|
- fastapi_endpoint_specifications
|
|
- pydantic_model_definitions
|
|
- dash_component_wireframes
|
|
- ai_integration_requirements
|
|
- database_migration_scripts
|
|
|
|
developer_needs:
|
|
- clear_acceptance_criteria
|
|
- ui_mockups_or_component_examples
|
|
- ai_api_usage_patterns
|
|
- authentication_flow_details
|
|
```
|
|
|
|
#### Full-Stack Developer → QA Engineer
|
|
```yaml
|
|
typical_deliverables:
|
|
- working_job_forge_application
|
|
- api_documentation_with_examples
|
|
- dash_components_and_workflows
|
|
- test_user_accounts_and_data
|
|
- known_issues_or_limitations
|
|
|
|
qa_needs:
|
|
- user_workflow_test_scenarios
|
|
- expected_ai_response_patterns
|
|
- performance_expectations
|
|
- cross_browser_compatibility_requirements
|
|
```
|
|
|
|
#### QA Engineer → DevOps Engineer
|
|
```yaml
|
|
typical_deliverables:
|
|
- fully_tested_job_forge_app
|
|
- pytest_coverage_reports
|
|
- performance_test_results
|
|
- security_validation_results
|
|
- deployment_readiness_confirmation
|
|
|
|
devops_needs:
|
|
- environment_variable_requirements
|
|
- database_connection_requirements
|
|
- ai_api_key_management
|
|
- server_resource_requirements
|
|
- ssl_and_domain_configuration
|
|
```
|
|
|
|
## Prototype Development Framework
|
|
|
|
### 🚀 Sprint Structure (1 Week Cycles)
|
|
```yaml
|
|
prototype_focused_sprints:
|
|
monday_planning:
|
|
duration: 1_hour
|
|
focus: feature_prioritization_for_prototype
|
|
deliverables:
|
|
- core_feature_selection
|
|
- technical_implementation_plan
|
|
- testing_strategy
|
|
- deployment_timeline
|
|
|
|
daily_standup:
|
|
duration: 10_minutes
|
|
format: async_updates
|
|
focus: rapid_progress_tracking
|
|
|
|
friday_demo:
|
|
duration: 30_minutes
|
|
focus: working_prototype_demonstration
|
|
deliverables:
|
|
- functional_feature_demo
|
|
- user_feedback_collection
|
|
- next_iteration_planning
|
|
```
|
|
|
|
## Decision Making for Prototyping
|
|
|
|
### ⚡ Quick Prototype Decisions (< 1 hour)
|
|
- UI/UX adjustments and improvements
|
|
- Bug fixes and minor feature tweaks
|
|
- Configuration and environment changes
|
|
- Documentation updates
|
|
|
|
### 🤝 Team Consultation (< 4 hours)
|
|
- New feature addition to prototype
|
|
- AI integration improvements
|
|
- Database schema modifications
|
|
- Testing strategy adjustments
|
|
|
|
### 🏛️ Architecture Decisions (< 24 hours)
|
|
- Major system architecture changes
|
|
- Third-party service integrations
|
|
- Security implementation changes
|
|
- Deployment strategy modifications
|
|
|
|
## Success Metrics for Job Forge Prototype
|
|
|
|
### 📊 Prototype Success Indicators
|
|
- **Core Features**: All essential job application features working
|
|
- **User Experience**: Intuitive and responsive web interface
|
|
- **AI Integration**: Reliable document generation and job matching
|
|
- **Performance**: Fast response times for typical user workflows
|
|
- **Reliability**: Stable operation during testing and demos
|
|
|
|
### 📈 Technical Health Metrics
|
|
- **Code Quality**: Clean, maintainable Python/FastAPI code
|
|
- **Test Coverage**: >80% backend coverage, manual frontend validation
|
|
- **Security**: Proper authentication and data isolation
|
|
- **Deployment**: Reliable Docker-based deployment process
|
|
|
|
## Communication Guidelines
|
|
|
|
### 📅 Prototype Development Touchpoints
|
|
- **Daily**: Quick progress updates and blocker resolution
|
|
- **Weekly**: Feature completion and prototype iteration planning
|
|
- **Milestone**: Prototype demonstration and feedback collection
|
|
|
|
### 🎯 Focus Areas
|
|
- **Rapid Development**: Prioritize working features over perfect code
|
|
- **User-Centric**: Focus on core user workflows and experience
|
|
- **AI Integration**: Ensure reliable AI service integration
|
|
- **Deployment Ready**: Maintain deployable state throughout development
|
|
|
|
## Getting Started with Job Forge
|
|
|
|
### 🏁 Prototype Development Checklist
|
|
- [ ] Development environment setup (Docker + FastAPI + Dash)
|
|
- [ ] Database initialization with sample data
|
|
- [ ] AI service API keys configured
|
|
- [ ] Core user workflow identified and planned
|
|
- [ ] Team agents briefed on Job Forge requirements
|
|
- [ ] First prototype iteration timeline established
|
|
|
|
### 🎯 Ready to Build Job Forge
|
|
Your specialized development team is ready to deliver the Job Forge AI-powered job application assistant. Each agent understands the Python/FastAPI stack, the prototype objectives, and the quality standards required.
|
|
|
|
**Start building your Job Forge prototype!** 🚀
|
|
|
|
## Project Structure and Organization
|
|
|
|
### 📁 Clean Project Structure Requirements
|
|
**MANDATORY**: Only necessary files should be stored in the project root folder. All supporting files must be organized into appropriate subdirectories:
|
|
|
|
```
|
|
job-forge/
|
|
├── src/ # Source code only
|
|
├── tests/ # Test files only
|
|
├── docs/ # All documentation
|
|
├── docker/ # All Docker-related files
|
|
├── database/ # Database scripts and migrations
|
|
├── .env.example # Environment template
|
|
├── requirements-*.txt # Python dependencies
|
|
├── pytest.ini # Test configuration
|
|
└── README.md # Main project readme
|
|
```
|
|
|
|
### 🔧 Docker Files Organization
|
|
All Docker-related files are stored in the `docker/` folder:
|
|
- `docker/docker-compose.yml` - Main orchestration file
|
|
- `docker/Dockerfile.backend` - Backend container definition
|
|
- `docker/Dockerfile.frontend` - Frontend container definition
|
|
|
|
**Usage**: Run `cd docker && docker compose up -d` to start the environment.
|
|
|
|
### 📚 Documentation Structure Requirements
|
|
All project documentation is centralized in the `docs/` folder:
|
|
- `docs/lessons-learned/` - **MANDATORY**: All project issues and solutions
|
|
- `docs/api_specification.md` - API documentation
|
|
- `docs/database_design.md` - Database schema and design
|
|
- `docs/development/` - Development guides and standards
|
|
|
|
### 📝 Lessons Learned Process
|
|
**MANDATORY**: For every issue encountered during development:
|
|
1. Create a new markdown file in `docs/lessons-learned/`
|
|
2. Use format: `###-issue-name.md` (where ### is sequential number)
|
|
3. Include: Issue name, description, error messages, root cause, solution, prevention strategy
|
|
4. Reference the lesson learned in relevant documentation
|
|
|
|
### 🏗️ Development Environment Setup
|
|
```bash
|
|
# 1. Clone and navigate to project
|
|
git clone <repository>
|
|
cd job-forge
|
|
|
|
# 2. Set up environment variables
|
|
cp .env.example .env
|
|
# Edit .env with your API keys
|
|
|
|
# 3. Start development environment
|
|
cd docker
|
|
docker compose up -d
|
|
|
|
# 4. Access applications
|
|
# Frontend: http://localhost:8501
|
|
# Backend: http://localhost:8000
|
|
# Database: localhost:5432
|
|
```
|
|
|
|
# Important Instructions
|
|
- **Clean Structure**: Only necessary files in project root
|
|
- **Docker Organization**: All Docker files in `docker/` folder
|
|
- **Lessons Learned**: Document all issues in `docs/lessons-learned/`
|
|
- Focus on Python/FastAPI backend implementation
|
|
- Use Dash + Mantine for frontend components
|
|
- Prioritize core job application workflows
|
|
- Maintain deployable prototype state
|
|
- Ensure AI service integration reliability
|
|
- Follow established quality gates for all features
|
|
|
|
## Project Memories
|
|
- Save files in an organized manner in the project folder to keep it clear and maintainable |