job-forge/docs/jobforge_mvp_architecture.md

Job Forge - Python/FastAPI Web Application Architecture

Version: 1.0.0 Prototype
Status: Development Phase 1
Date: August 2025
Scope: AI-powered job application management web application
Target: Prototype development for server deployment

---

📋 Application Scope & Objectives

Core Web Application Features

• User Authentication: JWT-based secure authentication system
• Job Application Management: Full CRUD operations for job applications
• AI-Powered Document Generation: Automated cover letter and resume optimization
• Web Interface: Modern responsive web interface using Dash + Mantine
• Multi-tenant Architecture: Secure user data isolation with RLS

Development Goals

• Deploy functional prototype to personal server
• Validate AI workflow effectiveness for job applications
• Test web application performance and user experience
• Establish scalable architecture for future enhancements
• Demonstrate full-stack Python/FastAPI capabilities

---

🏗️ Web Application Architecture

System Overview

graph TB
    subgraph "Web Frontend (Dash + Mantine)"
        UI[Dashboard Interface]
        FORMS[Application Forms]
        EDITOR[Document Editor]
        VIEWER[Document Viewer]
    end
    
    subgraph "Backend API (FastAPI)"
        AUTH[JWT Authentication]
        CRUD[Application CRUD]
        AI[AI Service Layer]
        FILES[Document Management]
    end
    
    subgraph "AI Agents"
        RESEARCH[Research Agent]
        RESUME[Resume Optimizer]
        COVER[Cover Letter Generator]
    end
    
    subgraph "Data Storage"
        PG[(PostgreSQL + pgvector)]
        FILES[Document Storage]
    end
    
    subgraph "External AI"
        CLAUDE[Claude AI]
        OPENAI[OpenAI Embeddings]
    end
    
    UI --> AUTH
    FORMS --> CRUD
    EDITOR --> FILES
    VIEWER --> FILES
    CRUD --> AI
    AI --> RESEARCH
    AI --> RESUME
    AI --> COVER
    CRUD --> PG
    FILES --> PG
    RESEARCH --> CLAUDE
    RESUME --> CLAUDE
    COVER --> CLAUDE
    AI --> OPENAI

---

🔐 User Authentication (Web Application)

JWT-Based Authentication System

class AuthenticationService:
    """JWT-based authentication for web application"""
    
    async def register_user(self, user_data: UserCreate) -> User:
        """Register new user account with validation"""
        
    async def authenticate_user(self, credentials: UserLogin) -> AuthResult:
        """Authenticate user and return JWT access token"""
        
    async def verify_token(self, token: str) -> User:
        """Verify JWT token and return authenticated user"""
        
    async def refresh_token(self, refresh_token: str) -> AuthResult:
        """Refresh JWT access token"""
        
    def create_access_token(self, user_id: str) -> str:
        """Create JWT access token with expiration"""

Database Schema (Users)

-- User table with enhanced security
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Enable row level security for multi-tenancy
ALTER TABLE users ENABLE ROW LEVEL SECURITY;

-- Create index for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_active ON users(is_active);

---

📋 Job Application Module

Core Application Workflow

class ApplicationService:
    """Core job application management"""
    
    async def create_application(self, user_id: str, job_data: JobApplicationData) -> Application:
        """Create new job application with job description and URL"""
        
    async def get_user_applications(self, user_id: str) -> List[Application]:
        """Get all applications for user"""
        
    async def get_application(self, user_id: str, app_id: str) -> Application:
        """Get specific application with documents"""
        
    async def update_application_status(self, user_id: str, app_id: str, status: str) -> None:
        """Update application status through workflow phases"""

Application Data Model

class JobApplicationData(BaseModel):
    """Input data for creating new application"""
    job_url: Optional[str] = None
    job_description: str
    company_name: str
    role_title: str
    location: Optional[str] = None
    priority_level: str = "medium"
    additional_context: Optional[str] = None

