# chandrima0503/ats-ai architecture

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

- Interactive diagram: https://gitdiagram.com/chandrima0503/ats-ai
- Repository: https://github.com/chandrima0503/ats-ai

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered Applicant Tracking System (ATS).
- Frontend: Vue 3 + Vite single-page application for uploading resumes, creating job postings, and viewing ranked candidates.
- Backend: Python FastAPI service that parses PDF resumes, generates embeddings, stores them in ChromaDB, and ranks resumes against job descriptions.

##### File Structure Analysis
- Top-level:
- backend/ – FastAPI application
– app/core/config.py (configuration)
– app/main.py (entry point, mounts routes)
– app/routes/{jobs.py, match.py, resumes.py} (API endpoints)
– app/services/{parser.py, embedder.py, gpt.py} (business logic)
– app/models/schemas.py (Pydantic schemas)
– data/vector_store/chroma.sqlite3 (persistent vector DB)
- frontend/ – Vue 3 app
– src/components, src/views, src/router, src/stores, src/composables/useApi.ts
– Cypress tests, Vite + TypeScript configs
- CI: .github/workflows/ci.yml
- Deployment: Dockerfile in backend/

##### Key Architectural Insights from README
- Resume upload → PDF parsing (pdfplumber + spaCy)
- Text embedding (sentence-transformers)
- Vector store in ChromaDB (SQLite persistence)
- Job descriptions embedded similarly
- Ranking resumes by vector similarity
- All operations exposed via FastAPI REST endpoints

