diff --git a/.claude/ai_engineer.md b/.claude/ai_engineer.md
new file mode 100644
index 0000000..004d767
--- /dev/null
+++ b/.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}
+
+
+
+{additional_context}
+
+
+
+{specific_task_instructions}
+
+"""
+```
+
+### **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.
\ No newline at end of file
diff --git a/.claude/backend_developer.md b/.claude/backend_developer.md
new file mode 100644
index 0000000..0649d7e
--- /dev/null
+++ b/.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.
\ No newline at end of file
diff --git a/.claude/devops_engineer.md b/.claude/devops_engineer.md
new file mode 100644
index 0000000..f4a4a92
--- /dev/null
+++ b/.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.
\ No newline at end of file
diff --git a/.claude/frontend_developer.md b/.claude/frontend_developer.md
new file mode 100644
index 0000000..2a8a0f4
--- /dev/null
+++ b/.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.
\ No newline at end of file
diff --git a/.claude/project_architect.md b/.claude/project_architect.md
new file mode 100644
index 0000000..3ac4a67
--- /dev/null
+++ b/.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.
\ No newline at end of file
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..bea3da4
--- /dev/null
+++ b/.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
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 36b13f1..a5f6005 100644
--- a/.gitignore
+++ b/.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
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5b02a1d
--- /dev/null
+++ b/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 ` 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.
\ No newline at end of file
diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
new file mode 100644
index 0000000..40abd04
--- /dev/null
+++ b/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! 🚀**
\ No newline at end of file
diff --git a/MVP_CHECKLIST.md b/MVP_CHECKLIST.md
new file mode 100644
index 0000000..bbfa972
--- /dev/null
+++ b/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!*
\ No newline at end of file
diff --git a/README.md b/README.md
index 93b138f..92830db 100644
--- a/README.md
+++ b/README.md
@@ -2,121 +2,33 @@
**AI-Powered Job Application Management System**
-Transform your job search with intelligent document generation and strategic application management. JobForge leverages advanced AI to create tailored resumes and cover letters while streamlining your entire application workflow.
+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.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://www.postgresql.org/)
-[](https://www.docker.com/)
---
-## 🎯 Project Overview
-
-### What is JobForge?
-
-JobForge is an AI-powered job application management system designed to streamline and optimize the job search process. Built for individual job seekers, it combines strategic application management with advanced AI document generation to maximize your chances of landing interviews.
-
-### Key Features (MVP)
-
-✨ **3-Phase AI Workflow**
-- **Research Phase:** Automated job description analysis and company research
-- **Resume Optimization:** Multi-resume synthesis tailored to specific job requirements
-- **Cover Letter Generation:** Personalized cover letters with authentic voice preservation
-
-🎨 **Modern Interface**
-- Professional web application built with Dash + Mantine components
-- Intuitive sidebar navigation and document management
-- Real-time processing status and progress tracking
-
-🔒 **Secure & Private**
-- Complete user data isolation with PostgreSQL Row-Level Security
-- Local document storage with full user control
-- JWT-based authentication system
-
-🤖 **AI-Powered Intelligence**
-- Claude Sonnet 4 for document generation and analysis
-- OpenAI embeddings for semantic document matching
-- Vector database for intelligent insights and recommendations
-
----
-
-## 🏗️ Architecture Overview
-
-### Technology Stack
-
-| Component | Technology | Purpose |
-|-----------|------------|---------|
-| **Frontend** | Dash + Mantine | Modern, responsive web interface |
-| **Backend** | FastAPI + AsyncIO | High-performance REST API |
-| **Database** | PostgreSQL 16 + pgvector | Data persistence with vector search |
-| **AI Services** | Claude Sonnet 4, OpenAI | Document generation and analysis |
-| **Development** | Docker Compose | Containerized development environment |
-| **Authentication** | JWT + bcrypt | Secure user authentication |
-
-### System Architecture
-
-```mermaid
-graph TB
- subgraph "Frontend Layer"
- UI[Dash + Mantine UI]
- COMP[Reusable Components]
- end
-
- subgraph "Backend API"
- API[FastAPI Rest API]
- AUTH[JWT Authentication]
- SERVICES[Business Services]
- end
-
- subgraph "AI Processing"
- CLAUDE[Claude Sonnet 4]
- OPENAI[OpenAI Embeddings]
- AGENTS[AI Agents]
- end
-
- subgraph "Data Layer"
- PG[(PostgreSQL + pgvector)]
- REDIS[(Redis Cache)]
- end
-
- UI --> API
- API --> AUTH
- API --> SERVICES
- SERVICES --> AGENTS
- AGENTS --> CLAUDE
- AGENTS --> OPENAI
- SERVICES --> PG
- API --> REDIS
-```
-
----
-
-## 🚀 Quick Start
+## 🚀 Quick Start (5 Minutes)
### Prerequisites
-
- **Docker Desktop** 4.20+ with Docker Compose
+- **API Keys**: Claude API key, OpenAI API key
- **Git** 2.30+
-- **API Keys:** Claude API key, OpenAI API key
### 1. Clone & Setup
-
```bash
-# Clone the repository
git clone https://github.com/your-org/jobforge-mvp.git
cd jobforge-mvp
-# Copy environment template
+# Copy environment template and add your API keys
cp .env.example .env
-
-# Add your API keys to .env file
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
@@ -125,258 +37,284 @@ docker-compose up -d
docker-compose logs -f
```
-### 3. Access the Application
+### 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
-- **Frontend Application:** http://localhost:8501
-- **Backend API:** http://localhost:8000
-- **API Documentation:** http://localhost:8000/docs
-
-### 4. Create Your First Application
-
-1. Register a new account at http://localhost:8501
-2. Upload your resume(s) to the resume library
-3. Create a new job application with company details and job description
-4. Watch the AI generate your research report, optimized resume, and cover letter
-5. Edit and refine the generated documents as needed
-
----
-
-## 📚 Documentation
-
-### 📖 Core Documentation
-
-| Document | Description | For |
-|----------|-------------|-----|
-| **[📋 MVP Architecture](docs/mvp-architecture.md)** | High-level system design and component overview | All team members |
-| **[🔧 Development Setup](docs/development-setup.md)** | Complete environment setup with troubleshooting | Developers |
-| **[🌿 Git Branch Strategy](docs/git-branch-strategy.md)** | Version control workflow and team coordination | All team members |
-
-### 🛠️ Technical Documentation
-
-| Document | Description | For |
-|----------|-------------|-----|
-| **[🔌 API Specification](docs/api-specification.md)** | Complete REST API documentation with examples | Backend developers |
-| **[🗄️ Database Design](docs/database-design.md)** | Schema, security policies, and optimization | Backend developers |
-| **[🧪 Testing Strategy](docs/testing-strategy.md)** | Testing guidelines and automation setup | All developers |
-
-### 📝 Additional Resources
-
-- **[📊 Project Roadmap](#roadmap)** - Development timeline and milestones
-- **[🤝 Contributing Guidelines](#contributing)** - How to contribute to the project
-- **[❓ FAQ](#faq)** - Common questions and answers
-
----
-
-## 🔄 Development Workflow
-
-### Branch Strategy
-
-We use a **Git Flow** approach with the following branches:
-
-- **`main`** - Production-ready code (protected)
-- **`develop`** - Integration branch for completed features
-- **`feature/*`** - Individual feature development
-- **`hotfix/*`** - Emergency production fixes
-- **`release/*`** - Release preparation and testing
-
-**Example feature branch names:**
+### 4. Quick Validation
```bash
-feature/backend-user-authentication
-feature/frontend-application-sidebar
-feature/ai-claude-integration
-feature/database-rls-policies
+# Check backend health
+curl http://localhost:8000/health
+
+# Check all services are running
+docker-compose ps
```
-See our **[Git Branch Strategy](docs/git-branch-strategy.md)** for detailed workflows.
-
-### Development Process
-
-1. **Start Feature:** Create branch from `develop`
-2. **Implement:** Follow coding standards and write tests
-3. **Test:** Ensure all tests pass and CI/CD checks succeed
-4. **Review:** Submit PR with detailed description
-5. **Merge:** Merge to `develop` after approval
-6. **Deploy:** Automatic deployment to staging environment
+All services should show "Up" status. If any issues, see [Troubleshooting](#-troubleshooting) below.
---
-## 🏃♂️ Project Status
+## ✨ What is JobForge?
-### Current Phase: MVP Development
+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.
-**Timeline:** 8 weeks (July - August 2025)
-**Status:** 🚧 In Development
-**Target:** Production-ready MVP for personal use and concept validation
+### 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
-### MVP Milestones
-
-| Week | Milestone | Status |
-|------|-----------|--------|
-| **1-2** | Foundation & Infrastructure | 🚧 In Progress |
-| **3-4** | User Authentication & Application CRUD | ⏳ Planned |
-| **5-6** | AI Agents Integration | ⏳ Planned |
-| **7-8** | Frontend Polish & Release | ⏳ Planned |
-
-### Feature Completion
-
-- [x] Project setup and documentation
-- [x] Docker development environment
-- [ ] User authentication system
-- [ ] Application creation and management
-- [ ] AI-powered research generation
-- [ ] Resume optimization engine
-- [ ] Cover letter generation
-- [ ] Document editing interface
-- [ ] Production deployment
+### Technology Stack
+- **Frontend**: Dash + Mantine components
+- **Backend**: FastAPI + AsyncIO
+- **Database**: PostgreSQL 16 + pgvector
+- **AI**: Claude Sonnet 4, OpenAI embeddings
+- **Development**: Docker Compose
---
-## 🧪 Testing
-
-### Testing Strategy
-
-We maintain high code quality through comprehensive testing:
-
-- **Unit Tests:** Business logic and services (80%+ coverage)
-- **Integration Tests:** API endpoints and database interactions
-- **Manual Testing:** Complete user workflows and edge cases
-- **AI Mocking:** Reliable testing without external API dependencies
-
-### Running Tests
+## 🛠️ Development Commands
+### Essential Commands
```bash
-# Run all tests
+# 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 with coverage report
+# 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
```
-See **[Testing Strategy](docs/testing-strategy.md)** for detailed testing guidelines.
-
----
-
-## 🚀 Deployment
-
-### Development Environment
-
+### Database Operations
```bash
-# Start development environment
-docker-compose up -d
+# Connect to PostgreSQL database
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
-# View service logs
-docker-compose logs -f [service_name]
-
-# Stop environment
-docker-compose down
+# Check database health
+curl http://localhost:8000/health
```
-### Production Deployment
+---
-Production deployment instructions will be added as we approach MVP completion. The current focus is on local development and testing.
+## 🏗️ 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
+```
---
-## 🤝 Contributing
+## 🔧 Environment Configuration
-### Getting Started
+### Required Environment Variables
+Copy `.env.example` to `.env` and configure:
-1. **Read the Documentation:** Start with [Development Setup](docs/development-setup.md)
-2. **Set Up Environment:** Follow the quick start guide above
-3. **Choose a Task:** Check open issues or discuss new features
-4. **Create Feature Branch:** Follow our [Git Branch Strategy](docs/git-branch-strategy.md)
-5. **Submit Pull Request:** Include tests and documentation updates
+```bash
+# API Keys (REQUIRED)
+CLAUDE_API_KEY=your_claude_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
-### Development Standards
+# Database (Auto-configured for local development)
+DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
-- **Code Style:** Black formatter, isort imports, type hints required
-- **Testing:** Write tests for new functionality, maintain coverage
-- **Documentation:** Update relevant docs for user-facing changes
-- **Security:** Never commit API keys or sensitive data
+# JWT Secret (Generate random string)
+JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
-### Pull Request Process
+# Development Settings
+DEBUG=true
+LOG_LEVEL=INFO
+```
-1. Create feature branch from `develop`
-2. Implement changes with tests
-3. Ensure all CI/CD checks pass
-4. Submit PR with detailed description
-5. Address code review feedback
-6. Merge after approval
+### 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
---
-## 📊 Roadmap {#roadmap}
+## 📚 Documentation
-### Phase 1: MVP (Current - August 2025)
+All technical documentation is centralized in the `/docs` folder:
-**Goal:** Production-ready job application management tool for personal use
+### 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
-**Key Features:**
-- Complete 3-phase AI workflow
-- Professional web interface
-- Secure user authentication
-- Document management and editing
-
-### Phase 2: SaaS Platform (September 2025+)
-
-**Goal:** Multi-tenant SaaS platform with subscription billing
-
-**Planned Features:**
-- Subscription management and billing
-- Usage analytics and insights
-- Advanced AI features and learning
-- Post-application tracking (interviews, responses)
-- Mobile application
-
-### Phase 3: Advanced Features (Future)
-
-**Goal:** Enterprise-grade job application platform
-
-**Planned Features:**
-- Multi-language support
-- Integration with job boards and ATS systems
-- Advanced analytics and success prediction
-- White-label solutions for career coaches
+### 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
---
-## ❓ FAQ {#faq}
+## 🐛 Troubleshooting
-### General Questions
+### Common Issues
-**Q: What makes JobForge different from other job application tools?**
-A: JobForge combines AI-powered document generation with strategic application management. Unlike simple trackers, it actively helps create better applications using advanced AI analysis and multi-resume optimization.
+#### "Port already in use"
+```bash
+# Check what's using the port
+lsof -i :8501 # or :8000, :5432
-**Q: Is JobForge free to use?**
-A: The MVP is designed for personal use and concept validation. Future SaaS plans will include both free and paid tiers with different feature sets.
+# Kill the process or change ports in docker-compose.yml
+```
-**Q: What AI models does JobForge use?**
-A: We use Claude Sonnet 4 for document generation and analysis, plus OpenAI embeddings for semantic search and document matching.
+#### "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-"
-### Technical Questions
+# Ensure .env file is in project root
+ls -la .env
+```
-**Q: Can I run JobForge without Docker?**
-A: While possible, Docker is strongly recommended for consistent development environments. Manual setup instructions may be added in the future.
+#### "Database Connection Failed"
+```bash
+# Check if PostgreSQL is running
+docker-compose ps postgres
-**Q: How secure is my job application data?**
-A: Very secure. We use PostgreSQL Row-Level Security for complete user data isolation, JWT authentication, and all sensitive data is encrypted at rest.
+# Check database logs
+docker-compose logs postgres
-**Q: Can I contribute to JobForge development?**
-A: Yes! Check our [Contributing Guidelines](#contributing) and [Development Setup](docs/development-setup.md) to get started.
+# Try connecting manually
+docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
+```
-### Development Questions
+#### "Frontend Won't Load"
+```bash
+# Check frontend logs
+docker-compose logs frontend
-**Q: What's the recommended development workflow?**
-A: Follow our [Git Branch Strategy](docs/git-branch-strategy.md) - create feature branches from `develop`, implement with tests, submit PRs for review.
+# Common issue: Backend not ready
+curl http://localhost:8000/health
-**Q: How do I add a new API endpoint?**
-A: See our [API Specification](docs/api-specification.md) for examples and patterns, then follow the testing guidelines in [Testing Strategy](docs/testing-strategy.md).
+# Restart frontend
+docker-compose restart frontend
+```
-**Q: Where can I find the database schema?**
-A: Complete schema documentation is in [Database Design](docs/database-design.md) including security policies and performance optimization.
+### 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
---
@@ -386,35 +324,14 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
---
-## 🙏 Acknowledgments
+## 🤝 Contributing
-- **Claude Sonnet 4** by Anthropic for advanced AI document generation
-- **OpenAI** for embedding models and semantic search capabilities
-- **FastAPI** community for the excellent async web framework
-- **Dash** and **Plotly** teams for the modern Python web framework
-- **PostgreSQL** and **pgvector** for robust data storage and vector search
+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
---
-## 📞 Support & Contact
-
-### Development Team
-
-For development questions, bug reports, or feature requests:
-
-- **Issues:** Use GitHub/Gitea issues for bug reports and feature requests
-- **Discussions:** Use GitHub/Gitea discussions for general questions
-- **Documentation:** Check the [docs](docs/) folder for detailed guides
-
-### Getting Help
-
-1. **Check Documentation:** Most questions are answered in our comprehensive docs
-2. **Search Issues:** Look for existing issues or discussions
-3. **Ask Questions:** Create new discussions for general questions
-4. **Report Bugs:** Use issue templates for bug reports
-
----
-
-**Made with ❤️ for job seekers everywhere**
-
-*Transform your job search. Forge your path to success.*
\ No newline at end of file
+**Ready to transform your job search? Let's build something amazing! 🚀**
\ No newline at end of file
diff --git a/database/init.sql b/database/init.sql
new file mode 100644
index 0000000..22aa125
--- /dev/null
+++ b/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;
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..9804dd4
--- /dev/null
+++ b/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:
\ No newline at end of file
diff --git a/requirements-backend.txt b/requirements-backend.txt
new file mode 100644
index 0000000..d14bf2a
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/requirements-frontend.txt b/requirements-frontend.txt
new file mode 100644
index 0000000..902bc64
--- /dev/null
+++ b/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
\ No newline at end of file