class Application(BaseModel):
    """Core application entity"""
    id: str
    user_id: str
    name: str  # Auto-generated: company_role_YYYY_MM_DD
    company_name: str
    role_title: str
    job_url: Optional[str]
    job_description: str
    status: ApplicationStatus  # draft, research_complete, resume_ready, cover_letter_ready
    
    # Phase completion tracking
    research_completed: bool = False
    resume_optimized: bool = False
    cover_letter_generated: bool = False
    
    created_at: datetime
    updated_at: datetime

Database Schema (Applications)

CREATE TABLE applications (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    company_name VARCHAR(255) NOT NULL,
    role_title VARCHAR(255) NOT NULL,
    job_url TEXT,
    job_description TEXT NOT NULL,
    location VARCHAR(255),
    priority_level VARCHAR(20) DEFAULT 'medium',
    status VARCHAR(50) DEFAULT 'draft',
    
    -- Phase tracking
    research_completed BOOLEAN DEFAULT FALSE,
    resume_optimized BOOLEAN DEFAULT FALSE,
    cover_letter_generated BOOLEAN DEFAULT FALSE,
    
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

ALTER TABLE applications ENABLE ROW LEVEL SECURITY;

CREATE POLICY user_applications_policy ON applications
    FOR ALL TO application_user
    USING (user_id = current_setting('app.current_user_id')::UUID);

---

🤖 AI Processing Workflow

3-Phase AI Orchestrator

class AIOrchestrator:
    """Orchestrates the 3-phase AI workflow"""
    
    def __init__(self, research_agent, resume_optimizer, cover_letter_generator):
        self.research_agent = research_agent
        self.resume_optimizer = resume_optimizer
        self.cover_letter_generator = cover_letter_generator
    
    async def execute_research_phase(self, application_id: str) -> ResearchReport:
        """Phase 1: Job analysis and company research"""
        
    async def execute_resume_optimization(self, application_id: str) -> OptimizedResume:
        """Phase 2: Resume optimization based on research"""
        
    async def execute_cover_letter_generation(self, application_id: str, user_context: str) -> CoverLetter:
        """Phase 3: Cover letter generation with user inputs"""

Phase 1: Research Agent

class ResearchAgent:
    """Job description analysis and company research"""
    
    async def analyze_job_description(self, job_desc: str) -> JobAnalysis:
        """Extract requirements, skills, and key information"""
        
    async def research_company_info(self, company_name: str) -> CompanyIntelligence:
        """Basic company research and insights"""
        
    async def generate_strategic_positioning(self, job_analysis: JobAnalysis) -> StrategicPositioning:
        """Determine optimal candidate positioning"""
        
    async def create_research_report(self, job_desc: str, company_name: str) -> ResearchReport:
        """Complete research phase output"""

Phase 2: Resume Optimizer

class ResumeOptimizer:
    """Resume optimization based on job requirements"""
    
    async def analyze_resume_portfolio(self, user_id: str) -> ResumePortfolio:
        """Load and analyze user's resume library"""
        
    async def optimize_resume_for_job(self, portfolio: ResumePortfolio, research: ResearchReport) -> OptimizedResume:
        """Create job-specific optimized resume"""
        
    async def validate_resume_optimization(self, resume: OptimizedResume) -> ValidationReport:
        """Ensure resume meets requirements and constraints"""

Phase 3: Cover Letter Generator

class CoverLetterGenerator:
    """Cover letter generation with user context"""
    
    async def analyze_writing_style(self, user_id: str) -> WritingStyle:
        """Analyze user's writing patterns from reference documents"""
        
    async def generate_cover_letter(self, research: ResearchReport, resume: OptimizedResume, 
                                  user_context: str, writing_style: WritingStyle) -> CoverLetter:
        """Generate personalized cover letter"""
        
    async def validate_cover_letter(self, cover_letter: CoverLetter) -> ValidationReport:
        """Ensure cover letter quality and authenticity"""

---

📄 Document Management

Document Storage & Retrieval

class DocumentService:
    """Handle document storage and retrieval"""
    
    async def save_document(self, user_id: str, app_id: str, doc_type: str, content: str) -> None:
        """Save generated document (research, resume, cover letter)"""
        
    async def get_document(self, user_id: str, app_id: str, doc_type: str) -> Document:
        """Retrieve document for viewing/editing"""
        
    async def update_document(self, user_id: str, app_id: str, doc_type: str, content: str) -> None:
        """Update document after user editing"""
        
    async def get_all_documents(self, user_id: str, app_id: str) -> ApplicationDocuments:
        """Get all documents for an application"""

Document Models

class Document(BaseModel):
    """Base document model"""
    id: str
    application_id: str
    document_type: str  # research_report, optimized_resume, cover_letter
    content: str
    created_at: datetime
    updated_at: datetime

class ApplicationDocuments(BaseModel):
    """All documents for an application"""
    research_report: Optional[Document] = None
    optimized_resume: Optional[Document] = None
    cover_letter: Optional[Document] = None

Database Schema (Documents)

CREATE TABLE documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    application_id UUID REFERENCES applications(id) ON DELETE CASCADE,
    document_type VARCHAR(50) NOT NULL,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

CREATE POLICY user_documents_policy ON documents
    FOR ALL TO application_user
    USING (
        application_id IN (
            SELECT id FROM applications 
            WHERE user_id = current_setting('app.current_user_id')::UUID
        )
    );

---

🎨 Frontend Interface (Dash + Mantine)

Main Application Layout

class JobForgeApp:
    """Main Dash application layout"""
    
    def create_layout(self):
        return dmc.MantineProvider([
            dmc.AppShell([
                dmc.Navbar([
                    ApplicationSidebar()
                ], width={"base": 300}),
                dmc.Main([
                    ApplicationTopBar(),
                    MainContent()
                ])
            ])
        ])

Application Sidebar

class ApplicationSidebar:
    """Sidebar with applications list and navigation"""
    
    def render(self, user_id: str):
        return dmc.Stack([
            # New Application Button
            dmc.Button(
                "➕ New Application",
                id="new-app-btn",
                fullWidth=True,
                variant="filled"
            ),
            
            # Applications List
            dmc.Title("Applications", order=4),
            dmc.ScrollArea([
                ApplicationCard(app) for app in self.get_user_applications(user_id)
            ]),
            
            # Resume Library Section
            dmc.Divider(),
            dmc.Title("Resume Library", order=4),
            ResumeLibrarySection()
        ])

class ApplicationCard:
    """Individual application card in sidebar"""
    
    def render(self, application: Application):
        return dmc.Card([
            dmc.Group([
                dmc.Text(application.company_name, weight=600),
                StatusBadge(application.status)
            ]),
            dmc.Text(application.role_title, size="sm", color="dimmed"),
            dmc.Text(application.created_at.strftime("%Y-%m-%d"), size="xs")
        ], id=f"app-card-{application.id}")

Application Top Bar Navigation

class ApplicationTopBar:
    """Top navigation bar for application phases"""
    
    def render(self, application: Application):
        return dmc.Group([
            # Phase Navigation Buttons
            PhaseButton("Research", "research", application.research_completed),
            PhaseButton("Resume", "resume", application.resume_optimized),
            PhaseButton("Cover Letter", "cover_letter", application.cover_letter_generated),
            
            # Application Actions
            dmc.Spacer(),
            dmc.ActionIcon(
                DashIconify(icon="tabler:settings"),
                id="app-settings-btn"
            )
        ])

class PhaseButton:
    """Navigation button for each phase"""
    
    def render(self, label: str, phase: str, completed: bool):
        icon = "tabler:check" if completed else "tabler:clock"
        color = "green" if completed else "gray"
        
        return dmc.Button([
            DashIconify(icon=icon),
            dmc.Text(label, ml="xs")
        ], 
        variant="subtle" if not completed else "filled",
        color=color,
        id=f"phase-{phase}-btn"
        )

Document Editor Interface

class DocumentEditor:
    """Markdown document editor with preview"""
    
    def render(self, document: Document):
        return dmc.Container([
            dmc.Grid([
                # Editor Column
                dmc.Col([
                    dmc.Title(f"Edit {document.document_type.replace('_', ' ').title()}", order=3),
                    dmc.Textarea(
                        value=document.content,
                        placeholder="Document content...",
                        minRows=20,
                        autosize=True,
                        id=f"editor-{document.document_type}"
                    ),
                    dmc.Group([
                        dmc.Button("Save Changes", id="save-btn"),
                        dmc.Button("Cancel", variant="outline", id="cancel-btn")
                    ])
                ], span=6),
                
                # Preview Column
                dmc.Col([
                    dmc.Title("Preview", order=3),
                    dmc.Container([
                        dcc.Markdown(document.content, id="preview-content")
                    ], style={"border": "1px solid #e0e0e0", "padding": "1rem", "minHeight": "500px"})
                ], span=6)
            ])
        ])

---

🗄️ MVP Database Schema

Complete Database Setup

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS vector;

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    full_name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Applications table
CREATE TABLE applications (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    company_name VARCHAR(255) NOT NULL,
    role_title VARCHAR(255) NOT NULL,
    job_url TEXT,
    job_description TEXT NOT NULL,
    location VARCHAR(255),
    priority_level VARCHAR(20) DEFAULT 'medium',
    status VARCHAR(50) DEFAULT 'draft',
    
    research_completed BOOLEAN DEFAULT FALSE,
    resume_optimized BOOLEAN DEFAULT FALSE,
    cover_letter_generated BOOLEAN DEFAULT FALSE,
    
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Documents table
CREATE TABLE documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    application_id UUID REFERENCES applications(id) ON DELETE CASCADE,
    document_type VARCHAR(50) NOT NULL,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    
    UNIQUE(application_id, document_type)
);

-- Resume library table
CREATE TABLE user_resumes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    focus_area VARCHAR(100),
    is_primary BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Basic vector embeddings (for future enhancement)
CREATE TABLE document_embeddings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
    embedding vector(1536),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Row Level Security
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE applications ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE user_resumes ENABLE ROW LEVEL SECURITY;

-- Security policies
CREATE POLICY user_own_data ON applications FOR ALL USING (user_id = current_setting('app.current_user_id')::UUID);
CREATE POLICY user_own_documents ON documents FOR ALL USING (
    application_id IN (SELECT id FROM applications WHERE user_id = current_setting('app.current_user_id')::UUID)
);
CREATE POLICY user_own_resumes ON user_resumes FOR ALL USING (user_id = current_setting('app.current_user_id')::UUID);

---

🚀 Web Application Development Plan

Development Phases

Phase 1: Infrastructure & Authentication (Weeks 1-2)

• Docker containerization for development and production
• PostgreSQL 16 with pgvector extension setup
• FastAPI backend with JWT authentication
• Row Level Security (RLS) implementation
• Basic CI/CD pipeline setup

Phase 2: Core Web Application (Weeks 3-4)

• Dash + Mantine responsive web interface
• Application CRUD operations with API endpoints
• User dashboard and application management
• Database integration with async operations
• Multi-tenant data isolation

Phase 3: AI Integration (Weeks 5-6)

• Claude API integration for document generation
• OpenAI API for embeddings and analysis
• Async AI service layer implementation
• Error handling and retry mechanisms
• AI service rate limiting and monitoring

Phase 4: Production Deployment (Weeks 7-8)

• Server deployment with Docker Compose
• Nginx reverse proxy and SSL configuration
• Database backup and monitoring setup
• Performance optimization and caching
• Security hardening and testing

Prototype Success Criteria

• ✅ Secure multi-user web application deployed to server
• ✅ JWT-based authentication with user registration/login
• ✅ Full CRUD operations for job applications
• ✅ AI-powered cover letter generation via web interface
• ✅ Responsive web UI with modern UX design
• ✅ Secure data storage with user isolation (RLS)
• ✅ Production-ready deployment with monitoring
• ✅ Scalable architecture for future enhancements

---

🐳 Docker Production Deployment

Production Environment

# docker-compose.yml
version: '3.8'

services:
  # FastAPI + Dash Web Application
  jobforge-app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    container_name: jobforge-app
    environment:
      - DATABASE_URL=postgresql://jobforge:${DB_PASSWORD}@postgres:5432/jobforge
      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - JWT_SECRET=${JWT_SECRET}
      - DEBUG=false
      - LOG_LEVEL=INFO
    volumes:
      - ./uploads:/app/uploads
      - ./logs:/var/log/jobforge
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - jobforge-network
    restart: unless-stopped

  # PostgreSQL with pgvector
  postgres:
    image: pgvector/pgvector:pg16
    container_name: jobforge-postgres
    environment:
      - POSTGRES_DB=jobforge
      - POSTGRES_USER=jobforge
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups
    networks:
      - jobforge-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U jobforge -d jobforge"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Nginx Reverse Proxy
  nginx:
    image: nginx:alpine
    container_name: jobforge-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - jobforge-app
    networks:
      - jobforge-network
    restart: unless-stopped

networks:
  jobforge-network:
    driver: bridge

volumes:
  postgres_data:
    driver: local

---

📁 Web Application Project Structure

job-forge/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── pytest.ini
├── alembic.ini
├── CLAUDE.md
├── README.md
├── app/
│   ├── main.py                 # FastAPI + Dash application entry
│   ├── core/
│   │   ├── config.py          # Application configuration
│   │   ├── database.py        # Database connection and session
│   │   ├── security.py        # JWT authentication utilities
│   │   └── exceptions.py      # Custom exception handlers
│   ├── api/
│   │   ├── v1/
│   │   │   ├── auth.py         # Authentication endpoints
│   │   │   ├── applications.py # Application CRUD endpoints
│   │   │   └── documents.py    # Document management endpoints
│   │   └── dependencies.py     # FastAPI dependencies
│   ├── models/
│   │   ├── user.py            # User SQLAlchemy model
│   │   ├── application.py     # Application SQLAlchemy model
│   │   └── document.py        # Document SQLAlchemy model
│   ├── schemas/
│   │   ├── user.py            # User Pydantic schemas
│   │   ├── application.py     # Application Pydantic schemas
│   │   └── auth.py            # Authentication schemas
│   ├── crud/
│   │   ├── user.py            # User database operations
│   │   ├── application.py     # Application database operations
│   │   └── document.py        # Document database operations
│   ├── services/
│   │   ├── auth.py            # Authentication service
│   │   ├── application.py     # Application business logic
│   │   └── ai/
│   │       ├── claude_service.py    # Claude API integration
│   │       ├── openai_service.py    # OpenAI API integration
│   │       └── document_generator.py # AI document generation
│   └── frontend/
│       ├── app.py             # Dash application setup
│       ├── layouts/
│       │   ├── dashboard.py   # Main dashboard layout
│       │   ├── auth.py        # Login/register layouts
│       │   └── application.py # Application detail layout
│       ├── components/
│       │   ├── navigation.py  # Navigation components
│       │   ├── forms.py       # Form components
│       │   └── modals.py      # Modal components
│       └── callbacks/
│           ├── auth.py        # Authentication callbacks
│           ├── application.py # Application callbacks
│           └── navigation.py  # Navigation callbacks
├── alembic/
│   ├── versions/              # Database migration files
│   └── env.py                 # Alembic configuration
├── tests/
│   ├── conftest.py           # Pytest configuration and fixtures
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
├── docs/
│   ├── README.md             # Main documentation hub
│   ├── development/          # Development documentation
│   ├── infrastructure/       # Deployment documentation
│   └── testing/              # Testing documentation
├── nginx/
│   └── nginx.conf            # Nginx configuration
├── logs/                     # Application logs
├── uploads/                  # File uploads
└── backups/                  # Database backups

---

This web application architecture provides a comprehensive, production-ready solution for AI-powered job application management. The FastAPI backend with Dash frontend delivers a modern web experience while maintaining scalability and security for prototype development and future enhancements.