# hamzaqadeer01/resume-matcher architecture

> Architecture diagram of the GitHub repository hamzaqadeer01/resume-matcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamzaqadeer01/resume-matcher
- Repository: https://github.com/hamzaqadeer01/resume-matcher

## Overview

##### Project Type and Purpose
- Full-stack web application to analyze and optimize resumes against job descriptions
- Frontend built with Next.js (React), styled with Tailwind CSS
- Backend built with FastAPI (Python), uses local AI model serving (Ollama) and SQLite

##### File Structure
- Top-level “apps/frontend” → Next.js application
- Top-level “apps/backend” → FastAPI application
– “app/api/router/v1” → REST endpoints (/job, /resume, /health)
– “app/agent” → Core AI Agent abstraction, providers (Ollama, OpenAI), strategies
– “app/services” → Business logic (job_service, resume_service, score_improvement_service)
– “app/models” & “app/schemas” → ORM models (SQLite via SQLAlchemy), Pydantic schemas, JSON schemas
– “app/core” → Configuration, database initialization, exception handling
- Configuration and deployment scripts: Makefile, setup scripts, .env.sample

##### Extract Key Insights from README
- Frontend communicates with backend over HTTP REST (Next.js API calls)
- Backend routes calls into an AI agent which generates prompts and queries local models via Ollama
- Persistence in SQLite for job postings, user resumes, match scores
- Local-first design: AI runs on user’s machine (no cloud hosting by default)

##### Main Components and Their Relationships
- User’s Browser (Web UI)
– Next.js pages & components
– File upload widget, keyword optimizer, resume previewer
– Sends HTTP requests to Backend (/api/v1)
- Backend API (FastAPI)
– API Layer: Routers → Controller methods
– Service Layer: Business logic for resume analysis, job matching, score improvement
– Agent Layer: Builds prompts, selects provider, executes model calls
– Providers: Ollama (local AI), optional OpenAI fallback
– Data Layer: SQLAlchemy models, SQLite database
- Data Store
– SQLite database file
– Tables: users, resumes, jobs, associations, scores
- AI Model Server
– Ollama local service (model hosting)
– Exposed via HTTP/gRPC to the Agent providers
- External Services (optional)
– OpenAI API as fallback provider
– Discord/LinkedIn/Twitter integration for community links (non-critical)

