# tanyaignatenko/resume-parser architecture

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

- Interactive diagram: https://gitdiagram.com/tanyaignatenko/resume-parser
- Repository: https://github.com/tanyaignatenko/resume-parser

## Overview

##### Project Type & Purpose
- This is a **full-stack AI-powered Resume Parser**.
- Frontend: Next.js/React web app for upload & display.
- Backend: FastAPI service hosting a custom spaCy NER model.
- Training: spaCy training pipeline driven by Python scripts and an annotated resume dataset.
- Deployment: Frontend + Backend on Vercel (backend configured via vercel.json).

##### File-Structure Snapshot & Architectural Clues
- **backend/**
- main.py, api/index.py → FastAPI entrypoints
- model/… → spaCy model artifacts (cfg, vocab, tokenizer, ner weights)
- requirements.txt, vercel.json → dependencies & deployment config
- **frontend/**
- app/** → Next.js pages (upload page, results page)
- components/** → React UI components & custom UI library
- lib/api.ts → client utilities to call the backend
- next.config.mjs, package.json → build & framework config
- **training/**
- annotated/*.json → train/dev/test splits
- *.py scripts → data preprocessing, pre-labeling, spaCy training
- No external database—model artifacts and data live in-repo; uses pdfplumber & docx2txt for file parsing.

##### Key Architecture Elements
a. **Frontend (Next.js + React)**
- UI pages: Upload form, Results view
- API client: POST “/parse” endpoint
b. **Backend (FastAPI + Uvicorn)**
- **API Layer**: parse endpoint defined in api/index.py
- **Processing Pipeline**:
1. File ingestion (PDF/DOCX/TXT)
2. Text extraction via pdfplumber/docx2txt
3. Text cleaning & normalization
4. Tokenization & spaCy NER inference (load from backend/model)
5. Schema mapping (Skills, Experience, Education, Languages) → JSON
c. **Model Storage**
- spaCy model directory containing cfg, tokenizer, vocab, ner weights
d. **Training Pipeline (Offline)**
- Annotation: Label Studio → annotated/*.json
- Preprocessing & pre-label scripts (ls_to_spacy.py, make_prelabels.py)
- Training: train_ner.py using spaCy’s CLI or API
- Evaluation: show_mismatches.py, reporting F1/Precision/Recall

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Client["User Browser"]:::external
        UploadPage["Upload Page"]:::frontend
        ResultsPage["Results Page"]:::frontend
        UIComponents["React UI Components"]:::frontend
        APIClient["API Client Utilities"]:::frontend
        GlobalStyles["Global Styles & Layout"]:::frontend
        FrameworkConfig["Framework Config"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        FastAPIEntry["FastAPI Entry Point\n(main.py)"]:::backend
        APIIndex["API Layer\n(/parse endpoint)"]:::backend
        ModelStore["Model Artifact Store"]:::backend
        BackendConfig["Deployment Config & Dependencies"]:::backend
    end

    %% ML Inference Subsystem
    subgraph "ML Inference" 
        direction TB
        ParserLib["File Parser Library\n(pdfplumber/docx2txt)"]:::ml
        CleanNorm["Text Cleaning & Normalization"]:::ml
        SpaCyNER["spaCy NER Inference"]:::ml
    end

    %% Training Pipeline (Offline)
    subgraph "Training Pipeline (Offline)" 
        direction TB
        AnnotatedData["Annotated Dataset Splits"]:::data
        CleanScript["Text Cleaning Script"]:::data
        Converter["Label-Studio to spaCy Converter"]:::data
        Prelabel["Pre-label Generation Script"]:::data
        TrainNER["spaCy NER Training Script"]:::data
        EvalReport["Evaluation & Mismatch Reporting"]:::data
        AnnotatedData --> CleanScript --> Converter --> Prelabel --> TrainNER --> EvalReport --> ModelStore
    end

    %% Deployment
    Vercel["Vercel Deployment"]:::deployment

    %% Connections Frontend to Backend
    Client -->|"opens"| UploadPage
    UploadPage -->|"submits file"| APIClient
    APIClient -->|"HTTP POST /parse"| FastAPIEntry
    FastAPIEntry --> APIIndex
    APIIndex -->|"file ingestion"| ParserLib
    ParserLib --> CleanNorm
    CleanNorm --> SpaCyNER
    SpaCyNER -->|"entities JSON"| APIIndex
    APIIndex -->|"JSON response"| APIClient
    APIClient --> ResultsPage

    %% Model store usage
    SpaCyNER --> ModelStore

    %% Deployment flows
    FrontendLayerDeploy["Frontend Code"]:::deployment
    BackendLayerDeploy["Backend Code"]:::deployment
    FrontendLayerDeploy -.-> Vercel
    BackendLayerDeploy -.-> Vercel

    %% Click Events
    click UploadPage "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/app/page.tsx"
    click ResultsPage "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/app/results/page.tsx"
    click UIComponents "https://github.com/tanyaignatenko/resume-parser/tree/main/frontend/components/"
    click APIClient "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/lib/api.ts"
    click GlobalStyles "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/app/globals.css"
    click GlobalStyles "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/app/layout.tsx"
    click FrameworkConfig "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/next.config.mjs"
    click FrameworkConfig "https://github.com/tanyaignatenko/resume-parser/blob/main/frontend/package.json"
    click FastAPIEntry "https://github.com/tanyaignatenko/resume-parser/blob/main/backend/main.py"
    click APIIndex "https://github.com/tanyaignatenko/resume-parser/blob/main/backend/api/index.py"
    click ModelStore "https://github.com/tanyaignatenko/resume-parser/tree/main/backend/model/"
    click BackendConfig "https://github.com/tanyaignatenko/resume-parser/blob/main/backend/vercel.json"
    click BackendConfig "https://github.com/tanyaignatenko/resume-parser/blob/main/backend/requirements.txt"
    click AnnotatedData "https://github.com/tanyaignatenko/resume-parser/blob/main/training/annotated/train.json"
    click AnnotatedData "https://github.com/tanyaignatenko/resume-parser/blob/main/training/annotated/dev.json"
    click AnnotatedData "https://github.com/tanyaignatenko/resume-parser/blob/main/training/annotated/test.json"
    click CleanScript "https://github.com/tanyaignatenko/resume-parser/blob/main/training/apply_clean_text.py"
    click Converter "https://github.com/tanyaignatenko/resume-parser/blob/main/training/ls_to_spacy.py"
    click Prelabel "https://github.com/tanyaignatenko/resume-parser/blob/main/training/make_prelabels.py"
    click TrainNER "https://github.com/tanyaignatenko/resume-parser/blob/main/training/train_ner.py"
    click EvalReport "https://github.com/tanyaignatenko/resume-parser/blob/main/training/show_mismatches.py"

    %% Styles
    classDef frontend fill:#b2f2bb,stroke:#2f9e44,color:#000
    classDef backend fill:#aedcff,stroke:#228be6,color:#000
    classDef ml fill:#ffd8a8,stroke:#f76707,color:#000
    classDef data fill:#e9ecef,stroke:#868e96,color:#000
    classDef deployment fill:#dee2e6,stroke:#495057,color:#000
    classDef external fill:#fff3bf,stroke:#f08c00,color:#000
```
