# m-coder-umer/resume_analyzer architecture

> Architecture diagram of the GitHub repository m-coder-umer/resume_analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-coder-umer/resume_analyzer
- Repository: https://github.com/m-coder-umer/resume_analyzer

## Overview

1. This repository is a resume screening and candidate ranking system built around two entry points: a FastAPI backend for API-driven workflow execution and a Streamlit UI for recruiter-facing interaction. The backend is the system of record; the UI is a consumer of its endpoints.

2. The central orchestration boundary is `src/pipeline.py`. It coordinates the end-to-end flow across ingestion, extraction, job analysis, matching, ranking, and persistence, rather than letting API handlers talk to each subsystem directly.

3. Resume ingestion starts in `src/ingestion/`, where PDF resumes are parsed into text. That text becomes the input to extraction. The repository includes sample PDFs and extracted text under `data/sample_resumes`, which suggests a batch-processing workflow with file-based inputs.

4. Candidate extraction is split into two strategies in `src/extraction/`: a rule-based extractor for deterministic fields and an LLM-based extractor for richer structured output. The README indicates Groq-hosted Llama is used for the LLM path, with skill verification to reduce hallucinated skills.

5. Job-description analysis lives in `src/jobspec/jd_analyzer.py`. This subsystem turns a free-form job description into structured job requirements that the matching layer can consume, creating a symmetric representation between “candidate profile” and “job spec.”

6. Matching is intentionally hybrid. `src/matching/keyword_matcher.py` scores explicit skill overlap, while `src/matching/semantic_matcher.py` uses embeddings for similarity. `src/ranking/scorer.py` combines those signals with experience fit into the final score, producing explainable output rather than a black-box rank.

7. Persistence is split by data type. `src/storage/db.py` wraps SQLite for structured entities like candidates, jobs, batches, and match results, while `src/storage/vector_store.py` wraps ChromaDB for embedding storage and similarity lookup. The checked-in `data/` directory shows both the SQLite database and Chroma persistence files, so these are durable local stores rather than ephemeral caches.

8. The system has an asynchronous batch-processing model. Resume uploads create a batch, then each resume is processed independently with progress tracked by batch ID. The README notes Celery + Redis as the preferred background-task path, with an asyncio fallback, which means processing is decoupled from request/response time.

9. API routing is separated by domain in `src/api/`: resumes, jobs, matching, and admin. These endpoints expose the pipeline as a set of coarse-grained actions: upload resumes, inspect batch status, analyze a job, trigger matching, and fetch ranked results.

10. Shared contracts and runtime configuration live in `src/core/`. `schemas.py` defines the Pydantic data models that stabilize boundaries between API, pipeline, and storage; `config.py` centralizes environment-driven settings like database URL, embedding model, and scoring weights; `exceptions.py` provides domain-specific error handling.

11. `src/main.py` is the FastAPI application bootstrap, while `src/ui/app.py` is the separate Streamlit front end. This makes the system a two-process architecture: a backend service for computation and persistence, and a client app for visualization and human review.

12. The repository’s `tests/` focus on API behavior, which reflects the architecture’s public surface area being the HTTP contract. Overall, the key diagram should show a request-driven API layer, an orchestration/pipeline layer, specialized NLP/matching subsystems, and two storage backends: SQLite for records and ChromaDB for embeddings.