##### Architectural Patterns and Design Principles
- Layered Architecture (API → Services → Agent → Providers → Database)
- Separation of Concerns:
– UI vs. API vs. Business Logic vs. AI orchestration vs. Persistence
- Hexagonal/Ports-and-Adapters:
– Agent strategies and providers are swappable adapters around a common interface
- Domain-Driven Organization:
– Models and schemas grouped by domain (job, resume, user)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Next.js)" 
        Browser["Browser UI\nNext.js + Tailwind"]:::frontend
        Routes["Next.js App Routes"]:::frontend
        UIComponents["UI Components Library"]:::frontend
        FileUpload["File Upload & API Utilities"]:::frontend
        Styles["Global Styles & Config"]:::frontend
    end

    %% Backend Entry & Core Config
    subgraph "Backend Core"
        Main["main.py"]:::backend
        Config["config.py"]:::backend
        DatabaseInit["database.py"]:::backend
        ExceptionsDef["exceptions.py"]:::backend
    end

    %% API Layer
    subgraph "API Layer (FastAPI Routers v1)"
        Health["Health Router\n/health"]:::backend
        JobRouter["Job Router\n/api/v1/job"]:::backend
        ResumeRouter["Resume Router\n/api/v1/resume"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        JobService["Job Service"]:::backend
        ResumeService["Resume Service"]:::backend
        ScoreService["Score Improvement Service"]:::backend
    end

    %% AI Agent Layer
    subgraph "AI Agent Layer"
        AgentManager["Agent Manager"]:::agent
        BaseAgent["Base Agent Interface"]:::agent
        AgentExceptions["Agent Exceptions"]:::agent
        subgraph Providers
            BaseProvider["Base Provider Interface"]:::agent
            Ollama["Ollama Provider\n(local)"]:::ai
            OpenAI["OpenAI Provider\n(fallback)"]:::external
        end
        subgraph Strategies
            BaseStrategy["Base Strategy"]:::agent
            WrapperStrategy["Wrapper Strategy"]:::agent
        end
        subgraph Prompts
            PromptBase["Prompt Base Interface"]:::agent
            JobPrompt["Structured Job Prompt"]:::agent
            ResumePrompt["Structured Resume Prompt"]:::agent
            ImprovePrompt["Resume Improvement Prompt"]:::agent
        end
    end

    %% Data Layer
    subgraph "Data Layer (SQLite/SQLAlchemy)"
        DB["SQLite Database"]:::data
        Models["ORM Models"]:::data
        Schemas["Schemas\n(Pydantic/JSON)"]:::data
    end

    %% External Services
    subgraph External
        AIserver["Ollama Local AI Server"]:::ai
        Discord["Discord/Twitter/LinkedIn Integration"]:::external
    end

    %% Connections
    Browser -->|REST| Health
    Browser -->|REST| JobRouter
    Browser -->|REST| ResumeRouter

    Main --> Health
    Main --> JobRouter
    Main --> ResumeRouter

    JobRouter -->|calls| JobService
    ResumeRouter -->|calls| ResumeService
    ResumeRouter -->|calls| ScoreService

    JobService -->|uses| AgentManager
    ResumeService -->|uses| AgentManager
    ScoreService -->|uses| AgentManager

    AgentManager --> BaseAgent
    AgentManager --> AgentExceptions
    BaseAgent --> BaseProvider
    BaseProvider --> Ollama
    BaseProvider --> OpenAI

    AgentManager --> BaseStrategy
    AgentManager --> WrapperStrategy

    AgentManager --> PromptBase
    PromptBase --> JobPrompt
    PromptBase --> ResumePrompt
    PromptBase --> ImprovePrompt

    BaseProvider -->|gRPC/HTTP| AIserver
    OpenAI -->|HTTPS| OpenAI
    JobService -->|SQL| DB
    ResumeService -->|SQL| DB
    ScoreService -->|SQL| DB
    DB --> Models
    DB --> Schemas

    %% Click Events
    click Browser "https://github.com/hamzaqadeer01/resume-matcher/tree/main/apps/frontend/"
    click Routes "https://github.com/hamzaqadeer01/resume-matcher/tree/main/apps/frontend/app/(default)/"
    click UIComponents "https://github.com/hamzaqadeer01/resume-matcher/tree/main/apps/frontend/components/"
    click FileUpload "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/frontend/hooks/use-file-upload.ts"
    click Styles "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/frontend/app/(default)/css/globals.css"

    click Main "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/main.py"
    click Config "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/core/config.py"
    click DatabaseInit "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/core/database.py"
    click ExceptionsDef "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/core/exceptions.py"

    click Health "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/api/router/health.py"
    click JobRouter "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/api/router/v1/job.py"
    click ResumeRouter "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/api/router/v1/resume.py"

    click JobService "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/services/job_service.py"
    click ResumeService "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/services/resume_service.py"
    click ScoreService "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/services/score_improvement_service.py"

    click AgentManager "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/manager.py"
    click AgentExceptions "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/exceptions.py"
    click BaseAgent "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/__init__.py"

    click BaseProvider "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/providers/base.py"
    click Ollama "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/providers/ollama.py"
    click OpenAI "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/providers/openai.py"

    click BaseStrategy "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/strategies/base.py"
    click WrapperStrategy "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/agent/strategies/wrapper.py"

    click PromptBase "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/prompt/base.py"
    click JobPrompt "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/prompt/structured_job.py"
    click ResumePrompt "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/prompt/structured_resume.py"
    click ImprovePrompt "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/prompt/resume_improvement.py"

    click Models "https://github.com/hamzaqadeer01/resume-matcher/blob/main/apps/backend/app/models/base.py"
    click Schemas "https://github.com/hamzaqadeer01/resume-matcher/tree/main/apps/backend/app/schemas/pydantic/"

    %% Styles
    classDef frontend fill:#C6E0FF,stroke:#0366d6,color:#000
    classDef backend fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef agent fill:#E0B0FF,stroke:#8A2BE2,color:#000
    classDef ai fill:#D6CADD,stroke:#7B68EE,color:#000
    classDef data fill:#FFE7B2,stroke:#E69A17,color:#000
    classDef external fill:#F0F0F0,stroke:#A0A0A0,color:#000
```
