# saiprasaad2002/job-application-agent-mcp architecture

> Architecture diagram of the GitHub repository saiprasaad2002/job-application-agent-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saiprasaad2002/job-application-agent-mcp
- Repository: https://github.com/saiprasaad2002/job-application-agent-mcp

## Overview

##### Project’s Main Components
- FastAPI Server: The core HTTP server defined in main.py that handles incoming requests on endpoints such as POST /job-application.
- MCP Server and Agents: An extension of the FastAPI app mounted under the /mcp path. It exposes several agent endpoints (e.g., /mcp/extract_text, /mcp/generate_summary, /mcp/calculate_score, etc.) which encapsulate the business logic using the Model Context Protocol for a multi-agent orchestration.
- Database Layer: Implemented in database.py, likely handling initialization and interactions with a SQLite database via SQLAlchemy. This layer stores applications and error logs.
- File Handling Component: Involved in receiving and storing uploaded resumes (note the README mentions an uploads/ directory even if it’s not in the file tree) and processing document formats using libraries like PyMuPDF and python-docx.
- External Services / Libraries: Integration points for email notifications using the Resend API, natural language processing modules (e.g., sentence-transformers for semantic scoring), and LLM services using ollama for summarization.

##### Relationships and Interaction Flow
- When a job application is submitted via the /job-application endpoint, the FastAPI server triggers a chain of operations orchestrated by the MCP layer.
- The workflow involves:
a. Document validation and text extraction (handled by an MCP agent: extract_text),
b. Duplicate checking (using check_existing_application),
c. Job description summarization (generate_summary via LLM),
d. Semantic scoring (calculate_score using sentence-transformers),
e. Email extraction (extract_email), and
f. Finally, sending an email invitation (send_email or send_interview_invitation if scores are 70% or above).
- The results of these operations, along with any errors generated, are persisted in the SQLite database.

##### Architectural Patterns and Design Principles
- Modularity: The system divides responsibilities among specialized agents. Each agent (e.g., resume extraction, duplicate detection) is an independent module that could be tested or extended separately.
- Separation of Concerns: Clear segmentation between API layer (FastAPI endpoints), business logic (MCP agents), and data persistence (SQLAlchemy with SQLite).
- Workflow Orchestration: The specialized MCP-based orchestration allows for flexible workflows and extension points in a multi-agent environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client (HTTP Request)"]:::client
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        FASTAPI["FastAPI Server (/job-application)"]:::api
        FileHandler["File Handler (Resume Uploads)"]:::file
    end

    %% Workflow Orchestration Layer
    subgraph "Workflow Orchestration"
        MCP["MCP Server (/mcp)"]:::api
        ExtractText["Extract Text Agent (/mcp/extract_text)"]:::agent
        DuplicateCheck["Duplicate Check Agent"]:::agent
        GenerateSummary["Generate Summary Agent (/mcp/generate_summary)"]:::agent
        CalculateScore["Calculate Score Agent (/mcp/calculate_score)"]:::agent
        ExtractEmail["Extract Email Agent (/mcp/extract_email)"]:::agent
        SendEmail["Send Email Agent (/mcp/send_email)"]:::agent
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        SQLiteDB["SQLite Database (Applications, Error Logs)"]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        LLM["LLM Service (Ollama)"]:::external
        NLP["NLP Service (Sentence-Transformers)"]:::external
        EmailService["Email Service (Resend API)"]:::external
    end

    %% Connections
    Client -->|"HTTP_Request"| FASTAPI
    FASTAPI -->|"store_resume"| FileHandler
    FASTAPI -->|"trigger_workflow"| MCP

    MCP -->|"extract"| ExtractText
    ExtractText -->|"check_duplicate"| DuplicateCheck
    DuplicateCheck -->|"summarize"| GenerateSummary
    GenerateSummary -->|"score"| CalculateScore
    CalculateScore -->|"extract_email"| ExtractEmail
    ExtractEmail -->|"send_email"| SendEmail

    %% External Service Integrations
    GenerateSummary -->|"LLM_call"| LLM
    CalculateScore -->|"NLP_call"| NLP
    SendEmail -->|"email_notify"| EmailService

    %% Persistence
    SendEmail -->|"persist"| SQLiteDB

    %% Click Events
    click FASTAPI "https://github.com/saiprasaad2002/job-application-agent-mcp/blob/main/main.py"
    click MCP "https://github.com/saiprasaad2002/job-application-agent-mcp/blob/main/main.py"
    click SQLiteDB "https://github.com/saiprasaad2002/job-application-agent-mcp/blob/main/database.py"

    %% Styles
    classDef client fill:#fc9,stroke:#333,stroke-width:2px;
    classDef api fill:#f9f,stroke:#333,stroke-width:2px;
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px;
    classDef file fill:#9ff,stroke:#333,stroke-width:2px;
    classDef database fill:#afa,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9,stroke:#333,stroke-width:2px;
```