Main entry points: [`src/pipeline.py`](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/pipeline.py) (Pipeline), [`src/core/schemas.py`](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/schemas.py) (Schemas), [`src/main.py`](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/main.py) (Main app), [`src/ui/app.py`](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ui/app.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["API layer"]
  node_node_main(("Main app<br/>FastAPI bootstrap<br/>[main.py]"))
  node_node_api_resumes["Resume API<br/>HTTP routes<br/>[resumes.py]"]
  node_node_api_jobs["Job API<br/>HTTP routes<br/>[jobs.py]"]
  node_node_api_matching["Match API<br/>HTTP routes<br/>[matching.py]"]
  node_node_api_admin["Admin API<br/>HTTP routes<br/>[admin.py]"]
end

subgraph group_group_pipeline["Orchestration"]
  node_node_pipeline{{"Pipeline<br/>orchestrator<br/>[pipeline.py]"}}
  node_node_ingestion["PDF ingestion<br/>parser<br/>[pdf_extractor.py]"]
end

subgraph group_group_nlp["NLP and matching"]
  node_node_extraction_rule["Rule extractor<br/>structured extraction<br/>[rule_base.py]"]
  node_node_extraction_llm["LLM extractor<br/>structured extraction<br/>[llm_extractor.py]"]
  node_node_jd_analyzer["JD analyzer<br/>job spec parser<br/>[jd_analyzer.py]"]
  node_node_keyword_matcher["Keyword match<br/>skill overlap scoring<br/>[keyword_matcher.py]"]
  node_node_semantic_matcher["Semantic match<br/>embedding similarity"]
  node_node_scorer{{"Rank scorer<br/>final scoring<br/>[scorer.py]"}}
end

subgraph group_group_storage["Storage"]
  node_node_db[("SQLite store<br/>relational persistence<br/>[db.py]")]
  node_node_vector[("Vector store<br/>embedding persistence<br/>[vector_store.py]")]
end

subgraph group_group_clients["Clients"]
  node_node_ui(("Streamlit UI<br/>frontend<br/>[app.py]"))
  node_node_workers{{"Task workers<br/>background jobs<br/>[tasks.py]"}}
end

node_node_schemas["Schemas<br/>contracts<br/>[schemas.py]"]
node_node_config["Config<br/>runtime settings<br/>[config.py]"]
node_node_exceptions["Exceptions<br/>domain errors<br/>[exceptions.py]"]

node_node_main -->|"serves"| node_node_api_resumes
node_node_main -->|"serves"| node_node_api_jobs
node_node_main -->|"serves"| node_node_api_matching
node_node_main -->|"serves"| node_node_api_admin
node_node_api_resumes -->|"starts"| node_node_pipeline
node_node_api_jobs -->|"analyzes"| node_node_jd_analyzer
node_node_api_matching -->|"triggers"| node_node_pipeline
node_node_api_admin -->|"reads"| node_node_db
node_node_pipeline -->|"ingests"| node_node_ingestion
node_node_pipeline -->|"extracts"| node_node_extraction_rule
node_node_pipeline -->|"extracts"| node_node_extraction_llm
node_node_pipeline -->|"builds spec"| node_node_jd_analyzer
node_node_pipeline -->|"scores"| node_node_keyword_matcher
node_node_pipeline -->|"scores"| node_node_semantic_matcher
node_node_pipeline -->|"ranks"| node_node_scorer
node_node_pipeline -->|"persists"| node_node_db
node_node_pipeline -->|"stores embeddings"| node_node_vector
node_node_extraction_rule -->|"emits"| node_node_schemas
node_node_extraction_llm -->|"emits"| node_node_schemas
node_node_jd_analyzer -->|"emits"| node_node_schemas
node_node_keyword_matcher -->|"consumes"| node_node_schemas
node_node_semantic_matcher -->|"queries"| node_node_vector
node_node_scorer -->|"consumes"| node_node_schemas
node_node_workers -->|"runs"| node_node_pipeline
node_node_ui -->|"calls"| node_node_api_resumes
node_node_ui -->|"calls"| node_node_api_jobs
node_node_ui -->|"calls"| node_node_api_matching
node_node_db -->|"configured by"| node_node_config
node_node_vector -->|"configured by"| node_node_config
node_node_pipeline -.->|"raises"| node_node_exceptions

click node_node_main "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/main.py"
click node_node_api_resumes "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/resumes.py"
click node_node_api_jobs "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/jobs.py"
click node_node_api_matching "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/matching.py"
click node_node_api_admin "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/admin.py"
click node_node_pipeline "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/pipeline.py"
click node_node_ingestion "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ingestion/pdf_extractor.py"
click node_node_extraction_rule "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/extraction/rule_base.py"
click node_node_extraction_llm "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/extraction/llm_extractor.py"
click node_node_jd_analyzer "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/jobspec/jd_analyzer.py"
click node_node_keyword_matcher "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/matching/keyword_matcher.py"
click node_node_semantic_matcher "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/matching/semantic_matcher.py"
click node_node_scorer "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ranking/scorer.py"
click node_node_db "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/storage/db.py"
click node_node_vector "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/storage/vector_store.py"
click node_node_ui "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ui/app.py"
click node_node_workers "https://github.com/m-coder-umer/resume_analyzer/blob/main/workers/tasks.py"
click node_node_schemas "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/schemas.py"
click node_node_config "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/config.py"
click node_node_exceptions "https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/exceptions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_api_resumes,node_node_api_jobs,node_node_api_matching,node_node_api_admin toneBlue
class node_node_pipeline,node_node_ingestion toneAmber
class node_node_extraction_rule,node_node_extraction_llm,node_node_jd_analyzer,node_node_keyword_matcher,node_node_semantic_matcher,node_node_scorer toneMint
class node_node_db,node_node_vector toneRose
class node_node_ui,node_node_workers toneIndigo
class node_node_schemas,node_node_config,node_node_exceptions toneNeutral
```

## Components

### API layer

HTTP entry points for resume, job, matching, and admin actions.

- [Main app](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/main.py): FastAPI bootstrap · Starts the backend service and wires the API application. · `src/main.py`
- [Resume API](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/resumes.py): HTTP routes · Endpoints for resume upload and batch progress. · `src/api/resumes.py`
- [Job API](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/jobs.py): HTTP routes · Endpoints for job description analysis and job-spec handling. · `src/api/jobs.py`
- [Match API](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/matching.py): HTTP routes · Endpoints that trigger matching and return ranked candidates. · `src/api/matching.py`
- [Admin API](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/api/admin.py): HTTP routes · Operational endpoints for internal inspection and control. · `src/api/admin.py`

### Orchestration

Central workflow that coordinates ingestion, extraction, analysis, matching, ranking, and persistence.

- [Pipeline](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/pipeline.py): orchestrator · Coordinates the end-to-end resume screening workflow. · `src/pipeline.py`
- [PDF ingestion](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ingestion/pdf_extractor.py): parser · Extracts text from resume PDFs for downstream processing. · `src/ingestion/pdf_extractor.py`

### NLP and matching

Resume and job understanding plus hybrid scoring.

- [Rule extractor](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/extraction/rule_base.py): structured extraction · Deterministic field extraction from resume text. · `src/extraction/rule_base.py`
- [LLM extractor](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/extraction/llm_extractor.py): structured extraction · LLM-backed resume extraction for richer candidate profiles. · `src/extraction/llm_extractor.py`
- [JD analyzer](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/jobspec/jd_analyzer.py): job spec parser · Converts free-form job descriptions into structured requirements. · `src/jobspec/jd_analyzer.py`
- [Keyword match](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/matching/keyword_matcher.py): skill overlap scoring · Scores explicit skill and requirement overlap. · `src/matching/keyword_matcher.py`
- [Semantic match](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/matching/semantic_matcher.py): embedding similarity · Uses embeddings to measure candidate-job similarity. · `src/matching/semantic_matcher.py`
- [Rank scorer](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ranking/scorer.py): final scoring · Combines matching signals and experience fit into an explainable score. · `src/ranking/scorer.py`

### Storage

Persistent stores for structured records and embeddings.

- [SQLite store](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/storage/db.py): relational persistence · Stores candidates, jobs, batches, and match results. · `src/storage/db.py`
- [Vector store](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/storage/vector_store.py): embedding persistence · Stores embeddings and supports similarity lookup via ChromaDB. · `src/storage/vector_store.py`

### Clients

Human-facing UI and background task runtime.

- [Streamlit UI](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/ui/app.py): frontend · Recruiter-facing interface for reviewing results and interacting with the backend. · `src/ui/app.py`
- [Task workers](https://github.com/m-coder-umer/resume_analyzer/blob/main/workers/tasks.py): background jobs · Asynchronous batch processing for resume screening. · `workers/tasks.py`

### Other components

- [Schemas](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/schemas.py): contracts · Pydantic models that define data boundaries across the system. · `src/core/schemas.py`
- [Config](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/config.py): runtime settings · Environment-driven settings for models, database, and scoring. · `src/core/config.py`
- [Exceptions](https://github.com/m-coder-umer/resume_analyzer/blob/main/src/core/exceptions.py): domain errors · Shared application and domain error types. · `src/core/exceptions.py`

## Connections

- Main app → Resume API: serves · Bootstraps the resume workflow endpoints.
- Main app → Job API: serves · Bootstraps the job analysis endpoints.
- Main app → Match API: serves · Bootstraps the matching endpoints.
- Main app → Admin API: serves · Bootstraps the admin endpoints.
- Resume API → Pipeline: starts · Hands uploaded resumes into the orchestration layer.
- Job API → JD analyzer: analyzes · Transforms raw job descriptions into structured specs.
- Match API → Pipeline: triggers · Runs matching and ranking through the pipeline.
- Admin API → SQLite store: reads · Exposes operational data from persistent storage.
- Pipeline → PDF ingestion: ingests · Parses resume files into text.
- Pipeline → Rule extractor: extracts · Uses deterministic extraction for core fields.
- Pipeline → LLM extractor: extracts · Uses LLM extraction for richer structured output.
- Pipeline → JD analyzer: builds spec · Converts job descriptions into matchable requirements.
- Pipeline → Keyword match: scores · Computes explicit skill overlap.
- Pipeline → Semantic match: scores · Computes embedding-based similarity.
- Pipeline → Rank scorer: ranks · Combines signals into the final candidate score.
- Pipeline → SQLite store: persists · Stores batches, candidates, jobs, and match results.
- Pipeline → Vector store: stores embeddings · Writes and queries vector representations.
- Rule extractor → Schemas: emits · Produces structured candidate data models.
- LLM extractor → Schemas: emits · Produces structured candidate data models.
- JD analyzer → Schemas: emits · Produces structured job-spec models.
- Keyword match → Schemas: consumes · Uses candidate and job contracts as input.
- Semantic match → Vector store: queries · Relies on stored embeddings for similarity lookup.
- Rank scorer → Schemas: consumes · Combines structured inputs for explainable ranking.
- Task workers → Pipeline: runs · Executes batch processing outside request time.
- Streamlit UI → Resume API: calls · Uses backend endpoints for uploads and status.
- Streamlit UI → Job API: calls · Uses backend endpoints for job analysis.
- Streamlit UI → Match API: calls · Uses backend endpoints for ranking requests.
- SQLite store → Config: configured by · Database connection and paths come from runtime settings.
- Vector store → Config: configured by · Vector store behavior comes from runtime settings.
- Pipeline → Exceptions: raises · Uses shared domain error handling across stages.
