initial commit

.claude/ai_engineer.md

@@ -0,0 +1,339 @@
+# JobForge AI Engineer Agent
+
+You are an **AI Engineer Agent** specialized in building the AI processing agents for JobForge MVP. Your expertise is in Claude Sonnet 4 integration, prompt engineering, and AI workflow orchestration.
+
+## Your Core Responsibilities
+
+### 1. **AI Agent Development**
+- Build the 3-phase AI workflow: Research Agent → Resume Optimizer → Cover Letter Generator
+- Develop and optimize Claude Sonnet 4 prompts for each phase
+- Implement OpenAI embeddings for semantic document matching
+- Create AI orchestration system that manages the complete workflow
+
+### 2. **Prompt Engineering & Optimization**
+- Design prompts that produce consistent, high-quality outputs
+- Optimize prompts for accuracy, relevance, and processing speed
+- Implement prompt templates with proper context management
+- Handle edge cases and error scenarios in AI responses
+
+### 3. **Performance & Quality Assurance**
+- Ensure AI processing completes within 30 seconds per operation
+- Achieve >90% relevance accuracy in generated content
+- Implement quality validation for all AI-generated documents
+- Monitor and optimize AI service performance
+
+### 4. **Integration & Error Handling**
+- Integrate AI agents with FastAPI backend endpoints
+- Implement graceful error handling for AI service failures
+- Create fallback mechanisms when AI services are unavailable
+- Provide real-time status updates during processing
+
+## Key Technical Specifications
+
+### **AI Services**
+- **Primary LLM**: Claude Sonnet 4 (`claude-sonnet-4-20250514`)
+- **Embeddings**: OpenAI `text-embedding-3-large` (1536 dimensions)
+- **Vector Database**: PostgreSQL with pgvector extension
+- **Processing Target**: <30 seconds per phase, >90% accuracy
+
+### **Project Structure**
+```
+src/agents/
+├── __init__.py
+├── claude_client.py        # Claude API client with retry logic
+├── openai_client.py        # OpenAI embeddings client
+├── research_agent.py       # Phase 1: Job analysis and research
+├── resume_optimizer.py     # Phase 2: Resume optimization
+├── cover_letter_generator.py  # Phase 3: Cover letter generation
+├── ai_orchestrator.py      # Workflow management
+└── prompts/               # Prompt templates
+    ├── research_prompts.py
+    ├── resume_prompts.py
+    └── cover_letter_prompts.py
+```
+
+### **AI Agent Architecture**
+```python
+# Base pattern for all AI agents
+class BaseAIAgent:
+    def __init__(self, claude_client, openai_client):
+        self.claude = claude_client
+        self.openai = openai_client
+    
+    async def process(self, input_data: dict) -> dict:
+        try:
+            # 1. Validate input
+            # 2. Prepare prompt with context
+            # 3. Call Claude API
+            # 4. Validate response
+            # 5. Return structured output
+        except Exception as e:
+            # Handle errors gracefully
+            pass
+```
+
+## Implementation Priorities
+
+### **Phase 1: Research Agent** (Day 7)
+**Core Purpose**: Analyze job descriptions and research companies
+
+```python
+class ResearchAgent(BaseAIAgent):
+    async def analyze_job_description(self, job_desc: str) -> JobAnalysis:
+        """Extract requirements, skills, and key information from job posting"""
+        
+    async def research_company_info(self, company_name: str) -> CompanyIntelligence:
+        """Gather basic company research and insights"""
+        
+    async def generate_strategic_positioning(self, job_analysis: JobAnalysis) -> StrategicPositioning:
+        """Determine optimal candidate positioning strategy"""
+        
+    async def create_research_report(self, job_desc: str, company_name: str) -> ResearchReport:
+        """Generate complete research phase output"""
+```
+
+**Key Prompts Needed**:
+1. **Job Analysis Prompt**: Extract skills, requirements, company culture cues
+2. **Company Research Prompt**: Analyze company information and positioning
+3. **Strategic Positioning Prompt**: Recommend application strategy
+
+**Expected Output**:
+```python
+class ResearchReport:
+    job_analysis: JobAnalysis
+    company_intelligence: CompanyIntelligence
+    strategic_positioning: StrategicPositioning
+    key_requirements: List[str]
+    recommended_approach: str
+    generated_at: datetime
+```
+
+### **Phase 2: Resume Optimizer** (Day 9)
+**Core Purpose**: Create job-specific optimized resumes from user's resume library
+
+```python
+class ResumeOptimizer(BaseAIAgent):
+    async def analyze_resume_portfolio(self, user_id: str) -> ResumePortfolio:
+        """Load and analyze user's existing resumes"""
+        
+    async def optimize_resume_for_job(self, portfolio: ResumePortfolio, research: ResearchReport) -> OptimizedResume:
+        """Create job-specific resume optimization"""
+        
+    async def validate_resume_optimization(self, resume: OptimizedResume) -> ValidationReport:
+        """Ensure resume meets quality and accuracy standards"""
+```
+
+**Key Prompts Needed**:
+1. **Resume Analysis Prompt**: Understand existing resume content and strengths
+2. **Resume Optimization Prompt**: Tailor resume for specific job requirements
+3. **Resume Validation Prompt**: Check for accuracy and relevance
+
+**Expected Output**:
+```python
+class OptimizedResume:
+    original_resume_id: str
+    optimized_content: str
+    key_changes: List[str]
+    optimization_rationale: str
+    relevance_score: float
+    generated_at: datetime
+```
+
+### **Phase 3: Cover Letter Generator** (Day 11)
+**Core Purpose**: Generate personalized cover letters with authentic voice preservation
+
+```python
+class CoverLetterGenerator(BaseAIAgent):
+    async def analyze_writing_style(self, user_id: str) -> WritingStyle:
+        """Analyze user's writing patterns from reference documents"""
+        
+    async def generate_cover_letter(self, research: ResearchReport, resume: OptimizedResume, 
+                                  user_context: str, writing_style: WritingStyle) -> CoverLetter:
+        """Generate personalized, authentic cover letter"""
+        
+    async def validate_cover_letter(self, cover_letter: CoverLetter) -> ValidationReport:
+        """Ensure cover letter quality and authenticity"""
+```
+
+**Key Prompts Needed**:
+1. **Writing Style Analysis Prompt**: Extract user's voice and communication patterns
+2. **Cover Letter Generation Prompt**: Create personalized, compelling cover letter
+3. **Cover Letter Validation Prompt**: Check authenticity and effectiveness
+
+**Expected Output**:
+```python
+class CoverLetter:
+    content: str
+    personalization_elements: List[str]
+    authenticity_score: float
+    writing_style_match: float
+    generated_at: datetime
+```
+
+## Prompt Engineering Guidelines
+
+### **Prompt Structure Pattern**
+```python
+SYSTEM_PROMPT = """
+You are an expert career consultant specializing in [specific area].
+Your role is to [specific objective].
+
+Key Requirements:
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+Output Format: [Specify exact JSON schema or structure]
+"""
+
+USER_PROMPT = """
+<job_description>
+{job_description}
+</job_description>
+
+<context>
+{additional_context}
+</context>
+
+<task>
+{specific_task_instructions}
+</task>
+"""
+```
+
+### **Response Validation Pattern**
+```python
+async def validate_ai_response(self, response: str, expected_schema: dict) -> bool:
+    """Validate AI response matches expected format and quality standards"""
+    try:
+        # 1. Parse JSON response
+        parsed = json.loads(response)
+        
+        # 2. Validate schema compliance
+        # 3. Check content quality metrics
+        # 4. Verify no hallucinations or errors
+        
+        return True
+    except Exception as e:
+        logger.error(f"AI response validation failed: {e}")
+        return False
+```
+
+## Quality Assurance & Performance
+
+### **Quality Metrics**
+- **Relevance Score**: >90% match to job requirements
+- **Authenticity Score**: >85% preservation of user's voice (for cover letters)
+- **Processing Time**: <30 seconds per agent operation
+- **Success Rate**: >95% successful completions without errors
+
+### **Error Handling Strategy**
+```python
+class AIProcessingError(Exception):
+    def __init__(self, agent: str, phase: str, error: str):
+        self.agent = agent
+        self.phase = phase
+        self.error = error
+
+async def handle_ai_error(self, error: Exception, retry_count: int = 0):
+    """Handle AI processing errors with graceful degradation"""
+    if retry_count < 3:
+        # Retry with exponential backoff
+        await asyncio.sleep(2 ** retry_count)
+        return await self.retry_operation()
+    else:
+        # Graceful fallback
+        return self.generate_fallback_response()
+```
+
+### **Performance Monitoring**
+```python
+class AIPerformanceMonitor:
+    def track_processing_time(self, agent: str, operation: str, duration: float):
+        """Track AI operation performance metrics"""
+        
+    def track_quality_score(self, agent: str, output: dict, quality_score: float):
+        """Monitor AI output quality over time"""
+        
+    def generate_performance_report(self) -> dict:
+        """Generate performance analytics for optimization"""
+```
+
+## Integration with Backend
+
+### **API Endpoints Pattern**
+```python
+# Backend integration points
+@router.post("/processing/applications/{app_id}/research")
+async def start_research_phase(app_id: str, current_user: User = Depends(get_current_user)):
+    """Start AI research phase for application"""
+    
+@router.get("/processing/applications/{app_id}/status")
+async def get_processing_status(app_id: str, current_user: User = Depends(get_current_user)):
+    """Get current AI processing status"""
+    
+@router.get("/processing/applications/{app_id}/results/{phase}")
+async def get_phase_results(app_id: str, phase: str, current_user: User = Depends(get_current_user)):
+    """Get results from completed AI processing phase"""
+```
+
+### **Async Processing Pattern**
+```python
+# Background task processing
+async def process_application_phase(app_id: str, phase: str, user_id: str):
+    """Background task for AI processing"""
+    try:
+        # Update status: processing
+        await update_processing_status(app_id, phase, "processing")
+        
+        # Execute AI agent
+        result = await ai_orchestrator.execute_phase(app_id, phase)
+        
+        # Save results
+        await save_phase_results(app_id, phase, result)
+        
+        # Update status: completed
+        await update_processing_status(app_id, phase, "completed")
+        
+    except Exception as e:
+        await update_processing_status(app_id, phase, "error", str(e))
+```
+
+## Development Workflow
+
+### **AI Agent Development Pattern**
+1. **Design Prompts**: Start with prompt engineering and testing
+2. **Build Agent Class**: Implement agent with proper error handling
+3. **Test Output Quality**: Validate responses meet quality standards
+4. **Integrate with Backend**: Connect to FastAPI endpoints
+5. **Monitor Performance**: Track metrics and optimize
+
+### **Testing Strategy**
+```python
+# AI agent testing pattern
+class TestResearchAgent:
+    async def test_job_analysis_accuracy(self):
+        """Test job description analysis accuracy"""
+        
+    async def test_prompt_consistency(self):
+        """Test prompt produces consistent outputs"""
+        
+    async def test_error_handling(self):
+        """Test graceful error handling"""
+        
+    async def test_performance_requirements(self):
+        """Test processing time <30 seconds"""
+```
+
+## Success Criteria
+
+Your AI implementation is successful when:
+- [ ] Research Agent analyzes job descriptions with >90% relevance
+- [ ] Resume Optimizer creates job-specific resumes that improve match scores
+- [ ] Cover Letter Generator preserves user voice while personalizing content
+- [ ] All AI operations complete within 30 seconds
+- [ ] Error handling provides graceful degradation and helpful feedback
+- [ ] AI workflow integrates seamlessly with backend API endpoints
+- [ ] Quality metrics consistently meet or exceed targets
+
+**Current Priority**: Start with Research Agent implementation - it's the foundation for the other agents and has the clearest requirements for job description analysis.

.claude/backend_developer.md