a. Main Components
- Client Browser (SPA)
- API Gateway / FastAPI Backend
- PDF Parser Service (pdfplumber + spaCy)
- Embedding Service (Sentence Transformers + optional GPT)
- Vector Store (ChromaDB / SQLite)
- Frontend Unit & E2E Test Harness (Cypress)
- External Services (if any: e.g., model hosting or OpenAI API)
b. Relationships / Data Flow
1. User uploads PDF → HTTP POST to /resumes/upload
2. FastAPI controller invokes Parser Service → extracted text & metadata
3. Text passed to Embedder Service → vector generated
4. Vector + metadata stored in ChromaDB (SQLite file)
5. User submits job description → similar pipeline (embed + store)
6. Ranking request → Backend queries ChromaDB for nearest vectors → returns ranked results
7. Frontend displays results
c. Architectural Patterns
- Layered architecture: Controllers (routes) → Services → Data Store
- Separation of concerns: Parsing, embedding, storage, API routing
- Persistent vector store (ChromaDB) for fast similarity queries
d. Technologies / Frameworks
- Frontend: Vue 3, Vite, Vue Router, Pinia, Axios (useApi.ts), Cypress
- Backend: Python 3.11, FastAPI, uvicorn, Pydantic, spaCy, pdfplumber, sentence-transformers, chromadb
- Deployment: Docker
- CI: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Vue 3 SPA)"
        direction TB
        Client["Client Browser<br/>(SPA)"]:::frontend
        MainTS["Entry Point<br/>main.ts"]:::frontend
        AppVue["App Shell<br/>App.vue"]:::frontend
        UploadComp["Resume Upload<br/>UploadResume.vue"]:::frontend
        HomeView["Home View<br/>HomeView.vue"]:::frontend
        UseApi["API Client<br/>useApi.ts"]:::frontend
        Router["Routing Config<br/>index.ts"]:::frontend
        Store["Pinia Store<br/>counter.ts"]:::frontend
        CypressTest["E2E Tests<br/>example.cy.ts"]:::frontend

        Client -->|loads| MainTS
        MainTS --> AppVue
        AppVue --> UploadComp
        AppVue --> HomeView
        UploadComp -->|calls| UseApi
        HomeView -->|calls| UseApi
        UseApi -->|uses| Router
        UseApi -->|uses| Store
        CypressTest -->|tests| Client
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        direction TB
        APIMain["API Gateway<br/>main.py"]:::backend
        Config["Config<br/>config.py"]:::backend
        subgraph "Routes"
            direction TB
            ResumesRoute["Resumes Routes<br/>resumes.py"]:::backend
            JobsRoute["Job Routes<br/>jobs.py"]:::backend
            MatchRoute["Match Routes<br/>match.py"]:::backend
        end
        subgraph "Services"
            direction TB
            ParserSvc["Parser Service<br/>parser.py"]:::service
            EmbedSvc["Embedding Service<br/>embedder.py"]:::service
            GPTSvc["GPT Helper Service<br/>gpt.py"]:::service
        end
        Schemas["Schemas<br/>schemas.py"]:::backend
        Dockerfile["Dockerfile"]:::backend
    end

    %% Data Layer
    ChromaDB["ChromaDB (SQLite)<br/>chroma.sqlite3"]:::db

    %% External Dependencies
    subgraph "External Models & Libs"
        direction TB
        PDFPlumb["pdfplumber"]:::external
        spaCy["spaCy"]:::external
        Transformers["sentence-transformers"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Connections
    Client -->|POST /resumes/upload| APIMain
    Client -->|POST /jobs| APIMain
    Client -->|GET /match| APIMain

    APIMain -->|includes| Config
    APIMain -->|routes to| ResumesRoute
    APIMain -->|routes to| JobsRoute
    APIMain -->|routes to| MatchRoute

    ResumesRoute -->|invokes| ParserSvc
    ResumesRoute -->|invokes| EmbedSvc
    ResumesRoute -->|uses| Schemas

    JobsRoute -->|invokes| EmbedSvc
    JobsRoute -->|uses| Schemas

    MatchRoute -->|queries| ChromaDB
    MatchRoute -->|uses| Schemas

    ParserSvc -->|uses| PDFPlumb
    ParserSvc -->|uses| spaCy
    ParserSvc -->|outputs text| EmbedSvc

    EmbedSvc -->|uses| Transformers
    EmbedSvc -->|optional LLM calls| GPTSvc

    GPTSvc -->|uses| OpenAIAPI

    EmbedSvc -->|stores vectors| ChromaDB

    ChromaDB -->|persistent store| Dockerfile

    %% Click Events
    click Client "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/main.ts"
    click MainTS "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/main.ts"
    click AppVue "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/App.vue"
    click UploadComp "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/components/UploadResume.vue"
    click HomeView "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/views/HomeView.vue"
    click UseApi "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/composables/useApi.ts"
    click Router "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/router/index.ts"
    click Store "https://github.com/chandrima0503/ats-ai/blob/master/frontend/src/stores/counter.ts"
    click CypressTest "https://github.com/chandrima0503/ats-ai/blob/master/frontend/cypress/e2e/example.cy.ts"
    click APIMain "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/main.py"
    click Config "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/core/config.py"
    click ResumesRoute "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/routes/resumes.py"
    click JobsRoute "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/routes/jobs.py"
    click MatchRoute "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/routes/match.py"
    click ParserSvc "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/services/parser.py"
    click EmbedSvc "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/services/embedder.py"
    click GPTSvc "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/services/gpt.py"
    click Schemas "https://github.com/chandrima0503/ats-ai/blob/master/backend/app/models/schemas.py"
    click ChromaDB "https://github.com/chandrima0503/ats-ai/blob/master/backend/data/vector_store/chroma.sqlite3"
    click Dockerfile "https://github.com/chandrima0503/ats-ai/tree/master/backend/Dockerfile"
    click CI "https://github.com/chandrima0503/ats-ai/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#01579B,color:#000
    classDef backend fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef service fill:#FFF9C4,stroke:#F9A825,color:#000
    classDef db fill:#FFCCBC,stroke:#E64A19,color:#000
    classDef external fill:#E1BEE7,stroke:#6A1B9A,color:#000
```