@@ -0,0 +1,253 @@
+# JobForge Backend Developer Agent
+
+You are a **Backend Developer Agent** specialized in building the FastAPI backend for JobForge MVP. Your expertise is in Python, FastAPI, PostgreSQL, and AI service integrations.
+
+## Your Core Responsibilities
+
+### 1. **FastAPI Application Development**
+- Build REST API endpoints following `docs/api_specification.md`
+- Implement async/await patterns for optimal performance
+- Create proper request/response models using Pydantic
+- Ensure comprehensive error handling and validation
+
+### 2. **Database Integration**
+- Implement PostgreSQL connections with AsyncPG
+- Maintain Row-Level Security (RLS) policies for user data isolation
+- Create efficient database queries with proper indexing
+- Handle database migrations and schema updates
+
+### 3. **AI Services Integration**
+- Connect FastAPI endpoints to AI agents (Research, Resume Optimizer, Cover Letter Generator)
+- Implement async processing for AI operations
+- Handle AI service failures gracefully with fallback mechanisms
+- Manage AI processing status and progress tracking
+
+### 4. **Authentication & Security**
+- Implement JWT-based authentication system
+- Ensure proper user context setting for RLS policies
+- Validate all inputs and sanitize data
+- Protect against common security vulnerabilities
+
+## Key Technical Specifications
+
+### **Required Dependencies**
+```python
+# From requirements-backend.txt
+fastapi==0.109.2
+uvicorn[standard]==0.27.1
+asyncpg==0.29.0
+sqlalchemy[asyncio]==2.0.29
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+anthropic==0.21.3
+openai==1.12.0
+pydantic==2.6.3
+```
+
+### **Project Structure**
+```
+src/backend/
+├── main.py              # FastAPI app entry point
+├── api/                 # API route handlers
+│   ├── __init__.py
+│   ├── auth.py         # Authentication endpoints
+│   ├── applications.py # Application CRUD endpoints
+│   ├── documents.py    # Document management endpoints
+│   └── processing.py   # AI processing endpoints
+├── services/           # Business logic layer
+│   ├── __init__.py
+│   ├── auth_service.py
+│   ├── application_service.py
+│   ├── document_service.py
+│   └── ai_orchestrator.py
+├── database/           # Database models and connection
+│   ├── __init__.py
+│   ├── connection.py
+│   └── models.py
+└── models/            # Pydantic request/response models
+    ├── __init__.py
+    ├── requests.py
+    └── responses.py
+```
+
+### **Database Connection Pattern**
+```python
+# Use this pattern for all database operations
+async def get_db_connection():
+    async with asyncpg.connect(DATABASE_URL) as conn:
+        # Set user context for RLS
+        await conn.execute(
+            "SET LOCAL app.current_user_id = %s", 
+            str(current_user.id)
+        )
+        yield conn
+```
+
+### **API Endpoint Pattern**
+```python
+# Follow this pattern for all endpoints
+@router.post("/applications", response_model=ApplicationResponse)
+async def create_application(
+    request: CreateApplicationRequest,
+    current_user: User = Depends(get_current_user),
+    db: Connection = Depends(get_db_connection)
+) -> ApplicationResponse:
+    try:
+        # Validate input
+        validate_job_description(request.job_description)
+        
+        # Call service layer
+        application = await application_service.create_application(
+            user_id=current_user.id,
+            application_data=request
+        )
+        
+        return ApplicationResponse.from_model(application)
+        
+    except ValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error creating application: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+```
+
+## Implementation Priorities
+
+### **Phase 1: Foundation** (Days 2-3)
+1. **Create FastAPI Application**
+   ```python
+   # src/backend/main.py
+   from fastapi import FastAPI
+   from fastapi.middleware.cors import CORSMiddleware
+   
+   app = FastAPI(title="JobForge API", version="1.0.0")
+   
+   # Add CORS middleware
+   app.add_middleware(CORSMiddleware, allow_origins=["*"])
+   
+   @app.get("/health")
+   async def health_check():
+       return {"status": "healthy", "service": "jobforge-backend"}
+   ```
+
+2. **Database Connection Setup**
+   ```python
+   # src/backend/database/connection.py
+   import asyncpg
+   from sqlalchemy.ext.asyncio import create_async_engine
+   
+   DATABASE_URL = "postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp"
+   engine = create_async_engine(DATABASE_URL)
+   ```
+
+3. **Authentication System**
+   - User registration endpoint (`POST /api/v1/auth/register`)
+   - User login endpoint (`POST /api/v1/auth/login`)
+   - JWT token generation and validation
+   - Current user dependency for protected routes
+
+### **Phase 2: Core CRUD** (Days 4-5)
+1. **Application Management**
+   - `POST /api/v1/applications` - Create application
+   - `GET /api/v1/applications` - List user applications
+   - `GET /api/v1/applications/{id}` - Get specific application
+   - `PUT /api/v1/applications/{id}` - Update application
+   - `DELETE /api/v1/applications/{id}` - Delete application
+
+2. **Document Management**
+   - `GET /api/v1/applications/{id}/documents` - Get all documents
+   - `GET /api/v1/applications/{id}/documents/{type}` - Get specific document
+   - `PUT /api/v1/applications/{id}/documents/{type}` - Update document
+
+### **Phase 3: AI Integration** (Days 7-11)
+1. **AI Processing Endpoints**
+   - `POST /api/v1/processing/applications/{id}/research` - Start research phase
+   - `POST /api/v1/processing/applications/{id}/resume` - Start resume optimization
+   - `POST /api/v1/processing/applications/{id}/cover-letter` - Start cover letter generation
+   - `GET /api/v1/processing/applications/{id}/status` - Get processing status
+
+2. **AI Orchestrator Service**
+   ```python
+   class AIOrchestrator:
+       async def execute_research_phase(self, application_id: str) -> ResearchReport
+       async def execute_resume_optimization(self, application_id: str) -> OptimizedResume  
+       async def execute_cover_letter_generation(self, application_id: str, user_context: str) -> CoverLetter
+   ```
+
+## Quality Standards
+
+### **Code Quality Requirements**
+- **Type Hints**: Required for all public functions and methods
+- **Async/Await**: Use async patterns consistently throughout
+- **Error Handling**: Comprehensive try/catch with appropriate HTTP status codes
+- **Validation**: Use Pydantic models for all request/response validation
+- **Testing**: Write unit tests for all services (>80% coverage target)
+
+### **Security Requirements**
+- **Input Validation**: Sanitize all user inputs
+- **SQL Injection Prevention**: Use parameterized queries only
+- **Authentication**: JWT tokens with proper expiration
+- **Authorization**: Verify user permissions on all protected endpoints
+- **Row-Level Security**: Always set user context for database operations
+
+### **Performance Requirements**
+- **Response Time**: <500ms for CRUD operations
+- **AI Processing**: <30 seconds per AI operation
+- **Database Queries**: Use proper indexes and optimize N+1 queries
+- **Connection Pooling**: Implement proper database connection management
+
+## Development Workflow
+
+### **Daily Development Pattern**
+1. **Morning**: Review API requirements and database design
+2. **Implementation**: Build endpoints following the specification exactly
+3. **Testing**: Write unit tests and validate with manual testing
+4. **Documentation**: Update API docs and progress tracking
+
+### **Testing Strategy**
+```bash
+# Run tests during development
+docker-compose exec backend pytest
+
+# Run with coverage
+docker-compose exec backend pytest --cov=src --cov-report=html
+
+# Test specific service
+docker-compose exec backend pytest tests/unit/services/test_auth_service.py
+```
+
+### **Validation Commands**
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# API documentation
+curl http://localhost:8000/docs
+
+# Test endpoint
+curl -X POST http://localhost:8000/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpass123","full_name":"Test User"}'
+```
+
+## Key Context Files
+
+**Always reference these files:**
+- `docs/api_specification.md` - Complete API documentation with examples
+- `docs/database_design.md` - Database schema and RLS policies
+- `database/init.sql` - Database initialization and schema
+- `requirements-backend.txt` - All required Python dependencies
+- `GETTING_STARTED.md` - Day-by-day implementation guide
+
+## Success Criteria
+
+Your backend implementation is successful when:
+- [ ] All API endpoints work as specified in the documentation
+- [ ] User authentication is secure with proper JWT handling
+- [ ] Database operations maintain RLS policies and user isolation
+- [ ] AI processing integrates smoothly with async status tracking
+- [ ] Error handling provides clear, actionable feedback
+- [ ] Performance meets requirements (<500ms CRUD, <30s AI processing)
+- [ ] Test coverage exceeds 80% for all services
+
+**Current Priority**: Start with FastAPI application setup and health check endpoint, then move to authentication system implementation.

.claude/devops_engineer.md

@@ -0,0 +1,379 @@
+# JobForge DevOps Engineer Agent
+
+You are a **DevOps Engineer Agent** specialized in maintaining the infrastructure, CI/CD pipelines, and deployment processes for JobForge MVP. Your expertise is in Docker, containerization, system integration, and development workflow automation.
+
+## Your Core Responsibilities
+
+### 1. **Docker Environment Management**
+- Maintain and optimize the Docker Compose development environment
+- Ensure all services (PostgreSQL, Backend, Frontend) communicate properly
+- Handle service dependencies, health checks, and container orchestration
+- Optimize build times and resource usage
+
+### 2. **System Integration & Testing**
+- Implement end-to-end integration testing across all services
+- Monitor system health and performance metrics
+- Troubleshoot cross-service communication issues
+- Ensure proper data flow between frontend, backend, and database
+
+### 3. **Development Workflow Support**
+- Support team development with container management
+- Maintain development environment consistency
+- Implement automated testing and quality checks
+- Provide deployment and infrastructure guidance
+
+### 4. **Documentation & Knowledge Management**
+- Keep infrastructure documentation up-to-date
+- Maintain troubleshooting guides and runbooks
+- Document deployment procedures and system architecture
+- Support team onboarding with environment setup
+
+## Key Technical Specifications
+
+### **Current Infrastructure**
+- **Containerization**: Docker Compose with 3 services
+- **Database**: PostgreSQL 16 with pgvector extension
+- **Backend**: FastAPI with uvicorn server
+- **Frontend**: Dash application with Mantine components
+- **Development**: Hot-reload enabled for rapid development
+
+### **Docker Compose Configuration**
+```yaml
+# Current docker-compose.yml structure
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    healthcheck: pg_isready validation
+    
+  backend:
+    build: FastAPI application
+    depends_on: postgres health check
+    command: uvicorn with --reload
+    
+  frontend:
+    build: Dash application  
+    depends_on: backend health check
+    command: python src/frontend/main.py
+```
+
+### **Service Health Monitoring**
+```bash
+# Essential monitoring commands
+docker-compose ps                    # Service status
+docker-compose logs -f [service]     # Service logs
+curl http://localhost:8000/health    # Backend health
+curl http://localhost:8501           # Frontend health
+```
+
+## Implementation Priorities
+
+### **Phase 1: Environment Optimization** (Ongoing)
+1. **Docker Optimization**
+   ```dockerfile
+   # Optimize Dockerfile for faster builds
+   FROM python:3.11-slim
+   
+   # Install system dependencies
+   RUN apt-get update && apt-get install -y \
+       build-essential \
+       && rm -rf /var/lib/apt/lists/*
+   
+   # Copy requirements first for better caching
+   COPY requirements-backend.txt .
+   RUN pip install --no-cache-dir -r requirements-backend.txt
+   
+   # Copy application code
+   COPY src/ ./src/
+   ```
+
+2. **Health Check Enhancement**
+   ```yaml
+   # Improved health checks
+   backend:
+     healthcheck:
+       test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+       interval: 30s
+       timeout: 10s
+       retries: 3
+       start_period: 40s
+   ```
+
+3. **Development Volume Optimization**
+   ```yaml
+   # Optimize development volumes
+   backend:
+     volumes:
+       - ./src:/app/src:cached  # Cached for better performance
+       - backend_cache:/app/.cache  # Cache pip packages
+   ```
+
+### **Phase 2: Integration Testing** (Days 12-13)
+1. **Service Integration Tests**
+   ```python
+   # Integration test framework
+   class TestServiceIntegration:
+       async def test_database_connection(self):
+           """Test PostgreSQL connection and basic queries"""
+           
+       async def test_backend_api_endpoints(self):
+           """Test all backend API endpoints"""
+           
+       async def test_frontend_backend_communication(self):
+           """Test frontend can communicate with backend"""
+           
+       async def test_ai_service_integration(self):
+           """Test AI services integration"""
+   ```
+
+2. **End-to-End Workflow Tests**
+   ```python
+   # E2E test scenarios
+   class TestCompleteWorkflow:
+       async def test_user_registration_to_document_generation(self):
+           """Test complete user journey"""
+           # 1. User registration
+           # 2. Application creation  
+           # 3. AI processing phases
+           # 4. Document generation
+           # 5. Document editing
+   ```
+
+### **Phase 3: Performance Monitoring** (Day 14)
+1. **System Metrics Collection**
+   ```python
+   # Performance monitoring
+   class SystemMonitor:
+       def collect_container_metrics(self):
+           """Collect Docker container resource usage"""
+           
+       def monitor_api_response_times(self):
+           """Monitor backend API performance"""
+           
+       def track_database_performance(self):
+           """Track PostgreSQL query performance"""
+           
+       def monitor_ai_processing_times(self):
+           """Track AI service response times"""
+   ```
+
+2. **Automated Health Checks**
+   ```bash
+   # Health check script
+   #!/bin/bash
+   set -e
+   
+   echo "Checking service health..."
+   
+   # Check PostgreSQL
+   docker-compose exec postgres pg_isready -U jobforge_user
+   
+   # Check Backend API
+   curl -f http://localhost:8000/health
+   
+   # Check Frontend
+   curl -f http://localhost:8501
+   
+   echo "All services healthy!"
+   ```
+
+## Docker Management Best Practices
+
+### **Development Workflow Commands**
+```bash
+# Daily development commands
+docker-compose up -d                    # Start all services
+docker-compose logs -f backend          # Monitor backend logs
+docker-compose logs -f frontend         # Monitor frontend logs
+docker-compose restart backend          # Restart after code changes
+docker-compose down && docker-compose up -d  # Full restart
+
+# Debugging commands
+docker-compose ps                        # Check service status
+docker-compose exec backend bash        # Access backend container
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp  # Database access
+
+# Cleanup commands
+docker-compose down -v                   # Stop and remove volumes
+docker system prune -f                  # Clean up Docker resources
+docker-compose build --no-cache         # Rebuild containers
+```
+
+### **Container Debugging Strategies**
+```bash
+# Service not starting
+docker-compose logs [service_name]      # Check startup logs
+docker-compose ps                       # Check exit codes
+docker-compose config                   # Validate compose syntax
+
+# Network issues
+docker network ls                       # List networks
+docker network inspect jobforge_default # Inspect network
+docker-compose exec backend ping postgres  # Test connectivity
+
+# Resource issues
+docker stats                            # Monitor resource usage
+docker system df                        # Check disk usage
+```
+
+## Quality Standards & Monitoring
+
+### **Service Reliability Requirements**
+- **Container Uptime**: >99.9% during development
+- **Health Check Success**: >95% success rate
+- **Service Start Time**: <60 seconds for full stack
+- **Build Time**: <5 minutes for complete rebuild
+
+### **Integration Testing Requirements**
+```bash
+# Integration test execution
+docker-compose -f docker-compose.test.yml up --build --abort-on-container-exit
+docker-compose -f docker-compose.test.yml down -v
+
+# Test coverage requirements
+# - Database connectivity: 100%
+# - API endpoint availability: 100%  
+# - Service communication: 100%
+# - Error handling: >90%
+```
+
+### **Performance Monitoring**
+```python
+# Performance tracking
+class InfrastructureMetrics:
+    def track_container_resource_usage(self):
+        """Monitor CPU, memory, disk usage per container"""
+        
+    def track_api_response_times(self):
+        """Monitor backend API performance"""
+        
+    def track_database_query_performance(self):
+        """Monitor PostgreSQL performance"""
+        
+    def generate_performance_report(self):
+        """Daily performance summary"""
+```
+
+## Troubleshooting Runbook
+
+### **Common Issues & Solutions**
+
+#### **Port Already in Use**
+```bash
+# Find process using port
+lsof -i :8501  # or :8000, :5432
+
+# Kill process
+kill -9 [PID]
+
+# Alternative: Change ports in docker-compose.yml
+```
+
+#### **Database Connection Issues**
+```bash
+# Check PostgreSQL status
+docker-compose ps postgres
+docker-compose logs postgres
+
+# Test database connection
+docker-compose exec postgres pg_isready -U jobforge_user
+
+# Reset database
+docker-compose down -v
+docker-compose up -d postgres
+```
+
+#### **Service Dependencies Not Working**
+```bash
+# Check health check status
+docker-compose ps
+
+# Restart with dependency order
+docker-compose down
+docker-compose up -d postgres
+# Wait for postgres to be healthy
+docker-compose up -d backend
+# Wait for backend to be healthy  
+docker-compose up -d frontend
+```
+
+#### **Memory/Resource Issues**
+```bash
+# Check container resource usage
+docker stats
+
+# Clean up Docker resources
+docker system prune -a -f
+docker volume prune -f
+
+# Increase Docker Desktop resources if needed
+```
+
+### **Emergency Recovery Procedures**
+```bash
+# Complete environment reset
+docker-compose down -v
+docker system prune -a -f
+docker-compose build --no-cache
+docker-compose up -d
+
+# Backup/restore database
+docker-compose exec postgres pg_dump -U jobforge_user jobforge_mvp > backup.sql
+docker-compose exec -T postgres psql -U jobforge_user jobforge_mvp < backup.sql
+```
+
+## Documentation Maintenance
+
+### **Infrastructure Documentation Updates**
+- Keep `docker-compose.yml` properly commented
+- Update `README.md` troubleshooting section with new issues
+- Maintain `GETTING_STARTED.md` with accurate setup steps
+- Document any infrastructure changes in git commits
+
+### **Monitoring and Alerting**
+```python
+# Infrastructure monitoring script
+def check_system_health():
+    """Comprehensive system health check"""
+    services = ['postgres', 'backend', 'frontend']
+    
+    for service in services:
+        health = check_service_health(service)
+        if not health:
+            alert_team(f"{service} is unhealthy")
+            
+def check_service_health(service: str) -> bool:
+    """Check individual service health"""
+    # Implementation specific to each service
+    pass
+```
+
+## Development Support
+
+### **Team Support Responsibilities**
+- Help developers with Docker environment issues
+- Provide guidance on container debugging
+- Maintain consistent development environment across team
+- Support CI/CD pipeline development (future phases)
+
+### **Knowledge Sharing**
+```bash
+# Create helpful aliases for team
+alias dcup='docker-compose up -d'
+alias dcdown='docker-compose down'  
+alias dclogs='docker-compose logs -f'
+alias dcps='docker-compose ps'
+alias dcrestart='docker-compose restart'
+```
+
+## Success Criteria
+
+Your DevOps implementation is successful when:
+- [ ] All Docker services start reliably and maintain health
+- [ ] Development environment provides consistent experience across team
+- [ ] Integration tests validate complete system functionality
+- [ ] Performance monitoring identifies and prevents issues
+- [ ] Documentation enables team self-service for common issues
+- [ ] Troubleshooting procedures resolve 95% of common problems
+- [ ] System uptime exceeds 99.9% during development phases
+
+**Current Priority**: Ensure Docker environment is rock-solid for development team, then implement comprehensive integration testing to catch issues early.

.claude/frontend_developer.md

@@ -0,0 +1,345 @@
+# JobForge Frontend Developer Agent
+
+You are a **Frontend Developer Agent** specialized in building the Dash + Mantine frontend for JobForge MVP. Your expertise is in Python Dash, Mantine UI components, and modern web interfaces.
+
+## Your Core Responsibilities
+
+### 1. **Dash Application Development**
+- Build modern web interface using Dash + Mantine components
+- Create responsive, intuitive user experience for job application management
+- Implement real-time status updates for AI processing phases
+- Ensure proper navigation between application phases
+
+### 2. **API Integration**
+- Connect frontend to FastAPI backend endpoints
+- Handle authentication state and JWT tokens
+- Implement proper error handling and user feedback
+- Manage loading states during AI processing operations
+
+### 3. **User Experience Design**
+- Create professional, modern interface design
+- Implement 3-phase workflow navigation (Research → Resume → Cover Letter)
+- Build document editor with markdown support and live preview
+- Ensure accessibility and responsive design across devices
+
+### 4. **Component Architecture**
+- Develop reusable UI components following consistent patterns
+- Maintain proper separation between pages, components, and API logic
+- Implement proper state management for user sessions
+
+## Key Technical Specifications
+
+### **Required Dependencies**
+```python
+# From requirements-frontend.txt
+dash==2.16.1
+dash-mantine-components==0.12.1
+dash-iconify==0.1.2
+requests==2.31.0
+httpx==0.27.0
+pandas==2.2.1
+plotly==5.18.0
+```
+
+### **Project Structure**
+```
+src/frontend/
+├── main.py              # Dash app entry point
+├── components/          # Reusable UI components
+│   ├── __init__.py
+│   ├── sidebar.py      # Application navigation sidebar
+│   ├── topbar.py       # Top navigation and user menu
+│   ├── editor.py       # Document editor component
+│   ├── forms.py        # Application forms
+│   └── status.py       # Processing status indicators
+├── pages/              # Page components
+│   ├── __init__.py
+│   ├── login.py        # Login/register page
+│   ├── dashboard.py    # Main dashboard
+│   ├── application.py  # Application detail view
+│   └── documents.py    # Document management
+└── api_client/         # Backend API integration
+    ├── __init__.py
+    ├── client.py       # HTTP client for backend
+    └── auth.py         # Authentication handling
+```
+
+### **Dash Application Pattern**
+```python
+# src/frontend/main.py
+import dash
+from dash import html, dcc, Input, Output, State, callback
+import dash_mantine_components as dmc
+
+app = dash.Dash(__name__, external_stylesheets=[])
+
+# Layout structure
+app.layout = dmc.MantineProvider(
+    theme={"colorScheme": "light"},
+    children=[
+        dcc.Location(id="url", refresh=False),
+        dmc.Container(
+            children=[
+                html.Div(id="page-content")
+            ],
+            size="xl"
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    app.run_server(host="0.0.0.0", port=8501, debug=True)
+```
+
+### **API Client Pattern**
+```python
+# src/frontend/api_client/client.py
+import httpx
+from typing import Dict, Any, Optional
+
+class JobForgeAPIClient:
+    def __init__(self, base_url: str = "http://backend:8000"):
+        self.base_url = base_url
+        self.token = None
+    
+    async def authenticate(self, email: str, password: str) -> Dict[str, Any]:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.base_url}/api/v1/auth/login",
+                json={"email": email, "password": password}
+            )
+            if response.status_code == 200:
+                data = response.json()
+                self.token = data["access_token"]
+                return data
+            else:
+                raise Exception(f"Authentication failed: {response.text}")
+    
+    def get_headers(self) -> Dict[str, str]:
+        if not self.token:
+            raise Exception("Not authenticated")
+        return {"Authorization": f"Bearer {self.token}"}
+```
+
+## Implementation Priorities
+
+### **Phase 1: Authentication UI** (Day 4)
+1. **Login/Register Page**
+   ```python
+   # Login form with Mantine components
+   dmc.Paper([
+       dmc.TextInput(label="Email", id="email-input"),
+       dmc.PasswordInput(label="Password", id="password-input"),
+       dmc.Button("Login", id="login-button"),
+       dmc.Text("Don't have an account?"),
+       dmc.Button("Register", variant="subtle", id="register-button")
+   ])
+   ```
+
+2. **Authentication State Management**
+   - Store JWT token in browser session
+   - Handle authentication status across page navigation
+   - Redirect unauthenticated users to login
+
+### **Phase 2: Application Management UI** (Day 6)
+1. **Application List Sidebar**
+   ```python
+   # Sidebar with application list
+   dmc.Navbar([
+       dmc.Button("New Application", id="new-app-button"),
+       dmc.Stack([
+           dmc.Card([
+               dmc.Text(app.company_name, weight=500),
+               dmc.Text(app.role_title, size="sm"),
+               dmc.Badge(app.status, color="blue")
+           ]) for app in applications
+       ])
+   ])
+   ```
+
+2. **Application Form**
+   ```python
+   # Application creation/editing form
+   dmc.Stack([
+       dmc.TextInput(label="Company Name", id="company-input", required=True),
+       dmc.TextInput(label="Role Title", id="role-input", required=True),
+       dmc.Textarea(label="Job Description", id="job-desc-input", 
+                   minRows=6, required=True),
+       dmc.TextInput(label="Job URL (optional)", id="job-url-input"),
+       dmc.Select(label="Priority", data=["low", "medium", "high"], 
+                 id="priority-select"),
+       dmc.Button("Save Application", id="save-app-button")
+   ])
+   ```
+
+### **Phase 3: Document Management UI** (Day 10)
+1. **Phase Navigation Tabs**
+   ```python
+   # 3-phase workflow tabs
+   dmc.Tabs([
+       dmc.TabsList([
+           dmc.Tab("Research", value="research", 
+                  icon=DashIconify(icon="material-symbols:search")),
+           dmc.Tab("Resume", value="resume",
+                  icon=DashIconify(icon="material-symbols:description")),
+           dmc.Tab("Cover Letter", value="cover-letter",
+                  icon=DashIconify(icon="material-symbols:mail"))
+       ]),
+       dmc.TabsPanel(value="research", children=[...]),
+       dmc.TabsPanel(value="resume", children=[...]),
+       dmc.TabsPanel(value="cover-letter", children=[...])
+   ])
+   ```
+
+2. **Document Editor Component**
+   ```python
+   # Markdown editor with preview
+   dmc.Grid([
+       dmc.Col([
+           dmc.Textarea(
+               label="Edit Document",
+               id="document-editor",
+               minRows=20,
+               autosize=True
+           ),
+           dmc.Group([
+               dmc.Button("Save", id="save-doc-button"),
+               dmc.Button("Cancel", variant="outline", id="cancel-doc-button")
+           ])
+       ], span=6),
+       dmc.Col([
+           dmc.Paper([
+               html.Div(id="document-preview")
+           ], p="md")
+       ], span=6)
+   ])
+   ```
+
+### **Phase 4: AI Processing UI** (Days 7, 9, 11)
+1. **Processing Status Indicators**
+   ```python
+   # AI processing status component
+   def create_processing_status(phase: str, status: str):
+       if status == "pending":
+           return dmc.Group([
+               dmc.Loader(size="sm"),
+               dmc.Text(f"{phase} in progress...")
+           ])
+       elif status == "completed":
+           return dmc.Group([
+               DashIconify(icon="material-symbols:check-circle", color="green"),
+               dmc.Text(f"{phase} completed")
+           ])
+       else:
+           return dmc.Group([
+               DashIconify(icon="material-symbols:play-circle"),
+               dmc.Button(f"Start {phase}", id=f"start-{phase}-button")
+           ])
+   ```
+
+2. **Real-time Status Updates**
+   ```python
+   # Callback for polling processing status
+   @callback(
+       Output("processing-status", "children"),
+       Input("status-interval", "n_intervals"),
+       State("application-id", "data")
+   )
+   def update_processing_status(n_intervals, app_id):
+       if not app_id:
+           return dash.no_update
+       
+       # Poll backend for status
+       status = api_client.get_processing_status(app_id)
+       return create_status_display(status)
+   ```
+
+## User Experience Patterns
+
+### **Navigation Flow**
+1. **Login/Register** → **Dashboard** → **Select/Create Application** → **3-Phase Workflow**
+2. **Sidebar Navigation**: Always visible list of user's applications
+3. **Phase Tabs**: Clear indication of current phase and completion status
+4. **Document Editing**: Seamless transition between viewing and editing
+
+### **Loading States**
+- Show loading spinners during API calls
+- Disable buttons during processing to prevent double-clicks
+- Display progress indicators for AI processing phases
+- Provide clear feedback when operations complete
+
+### **Error Handling**
+```python
+# Error notification pattern
+def show_error_notification(message: str):
+    return dmc.Notification(
+        title="Error",
+        id="error-notification",
+        action="show",
+        message=message,
+        color="red",
+        icon=DashIconify(icon="material-symbols:error")
+    )
+```
+
+## Quality Standards
+
+### **UI/UX Requirements**
+- **Responsive Design**: Works on desktop, tablet, and mobile
+- **Loading States**: Clear feedback during all async operations
+- **Error Handling**: Friendly error messages with actionable guidance
+- **Accessibility**: Proper labels, keyboard navigation, screen reader support
+- **Performance**: Components render in <100ms, smooth interactions
+
+### **Code Quality**
+- **Component Reusability**: Create modular, reusable components
+- **State Management**: Clean separation of UI state and data
+- **API Integration**: Proper error handling and loading states
+- **Type Safety**: Use proper type hints where applicable
+
+## Development Workflow
+
+### **Daily Development Pattern**
+1. **Morning**: Review UI requirements and design specifications
+2. **Implementation**: Build components following Mantine design patterns
+3. **Testing**: Test user interactions and API integration
+4. **Refinement**: Polish UI and improve user experience
+
+### **Testing Strategy**
+```bash
+# Manual testing workflow
+1. Start frontend: docker-compose up frontend
+2. Test user flows: registration → login → application creation → AI processing
+3. Verify responsive design across different screen sizes
+4. Check error handling with network interruptions
+```
+
+### **Validation Commands**
+```bash
+# Frontend health check
+curl http://localhost:8501
+
+# Check logs for errors
+docker-compose logs frontend
+```
+
+## Key Context Files
+
+**Always reference these files:**
+- `docs/api_specification.md` - Backend API endpoints and data models
+- `requirements-frontend.txt` - All required Python dependencies
+- `GETTING_STARTED.md` - Day-by-day implementation guide with UI priorities
+- `MVP_CHECKLIST.md` - Track frontend component completion
+
+## Success Criteria
+
+Your frontend implementation is successful when:
+- [ ] Users can register, login, and maintain session state
+- [ ] Application management (create, edit, list) works intuitively
+- [ ] 3-phase AI workflow is clearly represented and navigable
+- [ ] Document editing provides smooth, responsive experience
+- [ ] Real-time status updates show AI processing progress
+- [ ] Error states provide helpful feedback to users
+- [ ] UI is professional, modern, and responsive across devices
+
+**Current Priority**: Start with authentication UI (login/register forms) and session state management, then build application management interface.

.claude/project_architect.md

@@ -0,0 +1,118 @@
+# JobForge Project Architect Agent
+
+You are a **Project Architect Agent** for the JobForge MVP - an AI-powered job application management system. Your role is to help implement the technical architecture and ensure consistency across all development.
+
+## Your Core Responsibilities
+
+### 1. **System Architecture Guidance**
+- Ensure implementation follows the documented architecture in `docs/jobforge_mvp_architecture.md`
+- Maintain consistency between Frontend (Dash+Mantine), Backend (FastAPI), and Database (PostgreSQL+pgvector)
+- Guide the 3-phase AI workflow implementation: Research → Resume Optimization → Cover Letter Generation
+
+### 2. **Technical Standards Enforcement**
+- Follow the coding standards and patterns defined in the documentation
+- Ensure proper async/await patterns throughout the FastAPI backend
+- Maintain PostgreSQL Row-Level Security (RLS) policies for user data isolation
+- Implement proper error handling and validation
+
+### 3. **Development Process Guidance**
+- Follow the day-by-day implementation guide in `GETTING_STARTED.md`
+- Update progress in `MVP_CHECKLIST.md` as features are completed
+- Ensure all Docker services work together properly as defined in `docker-compose.yml`
+
+## Key Technical Context
+
+### **Technology Stack**
+- **Frontend**: Dash + Mantine components (Python-based web framework)
+- **Backend**: FastAPI with AsyncIO for high-performance REST API
+- **Database**: PostgreSQL 16 + pgvector extension for vector search
+- **AI Services**: Claude Sonnet 4 for document generation, OpenAI for embeddings
+- **Development**: Docker Compose for containerized environment
+
+### **Project Structure**
+```
+src/
+├── backend/          # FastAPI backend code
+│   ├── main.py      # FastAPI app entry point
+│   ├── api/         # API route handlers
+│   ├── services/    # Business logic
+│   └── database/    # Database models and connection
+├── frontend/        # Dash frontend code
+│   ├── main.py      # Dash app entry point
+│   ├── components/  # UI components
+│   └── pages/       # Page components
+└── agents/          # AI processing agents
+```
+
+### **Core Workflow Implementation**
+The system implements a 3-phase AI workflow:
+
+1. **Research Agent**: Analyzes job descriptions and researches companies
+2. **Resume Optimizer**: Creates job-specific optimized resumes from user's resume library
+3. **Cover Letter Generator**: Generates personalized cover letters with user context
+
+### **Database Security**
+- All tables use PostgreSQL Row-Level Security (RLS)
+- User data is completely isolated between users
+- JWT tokens for authentication with proper user context setting
+
+## Development Priorities
+
+### **Current Phase**: Foundation Setup ✅ → Core Implementation 🚧
+
+**Immediate Next Steps** (following GETTING_STARTED.md):
+1. Create FastAPI application structure (`src/backend/main.py`)
+2. Implement user authentication system
+3. Add application CRUD operations
+4. Build AI agents integration
+5. Create frontend UI components
+
+### **Quality Standards**
+- **Backend**: 80%+ test coverage, proper async patterns, comprehensive error handling
+- **Database**: All queries use proper indexes, RLS policies enforced
+- **AI Integration**: <30 seconds processing time, >90% relevance accuracy
+- **Frontend**: Responsive design, loading states, proper error handling
+
+## Decision-Making Guidelines
+
+### **Architecture Decisions**
+- Always prioritize user data security (RLS policies)
+- Maintain async/await patterns for performance
+- Follow the documented API specifications exactly
+- Ensure proper separation of concerns (services, models, routes)
+
+### **Implementation Approach**
+- Build incrementally following the day-by-day guide
+- Test each component thoroughly before moving to the next
+- Update documentation and checklists as you progress
+- Focus on MVP functionality over perfection
+
+### **Error Handling Strategy**  
+- Graceful degradation when AI services are unavailable
+- Comprehensive input validation and sanitization
+- User-friendly error messages in the frontend
+- Proper logging for debugging and monitoring
+
+## Context Files to Reference
+
+**Always check these files when making decisions:**
+- `README.md` - Centralized quick reference and commands
+- `GETTING_STARTED.md` - Day-by-day implementation roadmap  
+- `MVP_CHECKLIST.md` - Progress tracking and current status
+- `docs/jobforge_mvp_architecture.md` - Detailed technical architecture
+- `docs/api_specification.md` - Complete REST API documentation
+- `docs/database_design.md` - Database schema and security policies
+
+## Success Metrics
+
+Your implementation is successful when:
+- [ ] All Docker services start and communicate properly
+- [ ] Users can register, login, and manage applications securely
+- [ ] 3-phase AI workflow generates relevant, useful documents
+- [ ] Frontend provides intuitive, responsive user experience
+- [ ] Database maintains proper security and performance
+- [ ] System handles errors gracefully with good user feedback
+
+**Remember**: This is an MVP - focus on core functionality that demonstrates the 3-phase AI workflow effectively. Perfect polish comes later.
+
+**Current Priority**: Implement backend foundation with authentication and basic CRUD operations.

.env.example

@@ -0,0 +1,45 @@
+# =============================================================================
+# JobForge MVP - Environment Variables Template
+# =============================================================================
+# Copy this file to .env and fill in your actual values
+# Never commit .env to version control!
+
+# =============================================================================
+# API KEYS - REQUIRED FOR DEVELOPMENT
+# =============================================================================
+# Get Claude API key from: https://console.anthropic.com/
+CLAUDE_API_KEY=your_claude_api_key_here
+
+# Get OpenAI API key from: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your_openai_api_key_here
+
+# =============================================================================
+# 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
+# =============================================================================
+# Generate a secure random key (minimum 32 characters)
+# You can use: python -c "import secrets; print(secrets.token_urlsafe(32))"
+JWT_SECRET_KEY=your-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

.gitignore

@@ -128,8 +128,10 @@ celerybeat.pid
 # SageMath parsed files
 *.sage.py
 
-# Environments
+# Environment files
 .env
+.env.local
+.env.*.local
 .venv
 env/
 venv/
@@ -137,6 +139,34 @@ ENV/
 env.bak/
 venv.bak/
 
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*.sublime-project
+*.sublime-workspace
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Docker
+.dockerignore
+
+# User data and uploads
+user_data/
+uploads/
+
+# AI model cache
+.cache/
+models/
+
 # Spyder project settings
 .spyderproject
 .spyproject

CLAUDE.md

@@ -0,0 +1,180 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JobForge is an AI-powered job application management system designed for individual job seekers. It combines strategic application management with advanced AI document generation through a 3-phase workflow: Research → Resume Optimization → Cover Letter Generation.
+
+## Technology Stack
+
+- **Frontend**: Dash + Mantine UI components (Python-based web framework)
+- **Backend**: FastAPI with AsyncIO for high-performance REST API
+- **Database**: PostgreSQL 16 + pgvector extension for vector search
+- **AI Services**: Claude Sonnet 4 for document generation, OpenAI for embeddings
+- **Development**: Docker Compose for containerized environment
+- **Authentication**: JWT tokens with bcrypt password hashing
+
+## Development Commands
+
+### Docker Environment
+```bash
+# Start all services (PostgreSQL, Backend, Frontend)
+docker-compose up -d
+
+# View logs for all services
+docker-compose logs -f
+
+# View logs for specific service
+docker-compose logs -f backend
+docker-compose logs -f frontend
+docker-compose logs -f postgres
+
+# Stop all services
+docker-compose down
+
+# Rebuild services after code changes
+docker-compose up --build
+
+# Reset database (WARNING: Deletes all data)
+docker-compose down -v && docker-compose up -d
+```
+
+### Testing
+```bash
+# Run all backend tests
+docker-compose exec backend pytest
+
+# Run tests with coverage report
+docker-compose exec backend pytest --cov=src --cov-report=html
+
+# Run specific test file
+docker-compose exec backend pytest tests/unit/services/test_auth_service.py
+```
+
+### Database Operations
+```bash
+# Connect to PostgreSQL database
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
+
+# Check database health
+curl http://localhost:8000/health
+```
+
+## Architecture Overview
+
+### Core Components
+
+**Frontend Structure (`src/frontend/`)**:
+- `main.py` - Dash application entry point
+- `components/` - Reusable UI components (sidebar, topbar, editor)
+- `pages/` - Page components (login, dashboard, application views)
+- `api_client/` - Backend API client for frontend-backend communication
+
+**Backend Structure (`src/backend/`)**:
+- `main.py` - FastAPI application entry point
+- `api/` - REST API route handlers (auth, applications, documents, processing)
+- `services/` - Business logic layer (auth_service, application_service, document_service, ai_orchestrator)
+- `database/` - Database models and connection management
+- `models/` - Pydantic request/response models
+
+**AI Agents (`src/agents/`)**:
+- `research_agent.py` - Phase 1: Job analysis and company research
+- `resume_optimizer.py` - Phase 2: Resume optimization based on job requirements
+- `cover_letter_generator.py` - Phase 3: Personalized cover letter generation
+- `claude_client.py` - Claude AI API integration
+
+### 3-Phase AI Workflow
+
+1. **Research Phase**: Analyzes job description and researches company information
+2. **Resume Optimization**: Creates job-specific optimized resume from user's resume library
+3. **Cover Letter Generation**: Generates personalized cover letter with user context
+
+### Database Schema
+
+**Core Tables**:
+- `users` - User authentication and profile data
+- `applications` - Job applications with phase tracking
+- `documents` - Generated documents (research reports, resumes, cover letters)
+- `user_resumes` - User's resume library
+- `document_embeddings` - Vector embeddings for AI processing
+
+**Security**: PostgreSQL Row-Level Security (RLS) ensures complete user data isolation.
+
+## Key Development Patterns
+
+### Authentication
+- JWT tokens with 24-hour expiry
+- All API endpoints except auth require `Authorization: Bearer <token>` header
+- User context automatically injected via RLS policies
+
+### API Structure
+- RESTful endpoints following `/api/v1/` pattern
+- Async/await pattern throughout backend
+- Pydantic models for request/response validation
+- Standard HTTP status codes and error responses
+
+### AI Processing
+- Asynchronous processing with status tracking
+- Progress updates via `/processing/applications/{id}/status` endpoint
+- Frontend should poll every 2-3 seconds during AI processing
+- Error handling for external AI API failures
+
+### Frontend Components
+- Dash callbacks for interactivity
+- Mantine components for modern UI
+- Real-time status updates during AI processing
+- Document editor with markdown support and live preview
+
+## Environment Configuration
+
+Required environment variables in `.env`:
+```bash
+# API Keys (REQUIRED)
+CLAUDE_API_KEY=your_claude_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Database
+DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
+
+# JWT Authentication
+JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
+
+# Development Settings
+DEBUG=true
+LOG_LEVEL=INFO
+```
+
+## Service URLs
+
+- **Frontend Application**: http://localhost:8501
+- **Backend API**: http://localhost:8000
+- **API Documentation**: http://localhost:8000/docs (Swagger UI)
+- **Database**: localhost:5432
+
+## Development Guidelines
+
+### Code Style
+- Follow FastAPI patterns for backend development
+- Use async/await for all database and external API calls
+- Implement proper error handling and logging
+- Follow PostgreSQL RLS patterns for data security
+
+### Testing Strategy
+- Unit tests for business logic and services
+- Integration tests for API endpoints and database interactions
+- AI mocking for reliable testing without external API dependencies
+- Maintain 80%+ test coverage
+
+### Security Best Practices
+- Never commit API keys or sensitive data to repository
+- Use environment variables for all configuration
+- Implement proper input validation and sanitization
+- Follow JWT token best practices
+
+## Current Development Status
+
+**Phase**: MVP Development (8-week timeline)
+**Status**: Foundation setup and documentation complete, code implementation in progress
+
+The project is currently in its initial development phase with comprehensive documentation and architecture planning completed. The actual code implementation follows the patterns and structure outlined in the documentation.

GETTING_STARTED.md

@@ -0,0 +1,339 @@
+# 🚀 Getting Started - Day-by-Day Implementation Guide
+
+This guide provides a practical, day-by-day approach to implementing the JobForge MVP. Follow this roadmap to build the system incrementally.
+
+---
+
+## 📅 Week 1: Foundation & Environment
+
+### Day 1: Environment Setup ✅
+- [x] Set up Docker development environment
+- [x] Configure database with PostgreSQL + pgvector
+- [x] Create project structure and documentation
+- [x] Validate all services are running
+
+**Validation Steps:**
+```bash
+docker-compose ps  # All services should be "Up"
+curl http://localhost:8000/health  # Should return when backend is ready
+```
+
+### Day 2: Backend Foundation
+**Goal**: Create FastAPI application structure and health check endpoint
+
+**Tasks:**
+1. Create `src/backend/main.py` with FastAPI app
+2. Add health check endpoint (`/health`)
+3. Set up database connection with AsyncPG
+4. Add basic CORS and middleware configuration
+
+**Validation:**
+- `curl http://localhost:8000/health` returns `{"status": "healthy"}`
+- `curl http://localhost:8000/docs` shows Swagger UI
+
+### Day 3: Database Models & Authentication
+**Goal**: Implement user model and JWT authentication
+
+**Tasks:**
+1. Create `src/backend/models/` with Pydantic models
+2. Create `src/backend/services/auth_service.py`
+3. Implement user registration and login endpoints
+4. Add JWT token generation and validation
+
+**Endpoints to implement:**
+- `POST /api/v1/auth/register`
+- `POST /api/v1/auth/login`
+- `GET /api/v1/auth/me`
+
+**Validation:**
+```bash
+# Register user
+curl -X POST http://localhost:8000/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpass123","full_name":"Test User"}'
+
+# Login
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpass123"}'
+```
+
+### Day 4: Frontend Foundation
+**Goal**: Create basic Dash application with authentication UI
+
+**Tasks:**
+1. Create `src/frontend/main.py` with Dash app
+2. Create login/register components
+3. Set up API client for backend communication
+4. Implement basic navigation structure
+
+**Validation:**
+- Visit http://localhost:8501 shows login page
+- Can register and login through UI
+- Successful login redirects to dashboard
+
+### Day 5: Application CRUD - Backend
+**Goal**: Implement job application management (backend)
+
+**Tasks:**
+1. Create application models and database schema
+2. Implement `src/backend/services/application_service.py`
+3. Add application CRUD endpoints
+4. Test with Row Level Security policies
+
+**Endpoints to implement:**
+- `POST /api/v1/applications`
+- `GET /api/v1/applications`
+- `GET /api/v1/applications/{id}`
+- `PUT /api/v1/applications/{id}`
+- `DELETE /api/v1/applications/{id}`
+
+**Validation:**
+```bash
+# Create application (with auth token)
+curl -X POST http://localhost:8000/api/v1/applications \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"company_name":"Google","role_title":"Developer","job_description":"We are looking for..."}'
+```
+
+---
+
+## 📅 Week 2: Core Features
+
+### Day 6: Application CRUD - Frontend
+**Goal**: Create application management UI
+
+**Tasks:**
+1. Create application list/sidebar component
+2. Create application form component
+3. Implement application creation workflow
+4. Add basic application status display
+
+**Validation:**
+- Can create new applications through UI
+- Applications appear in sidebar
+- Can view application details
+
+### Day 7: AI Agents - Research Agent
+**Goal**: Implement the first AI agent for job research
+
+**Tasks:**
+1. Create `src/agents/research_agent.py`
+2. Implement Claude API integration
+3. Create prompts for job description analysis
+4. Add research report generation endpoint
+
+**AI Agent Structure:**
+```python
+class ResearchAgent:
+    async def analyze_job_description(self, job_desc: str) -> JobAnalysis
+    async def research_company_info(self, company_name: str) -> CompanyInfo
+    async def generate_research_report(self, application_id: str) -> ResearchReport
+```
+
+**Validation:**
+- Can trigger research phase for an application
+- Research report is generated and stored
+- Content is relevant and well-formatted
+
+### Day 8: Resume Management
+**Goal**: Implement resume library functionality
+
+**Tasks:**
+1. Create resume models and endpoints
+2. Add resume upload and storage
+3. Create resume management UI
+4. Implement resume selection for applications
+
+**Endpoints:**
+- `GET /api/v1/resumes`
+- `POST /api/v1/resumes`
+- `GET /api/v1/resumes/{id}`
+- `PUT /api/v1/resumes/{id}`
+
+### Day 9: AI Agents - Resume Optimizer
+**Goal**: Implement resume optimization agent
+
+**Tasks:**
+1. Create `src/agents/resume_optimizer.py`
+2. Implement resume analysis and optimization
+3. Add resume optimization endpoint
+4. Connect to application workflow
+
+**Validation:**
+- Can optimize resume based on job requirements
+- Optimized resume is stored and retrievable
+- Changes are meaningful and relevant
+
+### Day 10: Document Management UI
+**Goal**: Create document viewing and editing interface
+
+**Tasks:**
+1. Create document editor component with markdown support
+2. Add document preview functionality
+3. Implement save/cancel functionality
+4. Add phase navigation between documents
+
+**Validation:**
+- Can view generated documents
+- Can edit document content
+- Changes are saved and persist
+- Navigation between phases works
+
+---
+
+## 📅 Week 3: AI Integration & Polish
+
+### Day 11: AI Agents - Cover Letter Generator
+**Goal**: Complete the 3-phase AI workflow
+
+**Tasks:**
+1. Create `src/agents/cover_letter_generator.py`
+2. Implement cover letter generation
+3. Add user context input functionality
+4. Complete the full workflow integration
+
+**Validation:**
+- Full 3-phase workflow works end-to-end
+- Cover letters are personalized and relevant
+- User can provide additional context
+
+### Day 12: Error Handling & Validation
+**Goal**: Add robust error handling and validation
+
+**Tasks:**
+1. Add comprehensive input validation
+2. Implement error handling for AI API failures
+3. Add user-friendly error messages
+4. Create fallback mechanisms for AI services
+
+### Day 13: Testing & Quality Assurance
+**Goal**: Add essential tests and quality checks
+
+**Tasks:**
+1. Write unit tests for core services
+2. Add integration tests for API endpoints
+3. Test database security policies
+4. Implement basic load testing
+
+**Testing Commands:**
+```bash
+# Run all tests
+docker-compose exec backend pytest
+
+# Run with coverage
+docker-compose exec backend pytest --cov=src --cov-report=html
+
+# Test specific functionality
+docker-compose exec backend pytest tests/unit/services/test_auth_service.py
+```
+
+### Day 14: Performance Optimization
+**Goal**: Optimize system performance and reliability
+
+**Tasks:**
+1. Optimize database queries and indexes
+2. Add caching for AI responses
+3. Implement request rate limiting
+4. Add monitoring and logging
+
+---
+
+## 📅 Week 4: Final Polish & Deployment
+
+### Day 15-17: UI/UX Polish
+**Goals:**
+- Improve user interface design and responsiveness
+- Add loading states and progress indicators
+- Implement better navigation and user flow
+- Add help text and user guidance
+
+### Day 18-19: Security & Production Readiness
+**Goals:**
+- Security audit and hardening
+- Environment-specific configurations
+- Production deployment preparation
+- Documentation updates
+
+### Day 20: Final Testing & Release
+**Goals:**
+- End-to-end testing of complete workflows
+- Performance testing under load
+- Final bug fixes and polish
+- MVP release preparation
+
+---
+
+## 🎯 Daily Validation Checklist
+
+Use this checklist at the end of each day to ensure progress:
+
+### Backend Development
+- [ ] New endpoints work correctly
+- [ ] Database changes are applied
+- [ ] Tests pass for new functionality
+- [ ] API documentation is updated
+- [ ] Error handling is implemented
+
+### Frontend Development
+- [ ] UI components render correctly
+- [ ] User interactions work as expected
+- [ ] API integration functions properly
+- [ ] Responsive design is maintained
+- [ ] Loading states are implemented
+
+### AI Agents
+- [ ] AI responses are relevant and useful
+- [ ] Error handling for API failures
+- [ ] Performance is acceptable (<30s per operation)
+- [ ] Content quality meets standards
+- [ ] Integration with workflow is seamless
+
+---
+
+## 🚨 Common Daily Blockers & Solutions
+
+### "AI API is not responding"
+```bash
+# Check API keys are set
+echo $CLAUDE_API_KEY
+echo $OPENAI_API_KEY
+
+# Test API connectivity
+curl -H "Authorization: Bearer $CLAUDE_API_KEY" https://api.anthropic.com/v1/messages
+```
+
+### "Database changes not reflected"
+```bash
+# Restart database service
+docker-compose restart postgres
+
+# Check database logs
+docker-compose logs postgres
+
+# Reconnect to verify changes
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
+```
+
+### "Frontend not updating"
+```bash
+# Clear browser cache
+# Check frontend logs
+docker-compose logs frontend
+
+# Restart frontend service
+docker-compose restart frontend
+```
+
+---
+
+## 📈 Progress Tracking
+
+Track your daily progress in [MVP_CHECKLIST.md](MVP_CHECKLIST.md) and update the README status as you complete each phase.
+
+**Remember**: This is an MVP - focus on core functionality over perfection. The goal is to have a working end-to-end system that demonstrates the 3-phase AI workflow.
+
+---
+
+**Ready to start building? Begin with Day 1 and work through each day systematically! 🚀**

MVP_CHECKLIST.md

@@ -0,0 +1,247 @@
+# 📋 MVP Development Checklist
+
+Track your progress through the JobForge MVP development. Update this checklist as you complete each feature.
+
+---
+
+## 🎯 Current Status: Foundation Setup ✅
+
+**Overall Progress**: 25% Complete (Foundation & Environment)
+
+---
+
+## 📅 Week 1: Foundation & Environment
+
+### Day 1: Environment Setup ✅
+- [x] Docker development environment configured
+- [x] PostgreSQL + pgvector database running
+- [x] Project structure created
+- [x] Documentation centralized in README.md
+- [x] All services validated (postgres, backend, frontend)
+
+### Day 2: Backend Foundation 🚧
+- [ ] Create `src/backend/main.py` with FastAPI app
+- [ ] Add health check endpoint (`/health`)
+- [ ] Set up database connection with AsyncPG
+- [ ] Add CORS and middleware configuration
+- [ ] **Validation**: `curl http://localhost:8000/health` works
+
+### Day 3: Database Models & Authentication 📋
+- [ ] Create Pydantic models in `src/backend/models/`
+- [ ] Implement `src/backend/services/auth_service.py`
+- [ ] Add user registration endpoint
+- [ ] Add user login endpoint
+- [ ] Add JWT token validation
+- [ ] **Validation**: Can register and login via API
+
+### Day 4: Frontend Foundation 📋
+- [ ] Create `src/frontend/main.py` with Dash app
+- [ ] Create login/register UI components
+- [ ] Set up API client for backend communication
+- [ ] Implement basic navigation structure
+- [ ] **Validation**: Can register/login through UI
+
+### Day 5: Application CRUD - Backend 📋
+- [ ] Create application models and schemas
+- [ ] Implement `src/backend/services/application_service.py`
+- [ ] Add all application CRUD endpoints
+- [ ] Test Row Level Security policies
+- [ ] **Validation**: Can create applications via API
+
+---
+
+## 📅 Week 2: Core Features
+
+### Day 6: Application CRUD - Frontend 📋
+- [ ] Create application list/sidebar component
+- [ ] Create application form component
+- [ ] Implement application creation workflow
+- [ ] Add application status display
+- [ ] **Validation**: Can manage applications through UI
+
+### Day 7: AI Agents - Research Agent 📋
+- [ ] Create `src/agents/research_agent.py`
+- [ ] Implement Claude API integration
+- [ ] Create job analysis prompts
+- [ ] Add research report generation
+- [ ] **Validation**: Research phase generates useful reports
+
+### Day 8: Resume Management 📋
+- [ ] Create resume models and endpoints
+- [ ] Add resume upload and storage
+- [ ] Create resume management UI
+- [ ] Implement resume selection for applications
+- [ ] **Validation**: Can manage resume library
+
+### Day 9: AI Agents - Resume Optimizer 📋
+- [ ] Create `src/agents/resume_optimizer.py`
+- [ ] Implement resume analysis and optimization
+- [ ] Add resume optimization endpoint
+- [ ] Connect to application workflow
+- [ ] **Validation**: Resume optimization produces relevant changes
+
+### Day 10: Document Management UI 📋
+- [ ] Create document editor with markdown support
+- [ ] Add document preview functionality
+- [ ] Implement save/cancel functionality
+- [ ] Add phase navigation between documents
+- [ ] **Validation**: Can view and edit all generated documents
+
+---
+
+## 📅 Week 3: AI Integration & Polish
+
+### Day 11: AI Agents - Cover Letter Generator 📋
+- [ ] Create `src/agents/cover_letter_generator.py`
+- [ ] Implement cover letter generation
+- [ ] Add user context input functionality
+- [ ] Complete full workflow integration
+- [ ] **Validation**: Complete 3-phase workflow works end-to-end
+
+### Day 12: Error Handling & Validation 📋
+- [ ] Add comprehensive input validation
+- [ ] Implement AI API failure handling
+- [ ] Add user-friendly error messages
+- [ ] Create fallback mechanisms
+- [ ] **Validation**: System handles errors gracefully
+
+### Day 13: Testing & Quality Assurance 📋
+- [ ] Write unit tests for core services
+- [ ] Add integration tests for API endpoints
+- [ ] Test database security policies
+- [ ] Implement basic performance testing
+- [ ] **Validation**: Test coverage >80% for backend
+
+### Day 14: Performance Optimization 📋
+- [ ] Optimize database queries and indexes
+- [ ] Add caching for AI responses
+- [ ] Implement request rate limiting
+- [ ] Add monitoring and logging
+- [ ] **Validation**: AI operations complete <30 seconds
+
+---
+
+## 📅 Week 4: Final Polish & Deployment
+
+### Days 15-17: UI/UX Polish 📋
+- [ ] Improve interface design and responsiveness
+- [ ] Add loading states and progress indicators
+- [ ] Implement better navigation and user flow
+- [ ] Add help text and user guidance
+- [ ] **Validation**: UI is professional and intuitive
+
+### Days 18-19: Security & Production Readiness 📋
+- [ ] Complete security audit and hardening
+- [ ] Configure environment-specific settings
+- [ ] Prepare production deployment configuration
+- [ ] Update all documentation
+- [ ] **Validation**: Security review passes
+
+### Day 20: Final Testing & Release 📋
+- [ ] End-to-end testing of complete workflows
+- [ ] Performance testing under load
+- [ ] Final bug fixes and polish
+- [ ] MVP release preparation
+- [ ] **Validation**: Full system works reliably
+
+---
+
+## 🏆 MVP Success Criteria
+
+### Core Functionality ✅/❌
+- [ ] User can register and login securely
+- [ ] User can create job applications with descriptions
+- [ ] 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
+- [ ] Phase navigation works smoothly
+- [ ] Data is persisted securely with user isolation
+
+### Performance Criteria ✅/❌
+- [ ] AI processing completes within 30 seconds per phase
+- [ ] API responses return within 500ms for CRUD operations
+- [ ] Database queries execute efficiently with proper indexes
+- [ ] Frontend loads and responds quickly (<2 seconds)
+- [ ] System handles concurrent users without issues
+
+### Quality Criteria ✅/❌
+- [ ] Code coverage >80% for backend services
+- [ ] All API endpoints documented and tested
+- [ ] Database security policies prevent cross-user access
+- [ ] Error handling provides meaningful feedback
+- [ ] AI-generated content is relevant and useful
+
+---
+
+## 📊 Development Metrics
+
+### Backend Progress
+- **API Endpoints**: 0/15 implemented
+- **Services**: 0/5 implemented  
+- **Test Coverage**: 0%
+- **Database Tables**: 5/5 created ✅
+
+### Frontend Progress
+- **Components**: 0/8 implemented
+- **Pages**: 0/4 implemented
+- **API Integration**: 0% complete
+
+### AI Agents Progress
+- **Research Agent**: 0% complete
+- **Resume Optimizer**: 0% complete
+- **Cover Letter Generator**: 0% complete
+- **Integration**: 0% complete
+
+---
+
+## 🚨 Current Blockers
+
+*Update this section with any current blockers or issues*
+
+### Active Issues
+- None currently
+
+### Resolved Issues
+- ✅ Environment setup completed
+- ✅ Database schema created
+- ✅ Docker services configured
+
+---
+
+## 📝 Daily Notes
+
+### Latest Update: [Date]
+*Add daily progress notes here*
+
+**Today's Progress:**
+- Completed environment setup
+- All Docker services running
+- Database initialized with proper schema
+
+**Tomorrow's Goals:**
+- Start backend FastAPI application
+- Implement health check endpoint
+- Set up database connection
+
+**Learnings:**
+- Docker Compose health checks are crucial for service dependencies
+- pgvector extension setup requires specific image version
+
+---
+
+## 🎯 Next Steps
+
+1. **Immediate (Today)**: Start Day 2 - Backend Foundation
+2. **This Week**: Complete authentication and basic CRUD operations  
+3. **This Month**: Complete MVP with full 3-phase AI workflow
+
+---
+
+**Remember**: This is an MVP - focus on core functionality over perfection. The goal is to have a working end-to-end system that demonstrates the 3-phase AI workflow.
+
+**Current Priority**: Complete backend foundation and authentication system.
+
+---
+
+*Last Updated: [Current Date] - Update this checklist daily as you make progress!*

README.md

@@ -1,3 +1,337 @@
-# job-forge
+# ⚡ JobForge MVP
 
-A tool to help with job applications.
+**AI-Powered Job Application Management System**
+
+Transform your job search with intelligent document generation and strategic application management. JobForge uses Claude Sonnet 4 and OpenAI to create tailored resumes and cover letters through a 3-phase AI workflow.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-green.svg)](https://fastapi.tiangolo.com/)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-blue.svg)](https://www.postgresql.org/)
+
+---
+
+## 🚀 Quick Start (5 Minutes)
+
+### Prerequisites
+- **Docker Desktop** 4.20+ with Docker Compose
+- **API Keys**: Claude API key, OpenAI API key  
+- **Git** 2.30+
+
+### 1. Clone & Setup
+```bash
+git clone https://github.com/your-org/jobforge-mvp.git
+cd jobforge-mvp
+
+# Copy environment template and add your API keys
+cp .env.example .env
+nano .env  # Add CLAUDE_API_KEY and OPENAI_API_KEY
+```
+
+### 2. 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
+```
+
+### 3. Verify Installation
+Open these URLs to verify everything is working:
+- **Frontend Application**: http://localhost:8501
+- **Backend API**: http://localhost:8000
+- **API Documentation**: http://localhost:8000/docs
+
+### 4. Quick Validation
+```bash
+# Check backend health
+curl http://localhost:8000/health
+
+# Check all services are running
+docker-compose ps
+```
+
+All services should show "Up" status. If any issues, see [Troubleshooting](#-troubleshooting) below.
+
+---
+
+## ✨ What is JobForge?
+
+JobForge is an AI-powered job application management system that streamlines your job search through intelligent document generation. Built for individual job seekers, it combines strategic application management with advanced AI to maximize your chances of landing interviews.
+
+### Key Features
+- **3-Phase AI Workflow**: Research → Resume Optimization → Cover Letter Generation
+- **Modern Interface**: Professional web app with intuitive navigation
+- **Secure & Private**: Complete user data isolation with PostgreSQL Row-Level Security
+- **AI-Powered**: Claude Sonnet 4 for document generation, OpenAI for semantic matching
+
+### Technology Stack
+- **Frontend**: Dash + Mantine components
+- **Backend**: FastAPI + AsyncIO
+- **Database**: PostgreSQL 16 + pgvector
+- **AI**: Claude Sonnet 4, OpenAI embeddings
+- **Development**: Docker Compose
+
+---
+
+## 🛠️ Development Commands
+
+### Essential Commands
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs for all services
+docker-compose logs -f
+
+# View logs for specific service
+docker-compose logs -f backend
+docker-compose logs -f frontend
+docker-compose logs -f postgres
+
+# Stop all services
+docker-compose down
+
+# Rebuild after code changes
+docker-compose up --build
+
+# Reset database (WARNING: Deletes all data)
+docker-compose down -v && docker-compose up -d
+```
+
+### Testing
+```bash
+# Run backend tests
+docker-compose exec backend pytest
+
+# Run tests with coverage
+docker-compose exec backend pytest --cov=src --cov-report=html
+
+# Run specific test file
+docker-compose exec backend pytest tests/unit/services/test_auth_service.py
+```
+
+### Database Operations
+```bash
+# Connect to PostgreSQL database
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
+
+# Check database health
+curl http://localhost:8000/health
+```
+
+---
+
+## 🏗️ Project Structure
+
+```
+jobforge-mvp/
+├── src/
+│   ├── backend/          # FastAPI backend code
+│   │   ├── main.py      # FastAPI app entry point
+│   │   ├── api/         # API route handlers
+│   │   ├── services/    # Business logic
+│   │   └── database/    # Database models and connection
+│   ├── frontend/        # Dash frontend code
+│   │   ├── main.py      # Dash app entry point
+│   │   ├── components/  # UI components
+│   │   └── pages/       # Page components
+│   └── agents/          # AI processing agents
+├── database/
+│   └── init.sql         # Database initialization
+├── docs/                # Detailed technical documentation
+├── docker-compose.yml   # Development environment
+├── requirements-backend.txt
+├── requirements-frontend.txt
+└── .env.example         # Environment template
+```
+
+---
+
+## 🔧 Environment Configuration
+
+### Required Environment Variables
+Copy `.env.example` to `.env` and configure:
+
+```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
+```
+
+### 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
+
+---
+
+## 📚 Documentation
+
+All technical documentation is centralized in the `/docs` folder:
+
+### Core Documentation
+- **[Development Setup](docs/development_setup.md)** - Complete environment setup with troubleshooting
+- **[MVP Architecture](docs/jobforge_mvp_architecture.md)** - High-level system design and component overview
+- **[API Specification](docs/api_specification.md)** - Complete REST API documentation with examples
+- **[Database Design](docs/database_design.md)** - Schema, security policies, and optimization
+
+### Process Documentation
+- **[Git Branch Strategy](docs/git_branch_strategy.md)** - Version control workflow and team coordination
+- **[Testing Strategy](docs/testing_strategy.md)** - Testing guidelines and automation setup
+- **[Team Management](docs/team_management_guide.md)** - Team roles, processes, and standards
+
+---
+
+## 🐛 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-"
+
+# Ensure .env file is in project root
+ls -la .env
+```
+
+#### "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
+```
+
+### Clean Restart
+If you encounter persistent issues:
+```bash
+# Complete clean restart
+docker-compose down -v
+docker system prune -f
+docker-compose up --build -d
+```
+
+---
+
+## 🎯 Development Workflow
+
+### 1. Starting Development
+```bash
+# Ensure latest code
+git pull origin main
+
+# Start environment
+docker-compose up -d
+
+# Verify all services
+docker-compose ps
+curl http://localhost:8000/health
+```
+
+### 2. Making Changes
+```bash
+# Backend changes auto-reload
+# Frontend changes auto-reload
+# Database changes require restart: docker-compose restart postgres
+```
+
+### 3. Testing Changes
+```bash
+# Run tests
+docker-compose exec backend pytest
+
+# Check logs
+docker-compose logs -f backend
+```
+
+---
+
+## 🚀 MVP Development Status
+
+### Current Phase: Foundation Setup ✅
+- [x] Project structure and documentation
+- [x] Docker development environment
+- [x] Database schema with RLS policies
+- [x] Environment configuration
+
+### Next Phase: Core Implementation 🚧
+- [ ] User authentication system
+- [ ] Application CRUD operations
+- [ ] AI agents integration
+- [ ] Frontend UI components
+
+### Future Phases 📋
+- [ ] AI-powered research generation
+- [ ] Resume optimization engine
+- [ ] Cover letter generation
+- [ ] Document editing interface
+- [ ] Production deployment
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+**Ready to transform your job search? Let's build something amazing! 🚀**

database/init.sql

@@ -0,0 +1,213 @@
+-- JobForge MVP Database Initialization
+-- This file sets up the database schema with Row Level Security
+
+-- Enable required extensions
+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'
+);
+CREATE TYPE document_type_enum AS ENUM (
+    'research_report', 
+    'optimized_resume', 
+    'cover_letter'
+);
+CREATE TYPE focus_area_type AS ENUM (
+    'software_development',
+    'data_science', 
+    'management',
+    'consulting',
+    'other'
+);
+
+-- Users table
+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 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)
+);
+
+-- Applications table
+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,
+    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(),
+    
+    -- Constraints
+    CONSTRAINT job_description_min_length CHECK (LENGTH(job_description) >= 50),
+    CONSTRAINT company_name_not_empty CHECK (LENGTH(TRIM(company_name)) > 0),
+    CONSTRAINT role_title_not_empty CHECK (LENGTH(TRIM(role_title)) > 0),
+    CONSTRAINT valid_job_url CHECK (
+        job_url IS NULL OR 
+        job_url ~* '^https?://[^\s/$.?#].[^\s]*$'
+    )
+);
+
+-- Documents table
+CREATE TABLE documents (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    document_type document_type_enum NOT NULL,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT content_min_length CHECK (LENGTH(content) >= 10),
+    CONSTRAINT unique_document_per_application UNIQUE (application_id, document_type)
+);
+
+-- User resumes table
+CREATE TABLE user_resumes (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(255) NOT NULL,
+    content TEXT NOT NULL,
+    focus_area focus_area_type DEFAULT 'other',
+    is_primary BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT resume_name_not_empty CHECK (LENGTH(TRIM(name)) > 0),
+    CONSTRAINT resume_content_min_length CHECK (LENGTH(content) >= 100)
+);
+
+-- Document embeddings table (for AI features)
+CREATE TABLE document_embeddings (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    embedding vector(1536),  -- OpenAI text-embedding-3-large dimension
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT unique_embedding_per_document UNIQUE (document_id)
+);
+
+-- Create indexes
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_applications_user_id ON applications(user_id);
+CREATE INDEX idx_applications_status ON applications(status);
+CREATE INDEX idx_applications_created_at ON applications(created_at);
+CREATE INDEX idx_documents_application_id ON documents(application_id);
+CREATE INDEX idx_documents_type ON documents(document_type);
+CREATE INDEX idx_user_resumes_user_id ON user_resumes(user_id);
+CREATE INDEX idx_document_embeddings_document_id ON document_embeddings(document_id);
+
+-- Vector similarity index
+CREATE INDEX idx_document_embeddings_vector 
+ON document_embeddings USING ivfflat (embedding vector_cosine_ops)
+WITH (lists = 100);
+
+-- Row Level Security setup
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+ALTER TABLE user_resumes ENABLE ROW LEVEL SECURITY;
+ALTER TABLE document_embeddings ENABLE ROW LEVEL SECURITY;
+
+-- Helper function to get current user ID
+CREATE OR REPLACE FUNCTION get_current_user_id()
+RETURNS UUID AS $$
+BEGIN
+    RETURN current_setting('app.current_user_id')::UUID;
+EXCEPTION
+    WHEN others THEN
+        RETURN NULL;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- RLS policies
+CREATE POLICY users_own_data ON users
+    FOR ALL 
+    USING (id = get_current_user_id());
+
+CREATE POLICY applications_user_access ON applications
+    FOR ALL
+    USING (user_id = get_current_user_id());
+
+CREATE POLICY documents_user_access ON documents
+    FOR ALL
+    USING (
+        application_id IN (
+            SELECT id FROM applications 
+            WHERE user_id = get_current_user_id()
+        )
+    );
+
+CREATE POLICY user_resumes_access ON user_resumes
+    FOR ALL
+    USING (user_id = get_current_user_id());
+
+CREATE POLICY document_embeddings_access ON document_embeddings
+    FOR ALL
+    USING (
+        document_id IN (
+            SELECT d.id FROM documents d
+            JOIN applications a ON d.application_id = a.id
+            WHERE a.user_id = get_current_user_id()
+        )
+    );
+
+-- Trigger function for updating timestamps
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply timestamp triggers
+CREATE TRIGGER update_users_updated_at
+    BEFORE UPDATE ON users
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_applications_updated_at
+    BEFORE UPDATE ON applications  
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_documents_updated_at
+    BEFORE UPDATE ON documents
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_user_resumes_updated_at
+    BEFORE UPDATE ON user_resumes
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- Insert a test user for development (password: "testpass123")
+INSERT INTO users (id, email, password_hash, full_name) VALUES (
+    '123e4567-e89b-12d3-a456-426614174000',
+    'test@example.com', 
+    '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewgdyN8yF5V4M2kq',
+    'Test User'
+) ON CONFLICT (email) DO NOTHING;

docker-compose.yml

@@ -0,0 +1,65 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    container_name: jobforge_postgres
+    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
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U jobforge_user -d jobforge_mvp"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend
+    container_name: jobforge_backend
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
+      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
+      - DEBUG=true
+      - LOG_LEVEL=INFO
+    volumes:
+      - ./src:/app/src
+    depends_on:
+      postgres:
+        condition: service_healthy
+    command: uvicorn src.backend.main:app --host 0.0.0.0 --port 8000 --reload
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile.frontend
+    container_name: jobforge_frontend
+    ports:
+      - "8501:8501"
+    environment:
+      - BACKEND_URL=http://backend:8000
+    volumes:
+      - ./src/frontend:/app/src/frontend
+    depends_on:
+      backend:
+        condition: service_healthy
+    command: python src/frontend/main.py
+
+volumes:
+  postgres_data:

docs/api_specification.md

@@ -0,0 +1,597 @@
+# JobForge MVP - API Specification
+
+**Version:** 1.0.0 MVP  
+**Base URL:** `http://localhost:8000`  
+**Target Audience:** Backend Developers  
+**Last Updated:** July 2025
+
+---
+
+## 🔐 Authentication
+
+### Overview
+- **Method:** JWT Bearer tokens
+- **Token Expiry:** 24 hours
+- **Refresh:** Not implemented in MVP (re-login required)
+- **Header Format:** `Authorization: Bearer <jwt_token>`
+
+### Authentication Endpoints
+
+#### POST /api/v1/auth/register
+Register new user account.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "full_name": "John Doe"
+}
+```
+
+**Response (201):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "email": "user@example.com",
+  "full_name": "John Doe",
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer"
+}
+```
+
+**Errors:**
+- `400` - Invalid email format or weak password
+- `409` - Email already registered
+
+#### POST /api/v1/auth/login
+Authenticate user and return JWT token.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!"
+}
+```
+
+**Response (200):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "email": "user@example.com",
+  "full_name": "John Doe",
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer"
+}
+```
+
+**Errors:**
+- `401` - Invalid credentials
+- `400` - Missing email or password
+
+#### GET /api/v1/auth/me
+Get current user profile (requires authentication).
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "email": "user@example.com",
+  "full_name": "John Doe",
+  "created_at": "2025-07-01T10:00:00Z"
+}
+```
+
+**Errors:**
+- `401` - Invalid or expired token
+
+---
+
+## 📋 Applications API
+
+### Application Model
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "name": "google_senior_developer_2025_07_01",
+  "company_name": "Google",
+  "role_title": "Senior Developer", 
+  "job_url": "https://careers.google.com/jobs/123",
+  "job_description": "We are looking for...",
+  "location": "Toronto, ON",
+  "priority_level": "high",
+  "status": "draft",
+  "research_completed": false,
+  "resume_optimized": false,
+  "cover_letter_generated": false,
+  "created_at": "2025-07-01T10:00:00Z",
+  "updated_at": "2025-07-01T10:00:00Z"
+}
+```
+
+### Application Endpoints
+
+#### POST /api/v1/applications
+Create new job application.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:**
+```json
+{
+  "company_name": "Google",
+  "role_title": "Senior Developer",
+  "job_description": "We are looking for an experienced developer...",
+  "job_url": "https://careers.google.com/jobs/123",
+  "location": "Toronto, ON",
+  "priority_level": "high",
+  "additional_context": "Found through LinkedIn, know someone there"
+}
+```
+
+**Response (201):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "name": "google_senior_developer_2025_07_01",
+  "company_name": "Google",
+  "role_title": "Senior Developer",
+  "job_url": "https://careers.google.com/jobs/123", 
+  "job_description": "We are looking for an experienced developer...",
+  "location": "Toronto, ON",
+  "priority_level": "high",
+  "status": "draft",
+  "research_completed": false,
+  "resume_optimized": false,
+  "cover_letter_generated": false,
+  "created_at": "2025-07-01T10:00:00Z",
+  "updated_at": "2025-07-01T10:00:00Z"
+}
+```
+
+**Validation Rules:**
+- `company_name`: Required, 1-255 characters
+- `role_title`: Required, 1-255 characters  
+- `job_description`: Required, minimum 50 characters
+- `job_url`: Optional, valid URL format
+- `priority_level`: Optional, enum: `low|medium|high`
+
+**Errors:**
+- `400` - Validation errors
+- `401` - Unauthorized
+
+#### GET /api/v1/applications
+List user's applications.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Query Parameters:**
+- `status`: Filter by status (optional)
+- `priority`: Filter by priority level (optional)
+- `limit`: Number of results (default: 50, max: 100)
+- `offset`: Pagination offset (default: 0)
+
+**Response (200):**
+```json
+{
+  "applications": [
+    {
+      "id": "123e4567-e89b-12d3-a456-426614174000",
+      "name": "google_senior_developer_2025_07_01",
+      "company_name": "Google",
+      "role_title": "Senior Developer",
+      "status": "research_complete",
+      "priority_level": "high",
+      "research_completed": true,
+      "resume_optimized": false,
+      "cover_letter_generated": false,
+      "created_at": "2025-07-01T10:00:00Z",
+      "updated_at": "2025-07-01T11:30:00Z"
+    }
+  ],
+  "total": 1,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+#### GET /api/v1/applications/{application_id}
+Get specific application details.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):** Full application object (see Application Model above)
+
+**Errors:**
+- `404` - Application not found or not owned by user
+- `401` - Unauthorized
+
+#### PUT /api/v1/applications/{application_id}
+Update application details.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:**
+```json
+{
+  "company_name": "Google Inc.",
+  "location": "Toronto, ON, Canada",
+  "priority_level": "medium"
+}
+```
+
+**Response (200):** Updated application object
+
+**Errors:**
+- `404` - Application not found
+- `400` - Validation errors
+- `401` - Unauthorized
+
+#### DELETE /api/v1/applications/{application_id}
+Delete application and all associated documents.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (204):** No content
+
+**Errors:**
+- `404` - Application not found
+- `401` - Unauthorized
+
+---
+
+## 📄 Documents API
+
+### Document Model
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "application_id": "456e7890-e89b-12d3-a456-426614174000", 
+  "document_type": "research_report",
+  "content": "# Research Report\n\n## Job Analysis\n...",
+  "created_at": "2025-07-01T10:30:00Z",
+  "updated_at": "2025-07-01T10:30:00Z"
+}
+```
+
+### Document Endpoints
+
+#### GET /api/v1/applications/{application_id}/documents
+Get all documents for an application.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):**
+```json
+{
+  "research_report": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "content": "# Research Report\n\n## Job Analysis\n...",
+    "created_at": "2025-07-01T10:30:00Z",
+    "updated_at": "2025-07-01T10:30:00Z"
+  },
+  "optimized_resume": {
+    "id": "234e5678-e89b-12d3-a456-426614174000",
+    "content": "# John Doe\n\n## Experience\n...",
+    "created_at": "2025-07-01T11:00:00Z",
+    "updated_at": "2025-07-01T11:00:00Z"
+  },
+  "cover_letter": null
+}
+```
+
+#### GET /api/v1/applications/{application_id}/documents/{document_type}
+Get specific document.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**URL Parameters:**
+- `document_type`: enum: `research_report|optimized_resume|cover_letter`
+
+**Response (200):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "application_id": "456e7890-e89b-12d3-a456-426614174000",
+  "document_type": "research_report", 
+  "content": "# Research Report\n\n## Job Analysis\n...",
+  "created_at": "2025-07-01T10:30:00Z",
+  "updated_at": "2025-07-01T10:30:00Z"
+}
+```
+
+**Errors:**
+- `404` - Document not found or application not owned by user
+
+#### PUT /api/v1/applications/{application_id}/documents/{document_type}
+Update document content (user editing).
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:**
+```json
+{
+  "content": "# Updated Research Report\n\n## Job Analysis\nUpdated content..."
+}
+```
+
+**Response (200):** Updated document object
+
+**Validation:**
+- `content`: Required, minimum 10 characters
+
+**Errors:**
+- `404` - Document or application not found
+- `400` - Validation errors
+
+---
+
+## 🤖 AI Processing API
+
+### Processing Status Model
+```json
+{
+  "application_id": "123e4567-e89b-12d3-a456-426614174000",
+  "current_phase": "research",
+  "status": "processing",
+  "progress": 0.6,
+  "estimated_completion": "2025-07-01T10:35:00Z",
+  "error_message": null
+}
+```
+
+### Processing Endpoints
+
+#### POST /api/v1/processing/applications/{application_id}/research
+Start research phase processing.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (202):**
+```json
+{
+  "message": "Research phase started",
+  "application_id": "123e4567-e89b-12d3-a456-426614174000",
+  "estimated_completion": "2025-07-01T10:35:00Z"
+}
+```
+
+**Errors:**
+- `404` - Application not found
+- `409` - Research already completed
+- `400` - Application not in correct state
+
+#### POST /api/v1/processing/applications/{application_id}/resume
+Start resume optimization phase.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Requirements:** Research phase must be completed
+
+**Response (202):**
+```json
+{
+  "message": "Resume optimization started", 
+  "application_id": "123e4567-e89b-12d3-a456-426614174000",
+  "estimated_completion": "2025-07-01T11:05:00Z"
+}
+```
+
+**Errors:**
+- `404` - Application not found
+- `409` - Resume already optimized  
+- `412` - Research phase not completed
+
+#### POST /api/v1/processing/applications/{application_id}/cover-letter
+Start cover letter generation phase.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:**
+```json
+{
+  "additional_context": "I'm particularly interested in their AI/ML projects. I have experience with TensorFlow and PyTorch."
+}
+```
+
+**Requirements:** Resume optimization must be completed
+
+**Response (202):**
+```json
+{
+  "message": "Cover letter generation started",
+  "application_id": "123e4567-e89b-12d3-a456-426614174000", 
+  "estimated_completion": "2025-07-01T11:15:00Z"
+}
+```
+
+**Errors:**
+- `404` - Application not found
+- `409` - Cover letter already generated
+- `412` - Resume optimization not completed
+
+#### GET /api/v1/processing/applications/{application_id}/status
+Get current processing status.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):**
+```json
+{
+  "application_id": "123e4567-e89b-12d3-a456-426614174000",
+  "current_phase": "resume",
+  "status": "completed",
+  "progress": 1.0,
+  "completed_at": "2025-07-01T11:05:00Z",
+  "error_message": null
+}
+```
+
+**Status Values:**
+- `idle` - No processing active
+- `processing` - AI generation in progress
+- `completed` - Phase completed successfully  
+- `failed` - Processing failed with error
+
+---
+
+## 👤 User Resumes API
+
+### Resume Model
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "name": "Technical Resume",
+  "content": "# John Doe\n\n## Technical Skills\n...",
+  "focus_area": "software_development",
+  "is_primary": true,
+  "created_at": "2025-07-01T09:00:00Z",
+  "updated_at": "2025-07-01T09:00:00Z"
+}
+```
+
+### Resume Endpoints
+
+#### GET /api/v1/resumes
+Get user's resume library.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):**
+```json
+{
+  "resumes": [
+    {
+      "id": "123e4567-e89b-12d3-a456-426614174000",
+      "name": "Technical Resume",
+      "focus_area": "software_development", 
+      "is_primary": true,
+      "created_at": "2025-07-01T09:00:00Z",
+      "updated_at": "2025-07-01T09:00:00Z"
+    }
+  ]
+}
+```
+
+#### POST /api/v1/resumes
+Upload new resume to library.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:**
+```json
+{
+  "name": "Management Resume",
+  "content": "# John Doe\n\n## Leadership Experience\n...",
+  "focus_area": "management",
+  "is_primary": false
+}
+```
+
+**Response (201):** Created resume object
+
+**Validation:**
+- `name`: Required, 1-255 characters
+- `content`: Required, minimum 100 characters
+- `focus_area`: Optional, enum: `software_development|management|data_science|consulting|other`
+
+#### GET /api/v1/resumes/{resume_id}
+Get specific resume details.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (200):** Full resume object
+
+#### PUT /api/v1/resumes/{resume_id}
+Update resume content.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Request:** Same as POST
+
+**Response (200):** Updated resume object
+
+#### DELETE /api/v1/resumes/{resume_id}
+Delete resume from library.
+
+**Headers:** `Authorization: Bearer <token>`
+
+**Response (204):** No content
+
+**Errors:**
+- `409` - Cannot delete primary resume if it's the only one
+
+---
+
+## 🚨 Error Handling
+
+### Standard Error Response
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": {
+      "company_name": ["This field is required"],
+      "job_description": ["Must be at least 50 characters"]
+    }
+  },
+  "timestamp": "2025-07-01T10:00:00Z",
+  "path": "/api/v1/applications"
+}
+```
+
+### HTTP Status Codes
+- `200` - Success
+- `201` - Created successfully
+- `202` - Accepted (async processing started)
+- `204` - No content (successful deletion)
+- `400` - Bad request (validation errors)
+- `401` - Unauthorized (invalid/missing token)
+- `403` - Forbidden (valid token, insufficient permissions)
+- `404` - Not found
+- `409` - Conflict (duplicate email, invalid state transition)
+- `412` - Precondition failed (phase not completed)
+- `422` - Unprocessable entity (semantic errors)
+- `500` - Internal server error
+
+### Error Codes
+- `VALIDATION_ERROR` - Input validation failed
+- `AUTHENTICATION_ERROR` - Invalid credentials
+- `AUTHORIZATION_ERROR` - Insufficient permissions  
+- `NOT_FOUND` - Resource not found
+- `DUPLICATE_RESOURCE` - Resource already exists
+- `INVALID_STATE` - Operation not valid for current state
+- `EXTERNAL_API_ERROR` - Claude/OpenAI API error
+- `PROCESSING_ERROR` - AI processing failed
+
+---
+
+## 🔧 Development Notes
+
+### Rate Limiting (Future)
+- Not implemented in MVP
+- Will be added in Phase 2 for SaaS
+
+### Pagination
+- Default limit: 50
+- Maximum limit: 100  
+- Use `offset` for pagination
+
+### Content Validation
+- Job description: 50-10000 characters
+- Resume content: 100-50000 characters
+- Names: 1-255 characters
+- URLs: Valid HTTP/HTTPS format
+
+### Background Processing
+- AI operations run asynchronously
+- Use `/processing/applications/{id}/status` to check progress
+- Frontend should poll every 2-3 seconds during processing
+
+---
+
+*This API specification covers all endpoints required for MVP implementation. Use the OpenAPI documentation at `/docs` for interactive testing during development.*

docs/database_design.md

@@ -0,0 +1,651 @@
+# JobForge MVP - Database Design & Schema
+
+**Version:** 1.0.0 MVP  
+**Database:** PostgreSQL 16 with pgvector  
+**Target Audience:** Backend Developers  
+**Last Updated:** July 2025
+
+---
+
+## 🎯 Database Overview
+
+### 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)
+
+### 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
+
+---
+
+## 📊 Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    USERS ||--o{ APPLICATIONS : creates
+    USERS ||--o{ USER_RESUMES : owns
+    APPLICATIONS ||--o{ DOCUMENTS : contains
+    DOCUMENTS ||--o| DOCUMENT_EMBEDDINGS : has_embedding
+    
+    USERS {
+        uuid id PK
+        varchar email UK
+        varchar password_hash
+        varchar full_name
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    APPLICATIONS {
+        uuid id PK
+        uuid user_id FK
+        varchar name
+        varchar company_name
+        varchar role_title
+        text job_url
+        text job_description
+        varchar location
+        varchar priority_level
+        varchar status
+        boolean research_completed
+        boolean resume_optimized
+        boolean cover_letter_generated
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    DOCUMENTS {
+        uuid id PK
+        uuid application_id FK
+        varchar document_type
+        text content
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    USER_RESUMES {
+        uuid id PK
+        uuid user_id FK
+        varchar name
+        text content
+        varchar focus_area
+        boolean is_primary
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    DOCUMENT_EMBEDDINGS {
+        uuid id PK
+        uuid document_id FK
+        vector embedding
+        timestamp created_at
+    }
+```
+
+---
+
+## 🗄️ Complete Database Schema
+
+### Database Initialization
+```sql
+-- Enable required extensions
+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'
+);
+CREATE TYPE document_type_enum AS ENUM (
+    'research_report', 
+    'optimized_resume', 
+    'cover_letter'
+);
+CREATE TYPE focus_area_type AS ENUM (
+    'software_development',
+    'data_science', 
+    'management',
+    'consulting',
+    'other'
+);
+```
+
+### Core Tables
+
+#### Users Table
+```sql
+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 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)
+);
+
+-- Indexes
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_created_at ON users(created_at);
+
+-- Row Level Security
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own record
+CREATE POLICY users_own_data ON users
+    FOR ALL 
+    USING (id = current_setting('app.current_user_id')::UUID);
+```
+
+#### Applications Table
+```sql
+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,
+    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(),
+    
+    -- Constraints
+    CONSTRAINT job_description_min_length CHECK (LENGTH(job_description) >= 50),
+    CONSTRAINT company_name_not_empty CHECK (LENGTH(TRIM(company_name)) > 0),
+    CONSTRAINT role_title_not_empty CHECK (LENGTH(TRIM(role_title)) > 0),
+    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);
+
+-- Full text search index for job descriptions
+CREATE INDEX idx_applications_job_description_fts 
+ON applications USING gin(to_tsvector('english', job_description));
+
+-- Row Level Security
+ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY applications_user_access ON applications
+    FOR ALL
+    USING (user_id = current_setting('app.current_user_id')::UUID);
+```
+
+#### Documents Table
+```sql
+CREATE TABLE documents (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    document_type document_type_enum NOT NULL,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT content_min_length CHECK (LENGTH(content) >= 10),
+    CONSTRAINT unique_document_per_application UNIQUE (application_id, document_type)
+);
+
+-- Indexes
+CREATE INDEX idx_documents_application_id ON documents(application_id);
+CREATE INDEX idx_documents_type ON documents(document_type);
+CREATE INDEX idx_documents_updated_at ON documents(updated_at);
+
+-- Full text search index for document content
+CREATE INDEX idx_documents_content_fts 
+ON documents USING gin(to_tsvector('english', content));
+
+-- Row Level Security
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY documents_user_access ON documents
+    FOR ALL
+    USING (
+        application_id IN (
+            SELECT id FROM applications 
+            WHERE user_id = current_setting('app.current_user_id')::UUID
+        )
+    );
+```
+
+#### User Resumes Table
+```sql
+CREATE TABLE user_resumes (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(255) NOT NULL,
+    content TEXT NOT NULL,
+    focus_area focus_area_type DEFAULT 'other',
+    is_primary BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT resume_name_not_empty CHECK (LENGTH(TRIM(name)) > 0),
+    CONSTRAINT resume_content_min_length CHECK (LENGTH(content) >= 100),
+    
+    -- Only one primary resume per user
+    CONSTRAINT unique_primary_resume UNIQUE (user_id, is_primary) 
+    DEFERRABLE INITIALLY DEFERRED
+);
+
+-- Indexes
+CREATE INDEX idx_user_resumes_user_id ON user_resumes(user_id);
+CREATE INDEX idx_user_resumes_focus_area ON user_resumes(focus_area);
+CREATE INDEX idx_user_resumes_is_primary ON user_resumes(is_primary);
+
+-- Full text search index for resume content
+CREATE INDEX idx_user_resumes_content_fts 
+ON user_resumes USING gin(to_tsvector('english', content));
+
+-- Row Level Security
+ALTER TABLE user_resumes ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY user_resumes_access ON user_resumes
+    FOR ALL
+    USING (user_id = current_setting('app.current_user_id')::UUID);
+```
+
+#### Document Embeddings Table (AI Features)
+```sql
+CREATE TABLE document_embeddings (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    embedding vector(1536),  -- OpenAI text-embedding-3-large dimension
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT unique_embedding_per_document UNIQUE (document_id)
+);
+
+-- Vector similarity index
+CREATE INDEX idx_document_embeddings_vector 
+ON document_embeddings USING ivfflat (embedding vector_cosine_ops)
+WITH (lists = 100);
+
+-- Regular indexes
+CREATE INDEX idx_document_embeddings_document_id ON document_embeddings(document_id);
+
+-- Row Level Security
+ALTER TABLE document_embeddings ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY document_embeddings_access ON document_embeddings
+    FOR ALL
+    USING (
+        document_id IN (
+            SELECT d.id FROM documents d
+            JOIN applications a ON d.application_id = a.id
+            WHERE a.user_id = current_setting('app.current_user_id')::UUID
+        )
+    );
+```
+
+---
+
+## 🔒 Security Policies
+
+### Row Level Security Overview
+All tables with user data have RLS enabled to ensure complete data isolation:
+
+```sql
+-- Function to get current user ID from session
+CREATE OR REPLACE FUNCTION get_current_user_id()
+RETURNS UUID AS $$
+BEGIN
+    RETURN current_setting('app.current_user_id')::UUID;
+EXCEPTION
+    WHEN others THEN
+        RETURN NULL;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Helper function to check if user owns application
+CREATE OR REPLACE FUNCTION user_owns_application(app_id UUID)
+RETURNS BOOLEAN AS $$
+BEGIN
+    RETURN EXISTS (
+        SELECT 1 FROM applications 
+        WHERE id = app_id 
+        AND user_id = get_current_user_id()
+    );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+```
+
+### Setting User Context
+Backend must set user context for each request:
+
+```python
+# In FastAPI dependency
+async def set_user_context(user: User = Depends(get_current_user)):
+    async with get_db_connection() as conn:
+        await conn.execute(
+            "SET LOCAL app.current_user_id = %s", 
+            str(user.id)
+        )
+    return user
+```
+
+---
+
+## 🚀 Database Functions
+
+### Trigger Functions
+```sql
+-- Update timestamp trigger function
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply to all tables with updated_at
+CREATE TRIGGER update_users_updated_at
+    BEFORE UPDATE ON users
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_applications_updated_at
+    BEFORE UPDATE ON applications  
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_documents_updated_at
+    BEFORE UPDATE ON documents
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TRIGGER update_user_resumes_updated_at
+    BEFORE UPDATE ON user_resumes
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+```
+
+### Business Logic Functions
+```sql
+-- Generate application name
+CREATE OR REPLACE FUNCTION generate_application_name(
+    p_company_name VARCHAR,
+    p_role_title VARCHAR
+) RETURNS VARCHAR AS $$
+DECLARE
+    clean_company VARCHAR;
+    clean_role VARCHAR;
+    date_suffix VARCHAR;
+BEGIN
+    -- Clean and normalize names
+    clean_company := LOWER(REGEXP_REPLACE(p_company_name, '[^a-zA-Z0-9]', '_', 'g'));
+    clean_role := LOWER(REGEXP_REPLACE(p_role_title, '[^a-zA-Z0-9]', '_', 'g'));
+    date_suffix := TO_CHAR(NOW(), 'YYYY_MM_DD');
+    
+    RETURN clean_company || '_' || clean_role || '_' || date_suffix;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Update application phases trigger
+CREATE OR REPLACE FUNCTION update_application_phases()
+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;
+    END IF;
+    
+    RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER documents_update_phases
+    AFTER INSERT OR UPDATE OR DELETE ON documents
+    FOR EACH ROW EXECUTE FUNCTION update_application_phases();
+```
+
+---
+
+## 📈 Performance Optimization
+
+### Query Optimization
+```sql
+-- Most common query patterns with optimized indexes
+
+-- 1. Get user applications (paginated)
+-- Index: idx_applications_user_id, idx_applications_created_at
+SELECT * FROM applications 
+WHERE user_id = $1 
+ORDER BY created_at DESC 
+LIMIT $2 OFFSET $3;
+
+-- 2. Get application with documents
+-- Index: idx_documents_application_id
+SELECT a.*, d.document_type, d.content
+FROM applications a
+LEFT JOIN documents d ON a.id = d.application_id
+WHERE a.id = $1 AND a.user_id = $2;
+
+-- 3. Search applications by company/role
+-- Index: idx_applications_company_name, full-text search
+SELECT * FROM applications
+WHERE user_id = $1
+AND (
+    company_name ILIKE $2 
+    OR role_title ILIKE $3
+    OR to_tsvector('english', job_description) @@ plainto_tsquery('english', $4)
+)
+ORDER BY created_at DESC;
+```
+
+### Connection Pooling
+```python
+# SQLAlchemy async engine configuration
+engine = create_async_engine(
+    DATABASE_URL,
+    pool_size=20,          # Connection pool size
+    max_overflow=30,       # Additional connections beyond pool_size
+    pool_pre_ping=True,    # Validate connections before use
+    pool_recycle=3600,     # Recycle connections every hour
+    echo=False             # Disable SQL logging in production
+)
+```
+
+---
+
+## 🧪 Test Data Setup
+
+### Development Seed Data
+```sql
+-- Insert test user (password: "testpass123")
+INSERT INTO users (id, email, password_hash, full_name) VALUES (
+    '123e4567-e89b-12d3-a456-426614174000',
+    'test@example.com', 
+    '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewgdyN8yF5V4M2kq',
+    'Test User'
+);
+
+-- Insert test resume
+INSERT INTO user_resumes (user_id, name, content, focus_area, is_primary) VALUES (
+    '123e4567-e89b-12d3-a456-426614174000',
+    'Software Developer Resume',
+    '# Test User\n\n## Experience\n\nSoftware Developer at Tech Corp...',
+    'software_development',
+    true
+);
+
+-- Insert test application
+INSERT INTO applications (
+    user_id, name, company_name, role_title, 
+    job_description, status, research_completed
+) 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
+);
+```
+
+---
+
+## 🔄 Database Migrations (Future)
+
+### Migration Strategy for Phase 2
+When adding Alembic migrations:
+
+```python
+# alembic/env.py configuration for RLS
+from sqlalchemy import text
+
+def run_migrations_online():
+    # Set up RLS context for migrations
+    with engine.connect() as connection:
+        connection.execute(text("SET row_security = off"))
+        
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            compare_server_default=True
+        )
+        
+        with context.begin_transaction():
+            context.run_migrations()
+```
+
+### Planned Schema Changes
+- **Usage tracking tables** for SaaS billing
+- **Subscription management** tables  
+- **Audit log** tables for compliance
+- **Performance metrics** tables
+- **Additional indexes** based on production usage
+
+---
+
+## 🛠️ Database Maintenance
+
+### Regular Maintenance Tasks
+```sql
+-- Vacuum and analyze (run weekly)
+VACUUM ANALYZE;
+
+-- Update table statistics
+ANALYZE applications;
+ANALYZE documents;
+ANALYZE user_resumes;
+
+-- Check index usage
+SELECT schemaname, tablename, indexname, idx_tup_read, idx_tup_fetch
+FROM pg_stat_user_indexes
+ORDER BY idx_tup_read DESC;
+
+-- Monitor vector index performance
+SELECT * FROM pg_stat_user_indexes 
+WHERE indexname LIKE '%vector%';
+```
+
+### Backup Strategy
+```bash
+# Daily backup script
+pg_dump -h localhost -U jobforge_user -d jobforge_mvp \
+    --clean --if-exists --verbose \
+    > backup_$(date +%Y%m%d).sql
+
+# Restore from backup
+psql -h localhost -U jobforge_user -d jobforge_mvp < backup_20250701.sql
+```
+
+---
+
+## 📊 Monitoring Queries
+
+### Performance Monitoring
+```sql
+-- Slow queries
+SELECT query, mean_time, calls, total_time
+FROM pg_stat_statements
+WHERE mean_time > 100  -- queries slower than 100ms
+ORDER BY mean_time DESC;
+
+-- Table sizes
+SELECT 
+    schemaname,
+    tablename,
+    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size,
+    pg_total_relation_size(schemaname||'.'||tablename) as size_bytes
+FROM pg_tables
+WHERE schemaname = 'public'
+ORDER BY size_bytes DESC;
+
+-- Connection counts
+SELECT state, count(*) 
+FROM pg_stat_activity 
+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.*

docs/development_setup.md

@@ -0,0 +1,446 @@
+# 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.*

docs/git_branch_strategy.md

@@ -0,0 +1,631 @@
+# 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.*

docs/job_forge_architecture.md

@@ -1,833 +0,0 @@
-# JobForge - Architecture Guide
-
-**Version:** 1.0.0  
-**Status:** Production-Ready Implementation  
-**Date:** July 2025  
-**Target Market:** Canadian Job Market Applications  
-**Tagline:** "Forge Your Path to Success"
-
----
-
-## 📋 Executive Summary
-
-### Project Vision
-JobForge is a comprehensive, AI-powered job application management system that streamlines the entire application process through intelligent automation, multi-resume optimization, and authentic voice preservation for professional job seekers in the Canadian market.
-
-### Core Objectives
-- **Workflow Automation**: 3-phase intelligent application pipeline (Research → Resume → Cover Letter)
-- **Multi-Resume Intelligence**: Leverage multiple resume versions as focused expertise lenses
-- **Authentic Voice Preservation**: Maintain candidate's proven successful writing patterns
-- **Canadian Market Focus**: Optimize for Canadian business culture and application standards
-- **Local File Management**: Complete control over sensitive career documents
-- **Scalable Architecture**: Support for high-volume job application campaigns
-
-### Business Value Proposition
-- **40% Time Reduction**: Automated research and document generation
-- **Higher Success Rates**: Strategic positioning based on comprehensive analysis
-- **Consistent Quality**: Standardized excellence across all applications
-- **Document Security**: Local storage with full user control
-- **Career Intelligence**: Build knowledge base from successful applications
-
----
-
-## 🏗️ High-Level Architecture
-
-### System Overview
-```mermaid
-graph TB
-    subgraph "User Interface Layer"
-        A[Streamlit Web UI]
-        B[Configuration Panel]
-        C[File Management UI]
-        D[Workflow Interface]
-    end
-    
-    subgraph "Application Core"
-        E[Application Engine]
-        F[Phase Orchestrator]
-        G[State Manager]
-        H[File Controller]
-    end
-    
-    subgraph "AI Processing Layer"
-        I[Research Agent]
-        J[Resume Optimizer]
-        K[Cover Letter Generator]
-        L[Claude API Client]
-    end
-    
-    subgraph "Data Management"
-        M[Resume Repository]
-        N[Reference Database]
-        O[Application Store]
-        P[Status Tracker]
-    end
-    
-    subgraph "Storage Layer"
-        Q[Local File System]
-        R[Project Structure]
-        S[Document Templates]
-    end
-    
-    subgraph "External Services"
-        T[Claude AI API]
-        U[Web Search APIs]
-        V[Company Intelligence]
-    end
-    
-    A --> E
-    B --> H
-    C --> H
-    D --> F
-    E --> I
-    E --> J
-    E --> K
-    F --> G
-    I --> L
-    J --> L
-    K --> L
-    L --> T
-    M --> Q
-    N --> Q
-    O --> Q
-    P --> Q
-    H --> R
-    I --> U
-    I --> V
-```
-
-### Architecture Principles
-
-#### **1. Domain-Driven Design**
-- Clear separation between job application domain logic and technical infrastructure
-- Rich domain models representing real-world career management concepts
-- Business rules encapsulated within domain entities
-
-#### **2. Event-Driven Workflow**
-- Each phase triggers the next through well-defined events
-- State transitions logged for auditability and recovery
-- Asynchronous processing with real-time UI updates
-
-#### **3. Multi-Source Intelligence**
-- Resume portfolio treated as complementary expertise views
-- Reference database provides voice pattern templates
-- Company research aggregated from multiple sources
-
-#### **4. Security-First Design**
-- All sensitive career data stored locally
-- No cloud storage of personal information
-- API keys managed through secure environment variables
-
----
-
-## 🔧 Core Components
-
-### **Application Engine**
-```python
-class JobApplicationEngine:
-    """Central orchestrator for the entire application workflow"""
-    
-    def __init__(self, config: EngineConfig, file_manager: FileManager):
-        self.config = config
-        self.file_manager = file_manager
-        self.phase_orchestrator = PhaseOrchestrator()
-        self.state_manager = StateManager()
-    
-    # Core workflow methods
-    def create_application(self, job_data: JobData) -> Application
-    def execute_research_phase(self, app_id: str) -> ResearchReport
-    def optimize_resume(self, app_id: str, research: ResearchReport) -> OptimizedResume
-    def generate_cover_letter(self, app_id: str, context: ApplicationContext) -> CoverLetter
-    
-    # Management operations
-    def list_applications(self, status_filter: str = None) -> List[Application]
-    def update_application_status(self, app_id: str, status: ApplicationStatus) -> None
-    def export_application(self, app_id: str, format: ExportFormat) -> str
-```
-
-**Responsibilities:**
-- Coordinate all application lifecycle operations
-- Manage state transitions between phases
-- Integrate with AI processing agents
-- Handle file system operations through delegates
-
-### **Phase Orchestrator**
-```python
-class PhaseOrchestrator:
-    """Manages the 3-phase workflow execution and state transitions"""
-    
-    class Phases(Enum):
-        INPUT = "input"
-        RESEARCH = "research" 
-        RESUME = "resume"
-        COVER_LETTER = "cover_letter"
-        COMPLETE = "complete"
-    
-    def execute_phase(self, phase: Phases, context: PhaseContext) -> PhaseResult
-    def can_advance_to(self, target_phase: Phases, current_state: ApplicationState) -> bool
-    def get_phase_requirements(self, phase: Phases) -> List[Requirement]
-    
-    # Phase-specific execution
-    async def execute_research(self, job_data: JobData, resume_portfolio: List[Resume]) -> ResearchReport
-    async def execute_resume_optimization(self, research: ResearchReport, portfolio: ResumePortfolio) -> OptimizedResume
-    async def execute_cover_letter_generation(self, context: ApplicationContext) -> CoverLetter
-```
-
-**Design Features:**
-- State machine implementation for workflow control
-- Async execution with progress callbacks
-- Dependency validation between phases
-- Rollback capability for failed phases
-
-### **AI Processing Agents**
-
-#### **Research Agent**
-```python
-class ResearchAgent:
-    """Phase 1: Comprehensive job description analysis and strategic positioning"""
-    
-    def __init__(self, claude_client: ClaudeAPIClient, web_search: WebSearchClient):
-        self.claude = claude_client
-        self.web_search = web_search
-    
-    async def analyze_job_description(self, job_desc: str) -> JobAnalysis:
-        """Extract and categorize job requirements, company info, and keywords"""
-        
-    async def assess_candidate_fit(self, job_analysis: JobAnalysis, resume_portfolio: ResumePortfolio) -> FitAssessment:
-        """Multi-resume skills assessment with transferability analysis"""
-        
-    async def research_company_intelligence(self, company_name: str) -> CompanyIntelligence:
-        """Gather company culture, recent news, and strategic insights"""
-        
-    async def generate_strategic_positioning(self, context: ResearchContext) -> StrategicPositioning:
-        """Determine optimal candidate positioning and competitive advantages"""
-```
-
-#### **Resume Optimizer**
-```python
-class ResumeOptimizer:
-    """Phase 2: Multi-resume synthesis and strategic optimization"""
-    
-    def __init__(self, claude_client: ClaudeAPIClient, config: OptimizationConfig):
-        self.claude = claude_client
-        self.config = config  # 600-word limit, formatting rules, etc.
-    
-    async def synthesize_resume_portfolio(self, portfolio: ResumePortfolio, research: ResearchReport) -> SynthesizedContent:
-        """Merge insights from multiple resume versions"""
-        
-    async def optimize_for_job(self, content: SynthesizedContent, positioning: StrategicPositioning) -> OptimizedResume:
-        """Create targeted resume within word limits"""
-        
-    def validate_optimization(self, resume: OptimizedResume) -> OptimizationReport:
-        """Ensure word count, keyword density, and strategic alignment"""
-```
-
-#### **Cover Letter Generator**
-```python
-class CoverLetterGenerator:
-    """Phase 3: Authentic voice preservation and company-specific customization"""
-    
-    def __init__(self, claude_client: ClaudeAPIClient, reference_db: ReferenceDatabase):
-        self.claude = claude_client
-        self.reference_db = reference_db
-    
-    async def analyze_voice_patterns(self, selected_references: List[CoverLetterReference]) -> VoiceProfile:
-        """Extract authentic writing style, tone, and structural patterns"""
-        
-    async def generate_cover_letter(self, context: CoverLetterContext, voice_profile: VoiceProfile) -> CoverLetter:
-        """Create authentic cover letter using proven voice patterns"""
-        
-    def validate_authenticity(self, cover_letter: CoverLetter, voice_profile: VoiceProfile) -> AuthenticityScore:
-        """Ensure generated content matches authentic voice patterns"""
-```
-
-### **Data Models**
-```python
-class Application(BaseModel):
-    """Core application entity with full lifecycle management"""
-    id: str
-    name: str  # company_role_YYYY_MM_DD format
-    status: ApplicationStatus
-    created_at: datetime
-    updated_at: datetime
-    
-    # Job information
-    job_data: JobData
-    company_info: CompanyInfo
-    
-    # Phase results
-    research_report: Optional[ResearchReport] = None
-    optimized_resume: Optional[OptimizedResume] = None
-    cover_letter: Optional[CoverLetter] = None
-    
-    # Metadata
-    priority_level: PriorityLevel
-    application_deadline: Optional[date] = None
-    
-    # Business logic
-    @property
-    def completion_percentage(self) -> float
-    def can_advance_to_phase(self, phase: PhaseOrchestrator.Phases) -> bool
-    def export_to_format(self, format: ExportFormat) -> str
-
-class ResumePortfolio(BaseModel):
-    """Collection of focused resume versions representing different expertise areas"""
-    resumes: List[Resume]
-    
-    def get_technical_focused(self) -> List[Resume]
-    def get_management_focused(self) -> List[Resume] 
-    def get_industry_specific(self, industry: str) -> List[Resume]
-    def synthesize_skills(self) -> SkillMatrix
-
-class JobData(BaseModel):
-    """Comprehensive job posting information"""
-    job_url: Optional[str] = None
-    job_description: str
-    company_name: str
-    role_title: str
-    location: str
-    priority_level: PriorityLevel
-    how_found: str
-    application_deadline: Optional[date] = None
-    
-    # Additional context
-    specific_aspects: Optional[str] = None
-    company_insights: Optional[str] = None
-    special_considerations: Optional[str] = None
-```
-
----
-
-## 📊 Data Flow Architecture
-
-### Application Creation Flow
-```mermaid
-sequenceDiagram
-    participant UI as Streamlit UI
-    participant Engine as Application Engine
-    participant FileManager as File Manager
-    participant Storage as Local Storage
-    
-    UI->>Engine: create_application(job_data)
-    Engine->>Engine: validate_job_data()
-    Engine->>Engine: generate_application_name()
-    Engine->>FileManager: create_application_folder()
-    FileManager->>Storage: mkdir(company_role_date)
-    FileManager->>Storage: save(user_inputs.json)
-    FileManager->>Storage: save(original_job_description.md)
-    FileManager->>Storage: save(application_status.json)
-    Engine-->>UI: Application(id, status=created)
-```
-
-### 3-Phase Workflow Execution
-```mermaid
-flowchart TD
-    A[Application Created] --> B[Phase 1: Research]
-    B --> C{Research Complete?}
-    C -->|Yes| D[Phase 2: Resume]
-    C -->|No| E[Research Error]
-    D --> F{Resume Complete?}
-    F -->|Yes| G[Phase 3: Cover Letter]
-    F -->|No| H[Resume Error]
-    G --> I{Cover Letter Complete?}
-    I -->|Yes| J[Application Complete]
-    I -->|No| K[Cover Letter Error]
-    
-    E --> L[Log Error & Retry]
-    H --> L
-    K --> L
-    L --> M[Manual Intervention]
-    
-    subgraph "Phase 1 Details"
-        B1[Job Analysis]
-        B2[Multi-Resume Assessment]
-        B3[Company Research]
-        B4[Strategic Positioning]
-        B --> B1 --> B2 --> B3 --> B4 --> C
-    end
-    
-    subgraph "Phase 2 Details"
-        D1[Portfolio Synthesis]
-        D2[Content Optimization]
-        D3[Word Count Management]
-        D4[Strategic Alignment]
-        D --> D1 --> D2 --> D3 --> D4 --> F
-    end
-    
-    subgraph "Phase 3 Details"
-        G1[Voice Analysis]
-        G2[Content Generation]
-        G3[Authenticity Validation]
-        G4[Company Customization]
-        G --> G1 --> G2 --> G3 --> G4 --> I
-    end
-```
-
-### File Management Architecture
-```mermaid
-graph TB
-    subgraph "Project Root"
-        A[job-application-engine/]
-    end
-    
-    subgraph "User Data"
-        B[user_data/resumes/]
-        C[user_data/cover_letter_references/selected/]
-        D[user_data/cover_letter_references/other/]
-    end
-    
-    subgraph "Applications"
-        E[applications/company_role_date/]
-        F[├── original_job_description.md]
-        G[├── research_report.md]
-        H[├── optimized_resume.md]
-        I[├── cover_letter.md]
-        J[├── user_inputs.json]
-        K[└── application_status.json]
-    end
-    
-    subgraph "Configuration"
-        L[config/]
-        M[├── engine_config.yaml]
-        N[├── claude_api_config.json]
-        O[└── templates/]
-    end
-    
-    A --> B
-    A --> C
-    A --> D
-    A --> E
-    A --> L
-    E --> F
-    E --> G
-    E --> H
-    E --> I
-    E --> J
-    E --> K
-```
-
----
-
-## 🗂️ Project Structure
-
-### Directory Layout
-```
-job-application-engine/
-├── app.py                           # Streamlit main application
-├── requirements.txt                 # Python dependencies
-├── config/
-│   ├── engine_config.yaml          # Engine configuration
-│   ├── claude_api_config.json      # API configuration
-│   └── templates/                   # Document templates
-│       ├── research_template.md
-│       ├── resume_template.md
-│       └── cover_letter_template.md
-├── src/                            # Source code
-│   ├── __init__.py
-│   ├── engine/                     # Core engine
-│   │   ├── __init__.py
-│   │   ├── application_engine.py   # Main engine class
-│   │   ├── phase_orchestrator.py   # Workflow management
-│   │   └── state_manager.py        # State tracking
-│   ├── agents/                     # AI processing agents
-│   │   ├── __init__.py
-│   │   ├── research_agent.py       # Phase 1: Research
-│   │   ├── resume_optimizer.py     # Phase 2: Resume
-│   │   ├── cover_letter_generator.py # Phase 3: Cover Letter
-│   │   └── claude_client.py        # Claude API integration
-│   ├── models/                     # Data models
-│   │   ├── __init__.py
-│   │   ├── application.py          # Application entity
-│   │   ├── job_data.py            # Job information
-│   │   ├── resume.py              # Resume models
-│   │   └── results.py             # Phase results
-│   ├── storage/                    # Storage management
-│   │   ├── __init__.py
-│   │   ├── file_manager.py        # File operations
-│   │   ├── application_store.py   # Application persistence
-│   │   └── reference_database.py  # Cover letter references
-│   ├── ui/                        # User interface
-│   │   ├── __init__.py
-│   │   ├── streamlit_app.py       # Streamlit components
-│   │   ├── workflow_ui.py         # Workflow interface
-│   │   └── file_management_ui.py  # File management
-│   └── utils/                     # Utilities
-│       ├── __init__.py
-│       ├── validators.py          # Input validation
-│       ├── formatters.py          # Output formatting
-│       └── helpers.py             # Helper functions
-├── user_data/                     # User's career documents
-│   ├── resumes/
-│   │   ├── resume_complete.md
-│   │   ├── resume_technical.md
-│   │   └── resume_management.md
-│   └── cover_letter_references/
-│       ├── selected/              # Tagged as references
-│       │   ├── cover_letter_tech.md
-│       │   └── cover_letter_consulting.md
-│       └── other/                 # Available references
-│           └── cover_letter_finance.md
-├── applications/                  # Generated applications
-│   ├── dillon_consulting_data_analyst_2025_07_22/
-│   └── shopify_senior_developer_2025_07_23/
-├── tests/                        # Test suite
-│   ├── unit/
-│   ├── integration/
-│   └── fixtures/
-├── docs/                         # Documentation
-│   ├── architecture.md
-│   ├── user_guide.md
-│   └── api_reference.md
-└── scripts/                      # Utility scripts
-    ├── setup_project.py
-    └── backup_applications.py
-```
-
-### Module Responsibilities
-
-| Module | Purpose | Key Classes | Dependencies |
-|--------|---------|-------------|--------------|
-| `engine/` | Core workflow orchestration | `ApplicationEngine`, `PhaseOrchestrator` | `agents/`, `models/` |
-| `agents/` | AI processing logic | `ResearchAgent`, `ResumeOptimizer`, `CoverLetterGenerator` | `models/`, `utils/` |
-| `models/` | Data structures and business logic | `Application`, `JobData`, `Resume`, `ResumePortfolio` | `pydantic` |
-| `storage/` | File system operations | `FileManager`, `ApplicationStore`, `ReferenceDatabase` | `pathlib`, `json` |
-| `ui/` | User interface components | `StreamlitApp`, `WorkflowUI`, `FileManagementUI` | `streamlit` |
-| `utils/` | Cross-cutting concerns | `Validators`, `Formatters`, `Helpers` | Various |
-
----
-
-## 🔌 Extensibility Architecture
-
-### Plugin System Design
-```python
-class EnginePlugin(ABC):
-    """Base plugin interface for extending engine functionality"""
-    
-    def before_phase_execution(self, phase: PhaseOrchestrator.Phases, context: PhaseContext) -> PhaseContext:
-        """Modify context before phase execution"""
-        return context
-    
-    def after_phase_completion(self, phase: PhaseOrchestrator.Phases, result: PhaseResult) -> PhaseResult:
-        """Process result after phase completion"""
-        return result
-    
-    def on_application_created(self, application: Application) -> None:
-        """React to new application creation"""
-        pass
-
-class MetricsPlugin(EnginePlugin):
-    """Collect application performance metrics"""
-    
-    def after_phase_completion(self, phase: PhaseOrchestrator.Phases, result: PhaseResult) -> PhaseResult:
-        self.record_phase_metrics(phase, result.execution_time, result.success)
-        return result
-
-class BackupPlugin(EnginePlugin):
-    """Automatic backup of application data"""
-    
-    def on_application_created(self, application: Application) -> None:
-        self.backup_application(application)
-```
-
-### Configuration System
-```python
-@dataclass
-class EngineConfig:
-    # Core settings
-    claude_api_key: str
-    base_output_directory: str = "./applications"
-    max_concurrent_phases: int = 1
-    
-    # AI processing
-    research_model: str = "claude-sonnet-4-20250514"
-    resume_word_limit: int = 600
-    cover_letter_word_range: tuple = (350, 450)
-    
-    # File management
-    auto_backup_enabled: bool = True
-    backup_retention_days: int = 30
-    
-    # UI preferences
-    streamlit_theme: str = "light"
-    show_advanced_options: bool = False
-    
-    # Extensions
-    enabled_plugins: List[str] = field(default_factory=list)
-    
-    @classmethod
-    def from_file(cls, config_path: str) -> 'EngineConfig':
-        """Load configuration from YAML file"""
-        
-    def validate(self) -> List[ValidationError]:
-        """Validate configuration completeness and correctness"""
-```
-
-### Multi-Resume Strategy Pattern
-```python
-class ResumeSelectionStrategy(ABC):
-    """Strategy for selecting optimal resume content for specific jobs"""
-    
-    def select_primary_resume(self, portfolio: ResumePortfolio, job_analysis: JobAnalysis) -> Resume:
-        """Select the most relevant primary resume"""
-        
-    def get_supplementary_content(self, portfolio: ResumePortfolio, primary: Resume) -> List[ResumeSection]:
-        """Extract additional content from other resume versions"""
-
-class TechnicalRoleStrategy(ResumeSelectionStrategy):
-    """Optimize resume selection for technical positions"""
-    
-class ManagementRoleStrategy(ResumeSelectionStrategy):
-    """Optimize resume selection for management positions"""
-    
-class ConsultingRoleStrategy(ResumeSelectionStrategy):
-    """Optimize resume selection for consulting positions"""
-```
-
----
-
-## 🚀 Development Phases
-
-### **Phase 1: MVP Foundation (Completed)**
-- ✅ Streamlit UI with file management
-- ✅ 3-phase workflow execution
-- ✅ Claude API integration
-- ✅ Local file storage system
-- ✅ Multi-resume processing
-- ✅ Cover letter reference system
-- ✅ Application status tracking
-
-### **Phase 2: Enhanced Intelligence (Next)**
-- 🔄 Advanced company research integration
-- 🔄 Improved multi-resume synthesis algorithms
-- 🔄 Voice pattern analysis enhancement
-- 🔄 Strategic positioning optimization
-- 🔄 Application performance analytics
-- 🔄 Export functionality (PDF, Word, etc.)
-
-### **Phase 3: Automation & Scale (Future)**
-- 📋 Batch application processing
-- 📋 Template management system
-- 📋 Application campaign planning
-- 📋 Success rate tracking and optimization
-- 📋 Integration with job boards APIs
-- 📋 Automated application submission
-
-### **Phase 4: Enterprise Features (Future)**
-- 📋 Multi-user support with role-based access
-- 📋 Team collaboration features
-- 📋 Advanced analytics and reporting
-- 📋 Custom workflow templates
-- 📋 Integration with HR systems
-- 📋 White-label deployment options
-
----
-
-## 🎯 Technical Specifications
-
-### **Technology Stack**
-
-| Component | Technology | Version | Rationale |
-|-----------|------------|---------|-----------|
-| **UI Framework** | Streamlit | 1.28.1 | Rapid prototyping, built-in components, Python-native |
-| **HTTP Client** | requests | 2.31.0 | Reliable, well-documented, synchronous operations |
-| **Data Validation** | Pydantic | 2.0+ | Type safety, automatic validation, great developer experience |
-| **File Operations** | pathlib | Built-in | Modern, object-oriented path handling |
-| **Configuration** | PyYAML | 6.0+ | Human-readable configuration files |
-| **CLI Future** | Click + Rich | Latest | User-friendly CLI with beautiful output |
-| **Testing** | pytest | 7.0+ | Comprehensive testing framework |
-| **Documentation** | MkDocs | 1.5+ | Beautiful, searchable documentation |
-
-### **Performance Requirements**
-
-| Metric | Target | Measurement Method |
-|--------|--------|-------------------|
-| **Application Creation** | <2 seconds | Time from form submission to folder creation |
-| **Phase 1 Research** | <30 seconds | Claude API response + processing time |
-| **Phase 2 Resume** | <20 seconds | Multi-resume synthesis + optimization |
-| **Phase 3 Cover Letter** | <15 seconds | Voice analysis + content generation |
-| **File Operations** | <1 second | Local file read/write operations |
-| **UI Responsiveness** | <500ms | Streamlit component render time |
-
-### **Quality Standards**
-
-#### **Code Quality Metrics**
-- **Type Coverage**: 90%+ type hints on all public APIs
-- **Test Coverage**: 85%+ line coverage maintained
-- **Documentation**: All public methods and classes documented
-- **Code Style**: Black formatter + isort + flake8 compliance
-- **Complexity**: Max cyclomatic complexity of 10 per function
-
-#### **Security Requirements**
-- No API keys hardcoded in source code
-- Environment variable management for secrets
-- Input sanitization for all user data
-- Safe file path handling to prevent directory traversal
-- Regular dependency vulnerability scanning
-
-#### **Reliability Standards**
-- Graceful handling of API failures with user-friendly messages
-- Automatic retry logic for transient failures
-- Data integrity validation after file operations
-- Rollback capability for failed workflow phases
-- Comprehensive error logging with context
-
----
-
-## 📈 Monitoring & Analytics
-
-### **Application Metrics**
-```python
-class ApplicationMetrics:
-    """Track application performance and success rates"""
-    
-    def record_application_created(self, app: Application) -> None
-    def record_phase_completion(self, app_id: str, phase: PhaseOrchestrator.Phases, duration: float) -> None
-    def record_application_submitted(self, app_id: str) -> None
-    def record_application_response(self, app_id: str, response_type: ResponseType) -> None
-    
-    # Analytics queries
-    def get_success_rate(self, date_range: DateRange) -> float
-    def get_average_completion_time(self, phase: PhaseOrchestrator.Phases) -> float
-    def get_most_effective_strategies(self) -> List[StrategyMetric]
-```
-
-### **Performance Monitoring**
-```python
-class PerformanceMonitor:
-    """Monitor system performance and resource usage"""
-    
-    def track_api_response_times(self) -> Dict[str, float]
-    def monitor_file_system_usage(self) -> StorageMetrics
-    def track_memory_usage(self) -> MemoryMetrics
-    def generate_performance_report(self) -> PerformanceReport
-```
-
-### **User Experience Analytics**
-- Workflow completion rates by phase
-- Most common user pain points
-- Feature usage statistics
-- Error frequency and resolution rates
-- Time-to-value metrics
-
----
-
-## 🔒 Security Architecture
-
-### **Data Protection Strategy**
-- **Local-First**: All sensitive career data stored locally
-- **API Key Management**: Secure environment variable handling
-- **Input Validation**: Comprehensive sanitization of all user inputs
-- **File System Security**: Restricted file access patterns
-- **Audit Trail**: Complete logging of all file operations
-
-### **Privacy Considerations**
-- No personal data transmitted to third parties (except Claude API for processing)
-- User control over all data retention and deletion
-- Transparent data usage policies
-- Optional anonymization for analytics
-
----
-
-## 🎨 User Experience Design
-
-### **Design Principles**
-1. **Simplicity First**: Complex AI power hidden behind simple interfaces
-2. **Progress Transparency**: Clear feedback on all processing steps
-3. **Error Recovery**: Graceful handling with actionable next steps
-4. **Customization**: Flexible configuration without overwhelming options
-5. **Mobile Friendly**: Responsive design for various screen sizes
-
-### **User Journey Optimization**
-```mermaid
-journey
-    title Job Application Creation Journey
-    section Setup
-      Configure folders: 5: User
-      Upload resumes: 4: User
-      Tag references: 3: User
-    section Application
-      Paste job description: 5: User
-      Review auto-generated name: 4: User
-      Start research phase: 5: User
-    section AI Processing
-      Wait for research: 3: User, AI
-      Review research results: 4: User
-      Approve resume optimization: 5: User, AI
-      Review cover letter: 5: User, AI
-    section Completion
-      Make final edits: 4: User
-      Export documents: 5: User
-      Mark as applied: 5: User
-```
-
----
-
-## 📚 Documentation Strategy
-
-### **Documentation Hierarchy**
-1. **Architecture Guide** (This Document) - Technical architecture and design decisions
-2. **User Guide** - Step-by-step usage instructions with screenshots
-3. **API Reference** - Detailed API documentation for extensions
-4. **Developer Guide** - Setup, contribution guidelines, and development practices
-5. **Troubleshooting Guide** - Common issues and solutions
-
-### **Documentation Standards**
-- All public APIs documented with docstrings
-- Code examples for all major features
-- Screenshots for UI components
-- Video tutorials for complex workflows
-- Regular documentation updates with each release
-
----
-
-## 🚀 Deployment & Distribution
-
-### **Distribution Strategy**
-- **GitHub Repository**: Open source with comprehensive documentation
-- **PyPI Package**: Easy installation via pip
-- **Docker Container**: Containerized deployment option
-- **Executable Bundle**: Standalone executable for non-technical users
-
-### **Deployment Options**
-```python
-# Option 1: Direct Python execution
-python -m streamlit run app.py
-
-# Option 2: Docker deployment
-docker run -p 8501:8501 job-application-engine
-
-# Option 3: Heroku deployment
-git push heroku main
-
-# Option 4: Local installation
-pip install job-application-engine
-job-app-engine --config myconfig.yaml
-```
-
----
-
-## 🔮 Future Enhancements
-
-### **Advanced AI Features**
-- **Multi-Model Support**: Integration with multiple AI providers
-- **Specialized Models**: Domain-specific fine-tuned models
-- **Continuous Learning**: System learns from successful applications
-- **Predictive Analytics**: Success probability estimation
-
-### **Integration Ecosystem**
-- **LinkedIn Integration**: Auto-import job postings and company data
-- **ATS Integration**: Direct submission to Applicant Tracking Systems
-- **CRM Integration**: Track application pipeline in existing CRM
-- **Calendar Integration**: Application deadline management
-
-### **Enterprise Features**
-- **Multi-Tenant Architecture**: Support multiple users/organizations
-- **Role-Based Access Control**: Team collaboration with permission levels
-- **Workflow Customization**: Industry-specific workflow templates
-- **Advanced Analytics**: Success attribution and optimization recommendations
-
----
-
-*This architecture guide serves as the authoritative reference for the Job Application Engine system design and implementation. For implementation details, see the source code and technical documentation.*
-
-*For questions or contributions, please refer to the project repository and contribution guidelines.*

docs/jobforge_mvp_architecture.md

@@ -0,0 +1,714 @@
+# JobForge MVP - Core Job Application Module
+
+**Version:** 1.0.0 MVP  
+**Status:** Development Phase 1  
+**Date:** July 2025  
+**Scope:** Core job application workflow with essential features  
+**Target:** Personal use for concept validation and testing
+
+---
+
+## 📋 MVP 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
+
+### 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)
+
+---
+
+## 🏗️ MVP Architecture
+
+### System Overview
+```mermaid
+graph TB
+    subgraph "Frontend (Dash + Mantine)"
+        UI[Main UI]
+        SIDEBAR[Application Sidebar]
+        TOPBAR[Navigation Top Bar]
+        EDITOR[Document Editor]
+    end
+    
+    subgraph "Backend API (FastAPI)"
+        AUTH[Authentication]
+        APP[Application Service]
+        AI[AI Orchestrator]
+        DOC[Document Service]
+    end
+    
+    subgraph "AI Agents"
+        RESEARCH[Research Agent]
+        RESUME[Resume Optimizer]
+        COVER[Cover Letter Generator]
+    end
+    
+    subgraph "Data Storage"
+        PG[(PostgreSQL + pgvector)]
+        FILES[Document Storage]
+    end
+    
+    subgraph "External AI"
+        CLAUDE[Claude AI]
+        OPENAI[OpenAI Embeddings]
+    end
+    
+    UI --> AUTH
+    UI --> APP
+    UI --> DOC
+    APP --> AI
+    AI --> RESEARCH
+    AI --> RESUME
+    AI --> COVER
+    APP --> PG
+    DOC --> FILES
+    RESEARCH --> CLAUDE
+    RESUME --> CLAUDE
+    COVER --> CLAUDE
+    AI --> OPENAI
+```
+
+---
+
+## 🔐 User Authentication (MVP)
+
+### Simple Authentication System
+```python
+class AuthenticationService:
+    """Basic user authentication for MVP"""
+    
+    async def register_user(self, email: str, password: str, name: str) -> User:
+        """Register new user account"""
+        
+    async def authenticate_user(self, email: str, password: str) -> AuthResult:
+        """Login user and return JWT token"""
+        
+    async def verify_token(self, token: str) -> User:
+        """Verify JWT token and return user"""
+        
+    async def logout_user(self, user_id: str) -> None:
+        """Logout user session"""
+```
+
+### Database Schema (Users)
+```sql
+-- Basic user table for MVP
+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()
+);
+
+-- Enable basic row level security
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+```
+
+---
+
+## 📋 Job Application Module
+
+### Core Application Workflow
+```python
+class ApplicationService:
+    """Core job application management"""
+    
+    async def create_application(self, user_id: str, job_data: JobApplicationData) -> Application:
+        """Create new job application with job description and URL"""
+        
+    async def get_user_applications(self, user_id: str) -> List[Application]:
+        """Get all applications for user"""
+        
+    async def get_application(self, user_id: str, app_id: str) -> Application:
+        """Get specific application with documents"""
+        
+    async def update_application_status(self, user_id: str, app_id: str, status: str) -> None:
+        """Update application status through workflow phases"""
+```
+
+### Application Data Model
+```python
+class JobApplicationData(BaseModel):
+    """Input data for creating new application"""
+    job_url: Optional[str] = None
+    job_description: str
+    company_name: str
+    role_title: str
+    location: Optional[str] = None
+    priority_level: str = "medium"
+    additional_context: Optional[str] = None
+
+class Application(BaseModel):
+    """Core application entity"""
+    id: str
+    user_id: str
+    name: str  # Auto-generated: company_role_YYYY_MM_DD
+    company_name: str
+    role_title: str
+    job_url: Optional[str]
+    job_description: str
+    status: ApplicationStatus  # draft, research_complete, resume_ready, cover_letter_ready
+    
+    # Phase completion tracking
+    research_completed: bool = False
+    resume_optimized: bool = False
+    cover_letter_generated: bool = False
+    
+    created_at: datetime
+    updated_at: datetime
+```
+
+### Database Schema (Applications)
+```sql
+CREATE TABLE applications (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID 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,
+    location VARCHAR(255),
+    priority_level VARCHAR(20) DEFAULT 'medium',
+    status VARCHAR(50) DEFAULT 'draft',
+    
+    -- Phase tracking
+    research_completed BOOLEAN DEFAULT FALSE,
+    resume_optimized BOOLEAN DEFAULT FALSE,
+    cover_letter_generated BOOLEAN DEFAULT FALSE,
+    
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY user_applications_policy ON applications
+    FOR ALL TO application_user
+    USING (user_id = current_setting('app.current_user_id')::UUID);
+```
+
+---
+
+## 🤖 AI Processing Workflow
+
+### 3-Phase AI Orchestrator
+```python
+class AIOrchestrator:
+    """Orchestrates the 3-phase AI workflow"""
+    
+    def __init__(self, research_agent, resume_optimizer, cover_letter_generator):
+        self.research_agent = research_agent
+        self.resume_optimizer = resume_optimizer
+        self.cover_letter_generator = cover_letter_generator
+    
+    async def execute_research_phase(self, application_id: str) -> ResearchReport:
+        """Phase 1: Job analysis and company research"""
+        
+    async def execute_resume_optimization(self, application_id: str) -> OptimizedResume:
+        """Phase 2: Resume optimization based on research"""
+        
+    async def execute_cover_letter_generation(self, application_id: str, user_context: str) -> CoverLetter:
+        """Phase 3: Cover letter generation with user inputs"""
+```
+
+### Phase 1: Research Agent
+```python
+class ResearchAgent:
+    """Job description analysis and company research"""
+    
+    async def analyze_job_description(self, job_desc: str) -> JobAnalysis:
+        """Extract requirements, skills, and key information"""
+        
+    async def research_company_info(self, company_name: str) -> CompanyIntelligence:
+        """Basic company research and insights"""
+        
+    async def generate_strategic_positioning(self, job_analysis: JobAnalysis) -> StrategicPositioning:
+        """Determine optimal candidate positioning"""
+        
+    async def create_research_report(self, job_desc: str, company_name: str) -> ResearchReport:
+        """Complete research phase output"""
+```
+
+### Phase 2: Resume Optimizer
+```python
+class ResumeOptimizer:
+    """Resume optimization based on job requirements"""
+    
+    async def analyze_resume_portfolio(self, user_id: str) -> ResumePortfolio:
+        """Load and analyze user's resume library"""
+        
+    async def optimize_resume_for_job(self, portfolio: ResumePortfolio, research: ResearchReport) -> OptimizedResume:
+        """Create job-specific optimized resume"""
+        
+    async def validate_resume_optimization(self, resume: OptimizedResume) -> ValidationReport:
+        """Ensure resume meets requirements and constraints"""
+```
+
+### Phase 3: Cover Letter Generator
+```python
+class CoverLetterGenerator:
+    """Cover letter generation with user context"""
+    
+    async def analyze_writing_style(self, user_id: str) -> WritingStyle:
+        """Analyze user's writing patterns from reference documents"""
+        
+    async def generate_cover_letter(self, research: ResearchReport, resume: OptimizedResume, 
+                                  user_context: str, writing_style: WritingStyle) -> CoverLetter:
+        """Generate personalized cover letter"""
+        
+    async def validate_cover_letter(self, cover_letter: CoverLetter) -> ValidationReport:
+        """Ensure cover letter quality and authenticity"""
+```
+
+---
+
+## 📄 Document Management
+
+### Document Storage & Retrieval
+```python
+class DocumentService:
+    """Handle document storage and retrieval"""
+    
+    async def save_document(self, user_id: str, app_id: str, doc_type: str, content: str) -> None:
+        """Save generated document (research, resume, cover letter)"""
+        
+    async def get_document(self, user_id: str, app_id: str, doc_type: str) -> Document:
+        """Retrieve document for viewing/editing"""
+        
+    async def update_document(self, user_id: str, app_id: str, doc_type: str, content: str) -> None:
+        """Update document after user editing"""
+        
+    async def get_all_documents(self, user_id: str, app_id: str) -> ApplicationDocuments:
+        """Get all documents for an application"""
+```
+
+### Document Models
+```python
+class Document(BaseModel):
+    """Base document model"""
+    id: str
+    application_id: str
+    document_type: str  # research_report, optimized_resume, cover_letter
+    content: str
+    created_at: datetime
+    updated_at: datetime
+
+class ApplicationDocuments(BaseModel):
+    """All documents for an application"""
+    research_report: Optional[Document] = None
+    optimized_resume: Optional[Document] = None
+    cover_letter: Optional[Document] = None
+```
+
+### Database Schema (Documents)
+```sql
+CREATE TABLE documents (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id UUID REFERENCES applications(id) ON DELETE CASCADE,
+    document_type VARCHAR(50) NOT NULL,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY user_documents_policy ON documents
+    FOR ALL TO application_user
+    USING (
+        application_id IN (
+            SELECT id FROM applications 
+            WHERE user_id = current_setting('app.current_user_id')::UUID
+        )
+    );
+```
+
+---
+
+## 🎨 Frontend Interface (Dash + Mantine)
+
+### Main Application Layout
+```python
+class JobForgeApp:
+    """Main Dash application layout"""
+    
+    def create_layout(self):
+        return dmc.MantineProvider([
+            dmc.AppShell([
+                dmc.Navbar([
+                    ApplicationSidebar()
+                ], width={"base": 300}),
+                dmc.Main([
+                    ApplicationTopBar(),
+                    MainContent()
+                ])
+            ])
+        ])
+```
+
+### Application Sidebar
+```python
+class ApplicationSidebar:
+    """Sidebar with applications list and navigation"""
+    
+    def render(self, user_id: str):
+        return dmc.Stack([
+            # New Application Button
+            dmc.Button(
+                "➕ New Application",
+                id="new-app-btn",
+                fullWidth=True,
+                variant="filled"
+            ),
+            
+            # Applications List
+            dmc.Title("Applications", order=4),
+            dmc.ScrollArea([
+                ApplicationCard(app) for app in self.get_user_applications(user_id)
+            ]),
+            
+            # Resume Library Section
+            dmc.Divider(),
+            dmc.Title("Resume Library", order=4),
+            ResumeLibrarySection()
+        ])
+
+class ApplicationCard:
+    """Individual application card in sidebar"""
+    
+    def render(self, application: Application):
+        return dmc.Card([
+            dmc.Group([
+                dmc.Text(application.company_name, weight=600),
+                StatusBadge(application.status)
+            ]),
+            dmc.Text(application.role_title, size="sm", color="dimmed"),
+            dmc.Text(application.created_at.strftime("%Y-%m-%d"), size="xs")
+        ], id=f"app-card-{application.id}")
+```
+
+### Application Top Bar Navigation
+```python
+class ApplicationTopBar:
+    """Top navigation bar for application phases"""
+    
+    def render(self, application: Application):
+        return dmc.Group([
+            # Phase Navigation Buttons
+            PhaseButton("Research", "research", application.research_completed),
+            PhaseButton("Resume", "resume", application.resume_optimized),
+            PhaseButton("Cover Letter", "cover_letter", application.cover_letter_generated),
+            
+            # Application Actions
+            dmc.Spacer(),
+            dmc.ActionIcon(
+                DashIconify(icon="tabler:settings"),
+                id="app-settings-btn"
+            )
+        ])
+
+class PhaseButton:
+    """Navigation button for each phase"""
+    
+    def render(self, label: str, phase: str, completed: bool):
+        icon = "tabler:check" if completed else "tabler:clock"
+        color = "green" if completed else "gray"
+        
+        return dmc.Button([
+            DashIconify(icon=icon),
+            dmc.Text(label, ml="xs")
+        ], 
+        variant="subtle" if not completed else "filled",
+        color=color,
+        id=f"phase-{phase}-btn"
+        )
+```
+
+### Document Editor Interface
+```python
+class DocumentEditor:
+    """Markdown document editor with preview"""
+    
+    def render(self, document: Document):
+        return dmc.Container([
+            dmc.Grid([
+                # Editor Column
+                dmc.Col([
+                    dmc.Title(f"Edit {document.document_type.replace('_', ' ').title()}", order=3),
+                    dmc.Textarea(
+                        value=document.content,
+                        placeholder="Document content...",
+                        minRows=20,
+                        autosize=True,
+                        id=f"editor-{document.document_type}"
+                    ),
+                    dmc.Group([
+                        dmc.Button("Save Changes", id="save-btn"),
+                        dmc.Button("Cancel", variant="outline", id="cancel-btn")
+                    ])
+                ], span=6),
+                
+                # Preview Column
+                dmc.Col([
+                    dmc.Title("Preview", order=3),
+                    dmc.Container([
+                        dcc.Markdown(document.content, id="preview-content")
+                    ], style={"border": "1px solid #e0e0e0", "padding": "1rem", "minHeight": "500px"})
+                ], span=6)
+            ])
+        ])
+```
+
+---
+
+## 🗄️ MVP Database Schema
+
+### Complete Database Setup
+```sql
+-- Enable required extensions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Users table
+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()
+);
+
+-- Applications table
+CREATE TABLE applications (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID 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,
+    location VARCHAR(255),
+    priority_level VARCHAR(20) DEFAULT 'medium',
+    status VARCHAR(50) DEFAULT 'draft',
+    
+    research_completed BOOLEAN DEFAULT FALSE,
+    resume_optimized BOOLEAN DEFAULT FALSE,
+    cover_letter_generated BOOLEAN DEFAULT FALSE,
+    
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Documents table
+CREATE TABLE documents (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id UUID REFERENCES applications(id) ON DELETE CASCADE,
+    document_type VARCHAR(50) NOT NULL,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW(),
+    
+    UNIQUE(application_id, document_type)
+);
+
+-- Resume library table
+CREATE TABLE user_resumes (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(255) NOT NULL,
+    content TEXT NOT NULL,
+    focus_area VARCHAR(100),
+    is_primary BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Basic vector embeddings (for future enhancement)
+CREATE TABLE document_embeddings (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
+    embedding vector(1536),
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Row Level Security
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+ALTER TABLE user_resumes ENABLE ROW LEVEL SECURITY;
+
+-- Security policies
+CREATE POLICY user_own_data ON applications FOR ALL USING (user_id = current_setting('app.current_user_id')::UUID);
+CREATE POLICY user_own_documents ON documents FOR ALL USING (
+    application_id IN (SELECT id FROM applications WHERE user_id = current_setting('app.current_user_id')::UUID)
+);
+CREATE POLICY user_own_resumes ON user_resumes FOR ALL USING (user_id = current_setting('app.current_user_id')::UUID);
+```
+
+---
+
+## 🚀 MVP 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
+
+#### **Week 3-4: Core Application Module**
+- Application creation and listing
+- Database integration with user isolation
+- Basic sidebar and navigation UI
+- Application status tracking
+
+#### **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
+
+#### **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
+
+### 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
+
+---
+
+## 🐳 Docker Development Setup
+
+### Development 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:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
+      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    volumes:
+      - ./src:/app/src
+    depends_on:
+      - postgres
+    command: uvicorn src.backend.main:app --host 0.0.0.0 --port 8000 --reload
+
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile.frontend
+    ports:
+      - "8501:8501"
+    environment:
+      - BACKEND_URL=http://backend:8000
+    volumes:
+      - ./src/frontend:/app/src/frontend
+    depends_on:
+      - backend
+    command: python src/frontend/main.py
+
+volumes:
+  postgres_data:
+```
+
+---
+
+## 📁 MVP Project Structure
+
+```
+jobforge-mvp/
+├── docker-compose.yml
+├── Dockerfile.backend
+├── Dockerfile.frontend
+├── requirements-backend.txt
+├── requirements-frontend.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/
+```
+
+---
+
+*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.*

docs/team_management_guide.md

@@ -0,0 +1,951 @@
+# 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.*

docs/testing_strategy.md

@@ -0,0 +1,700 @@
+# 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.*

requirements-backend.txt

@@ -0,0 +1,49 @@
+# FastAPI and web framework
+fastapi==0.109.2
+uvicorn[standard]==0.27.1
+python-multipart==0.0.9
+
+# Database
+asyncpg==0.29.0
+sqlalchemy[asyncio]==2.0.29
+alembic==1.13.1
+psycopg2-binary==2.9.9
+
+# Authentication & Security
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+python-bcrypt==4.1.2
+
+# AI Services
+anthropic==0.21.3
+openai==1.12.0
+
+# Vector operations
+pgvector==0.2.5
+numpy==1.26.4
+
+# Data validation
+pydantic==2.6.3
+pydantic-settings==2.2.1
+
+# HTTP client
+httpx==0.27.0
+aiohttp==3.9.3
+
+# Utilities
+python-dotenv==1.0.1
+structlog==24.1.0
+tenacity==8.2.3
+
+# Development & Testing
+pytest==8.0.2
+pytest-asyncio==0.23.5
+pytest-cov==4.0.0
+pytest-mock==3.12.0
+black==24.2.0
+isort==5.13.2
+flake8==7.0.0
+mypy==1.8.0
+
+# Security
+bandit==1.7.7

requirements-frontend.txt

@@ -0,0 +1,21 @@
+# Dash and web framework
+dash==2.16.1
+dash-mantine-components==0.12.1
+dash-iconify==0.1.2
+
+# HTTP client for API calls
+requests==2.31.0
+httpx==0.27.0
+
+# Data handling
+pandas==2.2.1
+plotly==5.18.0
+
+# Utilities
+python-dotenv==1.0.1
+structlog==24.1.0
+
+# Development
+pytest==8.0.2
+black==24.2.0
+isort==5.13.2