# harshith051104/automated-resume-relevance-check-system architecture

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

- Interactive diagram: https://gitdiagram.com/harshith051104/automated-resume-relevance-check-system
- Repository: https://github.com/harshith051104/automated-resume-relevance-check-system

## Overview

This is a **single-repo Python application** with a **Streamlit UI** that orchestrates an **AI/NLP evaluation pipeline** to score **resume relevance vs job descriptions**. It’s not a traditional multi-tier “frontend/backend” web app; instead it’s a **UI-driven orchestration layer** (Streamlit) calling modular Python components:
- **Parsers**: extract structured text/skills from PDF/DOCX JDs and resumes
- **Scoring engine**: combines **hard/lexical matching** + **semantic/embedding matching**
- **LLM pipeline**: uses **LangChain + LangGraph** with **Google Gemini** (and LangSmith tracing)
- **Persistence**: **SQLite via SQLAlchemy** for JDs/resumes/results
- **Vector store**: **ChromaDB** for semantic search/embeddings (per README)

**Entry/UI**
- `app.py` — Streamlit application entrypoint; page routing/workflow; invokes parsing/scoring; renders analytics.

**Core modules (under `src/`)**
- `src/parsers/`
- `jd_parser.py` — JD ingestion/parse pipeline (PDF/DOCX → text/entities/skills)
- `resume_parser.py` — Resume ingestion/parse pipeline (PDF/DOCX → text/entities/skills); mentions NLTK in README
- `src/scoring/`
- `score_engine.py` — orchestrates scoring; merges sub-scores into final weighted score
- `hard_match.py` — keyword/BM25/fuzzy/TF-IDF style matching (lexical signals)
- `semantic_match.py` — embeddings/semantic similarity; integrates ChromaDB + Google embeddings (per README)
- `src/langchain_pipeline/`
- `chains.py` — LangChain chain definitions (prompting / tools / retrieval steps)
- `graph.py` — LangGraph orchestration (state machine / DAG for multi-step evaluation)
- `src/database/`
- `db_handler.py` — database access layer (SQLAlchemy) for SQLite persistence
- `src/utils/helpers.py` — shared helpers used across modules

**Config/Runtime**
- `.streamlit/config.toml` — UI settings/theme
- `.env.example` — env var contract: Gemini key, LangSmith settings, DB URL, limits
- `requirements.txt`, `packages.txt`, `.devcontainer/` — dependency + deployment scaffolding

From README/env contract, treat these as “outside the system” but connected:

- **User (Recruiter/HR)** via browser
- **Streamlit runtime** (hosting: local or Streamlit Cloud)
- **Google Gemini API** (LLM inference)
- **Google AI Embeddings API** (semantic embeddings) *(or whichever LangChain embeddings provider configured)*
- **LangSmith** (observability/tracing)
- **File inputs** (PDF/DOCX uploads) — treat as data source from user session

##### Upload resume(s) → parse → persist
3) For each resume × JD: build evaluation context → run hard + semantic scoring → combine → store result → render dashboard

##### Primary flows
**(1) JD ingestion path**
- User → `app.py` (Upload JD PDF/DOCX)
- `app.py` → `src/parsers/jd_parser.py` (extract text/skills/entities)
- `jd_parser.py` → `src/database/db_handler.py` (store JD raw text + extracted fields)
- `db_handler.py` → SQLite

**(2) Resume ingestion path**
- User → `app.py` (Upload Resume PDF/DOCX)
- `app.py` → `src/parsers/resume_parser.py`
- `resume_parser.py` → `db_handler.py` → SQLite

**(3) Evaluation/scoring path**
- `app.py` → `src/scoring/score_engine.py` (evaluate resume vs JD)
- `score_engine.py` → `hard_match.py` (TF-IDF/BM25/fuzzy signals)
- `score_engine.py` → `semantic_match.py`:
- `semantic_match.py` → Embeddings API (create embeddings)
- `score_engine.py` → `src/langchain_pipeline/graph.py` (if LLM reasoning is in the loop)
- `graph.py` → `chains.py`
- `chains.py` → Google Gemini API
- `langchain_pipeline/*` → LangSmith (trace spans, prompts, runs)
- `score_engine.py` → `db_handler.py` → SQLite (persist evaluation results, scores, verdicts)

**(4) Analytics/dashboard path**
- `app.py` → `db_handler.py` → SQLite (read results)
- `app.py` → UI Charts (score distributions/trends)

##### Cross-cutting concerns to label (don’t hide them)
- **Env/config**: `.env` values feed `app.py` and pipeline modules (API keys, DB URL, limits)

Small annotation callouts (sticky-note style) to make design intent explicit:

- **Orchestrator pattern**: `app.py` is the central coordinator; business logic is in `src/`.
- **Separation of concerns**:
- parsing (`src/parsers`)
- scoring (`src/scoring`)
- LLM orchestration (`src/langchain_pipeline`)
- persistence (`src/database`)
- **Hybrid scoring strategy**: lexical + semantic + optional LLM reasoning (weighted final score).
- **Observability**: LangSmith instrumentation around LangChain/LangGraph runs.
- **Stateful stores**: SQLite (structured persistence) + ChromaDB (vector persistence).

Nodes explicitly:
- `app.py` (Streamlit UI + workflow)
- `src/parsers/jd_parser.py`
- `src/parsers/resume_parser.py`
- `src/scoring/score_engine.py`
- `src/scoring/hard_match.py`
- `src/scoring/semantic_match.py`
- `src/langchain_pipeline/graph.py`
- `src/langchain_pipeline/chains.py`
- `src/database/db_handler.py`
- SQLite DB file (`DATABASE_URL=sqlite:///...`)
- ChromaDB (vector store)
- Google Gemini API
- Embeddings API
- LangSmith
- Config: `.env` / Streamlit Secrets, `.streamlit/config.toml`
- Batch processing loop (annotated)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram A: Level 1 Context
%% =========================
subgraph A["A) System Context (Level 1)"]
direction TB

U["User (Recruiter/HR)\nBrowser"]:::external

subgraph RTBOX["Streamlit Runtime (Local or Streamlit Cloud)"]
direction TB
RT["Streamlit App Runtime"]:::runtime
SEC["Secrets & Config\n(.env / Streamlit Secrets)\nNever committed"]:::note
end

APP["UI / Workflow Controller\n(app.py)"]:::ui

GEM["Google Gemini API\n(LLM inference)"]:::externalCloud
EMB["Embeddings API\n(Google AI Embeddings or configured provider)"]:::externalCloud
LS["LangSmith\n(Tracing/Observability)"]:::externalCloud

SQL[("SQLite DB\n(SQLAlchemy)")]:::datastore
CH[("ChromaDB\n(Vector Store)")]:::datastore

FILES["Uploaded Files\n(PDF/DOCX bytes)"]:::external

U -->|"uses"| RT
RT -->|"runs"| APP
U -->|"uploads"| FILES
FILES -->|"PDF/DOCX bytes"| APP

APP -->|"calls LLM"| GEM
APP -->|"requests embeddings"| EMB
APP -->|"reads/writes"| CH
APP -->|"reads/writes"| SQL
APP -->|"sends traces"| LS

SEC -.->|"injects config"| APP
end

%% =======================================
%% Diagram B: Level 2 Container/Components
%% =======================================
subgraph B["B) Internal Component Architecture (Level 2)"]
direction TB

subgraph ORCH["Streamlit Orchestration Layer"]
direction TB
APP2["UI / Workflow Controller\n(app.py)"]:::ui
CFG["Runtime Config\n(.streamlit/config.toml)\n.env.example (contract)"]:::config
end

subgraph CORE["Core Python Modules (src/)"]
direction TB

subgraph PARSERS["Parsers (src/parsers/)"]
direction TB
JDP["JD Parser\n(jd_parser.py)"]:::component
RSP["Resume Parser\n(resume_parser.py)"]:::component
NLTK["NLTK\n(tokenize/entity/skills)"]:::library
end

subgraph SCORING["Scoring (src/scoring/)"]
direction TB
SE["Score Engine Orchestrator\n(score_engine.py)"]:::component
HM["Hard / Lexical Match\n(hard_match.py)\n(BM25/TF-IDF/fuzzy)"]:::component
SM["Semantic Match\n(semantic_match.py)\n(embeddings + similarity)"]:::component
end

subgraph LLMPIPE["LLM Pipeline (src/langchain_pipeline/)"]
direction TB
LG["LangGraph Orchestration\n(graph.py)"]:::component
LC["LangChain Chains\n(chains.py)"]:::component
end

subgraph PERSIST["Persistence (src/database/)"]
direction TB
DBH["DB Handler\n(db_handler.py)\n(SQLAlchemy)"]:::component
end

subgraph UTILS["Utilities (src/utils/)"]
direction TB
HELP["Shared Helpers\n(helpers.py)"]:::component
end

end

%% External dependencies (repeated for clarity)
GEM2["Google Gemini API"]:::externalCloud
EMB2["Embeddings API"]:::externalCloud
LS2["LangSmith Tracing"]:::externalCloud
SQL2[("SQLite DB")]:::datastore
CH2[("ChromaDB")]:::datastore

%% --- Component wiring (dataflow + dependencies)
CFG -.->|"API keys + DB URL + limits"| APP2

APP2 -->|"parses JD"| JDP
APP2 -->|"parses resume"| RSP
RSP -->|"tokenize/extract"| NLTK

JDP -->|"stores JD record"| DBH
RSP -->|"stores resume record"| DBH
DBH -->|"persists"| SQL2

APP2 -->|"evaluate resume×JD"| SE
SE -->|"computes hard score"| HM
SE -->|"computes semantic score"| SM
SM -->|"create embeddings"| EMB2
SM <-->|"store/query vectors"| CH2

SE -->|"optional LLM reasoning"| LG
LG -->|"invokes"| LC
LC -->|"calls LLM"| GEM2

LG -.->|"trace spans"| LS2
LC -.->|"trace runs"| LS2

SE -->|"stores result records"| DBH
APP2 -->|"reads results for dashboard"| DBH
DBH -->|"queries"| SQL2

HELP -.->|"shared helpers"| JDP
HELP -.->|"shared helpers"| RSP
HELP -.->|"shared helpers"| SE
HELP -.->|"shared helpers"| DBH

end

%% ===================================
%% Diagram C: Level 3 Workflow (Flow)
%% ===================================
subgraph C["C) Workflow / Sequence (Level 3)"]
direction TB

C1["1) User uploads JD (PDF/DOCX)"]:::external
C2["2) app.py sends bytes to JD Parser"]:::ui
C3["3) JD Parser extracts text + skills/entities (JSON)"]:::component
C4["4) DB Handler persists JD record → SQLite"]:::component

C5["5) User uploads Resume (PDF/DOCX)"]:::external
C6["6) app.py sends bytes to Resume Parser"]:::ui
C7["7) Resume Parser extracts text + skills/entities (JSON)\n(+ NLTK enrich)"]:::component
C8["8) DB Handler persists Resume record → SQLite"]:::component

LOOP["Loop: for each resume × JD\n(batch N ≤ BATCH_PROCESSING_LIMIT)"]:::note
C9["9) Score Engine evaluates resume + JD context"]:::component
C10["10) Hard Match computes lexical signals"]:::component
C11["11) Semantic Match builds embeddings + similarity\nEmbeddings API + ChromaDB"]:::component
C12["12) Optional LangGraph/Chains reasoning\nGemini API (+ LangSmith traces)"]:::component
C13["13) DB Handler stores result records → SQLite"]:::component
C14["14) app.py reads analytics + renders dashboard"]:::ui

C1 --> C2 --> C3 --> C4
C5 --> C6 --> C7 --> C8
C8 --> LOOP --> C9
C9 --> C10 --> C13
C9 --> C11 --> C13
C9 --> C12 --> C13
C13 --> C14
end

%% =========================
%% Click Events (mappings)
%% =========================
click APP "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/app.py"
click APP2 "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/app.py"

click JDP "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/parsers/jd_parser.py"
click RSP "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/parsers/resume_parser.py"
click SE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/scoring/score_engine.py"
click HM "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/scoring/hard_match.py"
click SM "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/scoring/semantic_match.py"
click LC "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/langchain_pipeline/chains.py"
click LG "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/langchain_pipeline/graph.py"
click DBH "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/database/db_handler.py"
click HELP "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/src/utils/helpers.py"

%% package boundary clicks (use invisible/aux nodes to attach clicks)
PARSERS_DIR["src/parsers/"]:::boundary
SCORING_DIR["src/scoring/"]:::boundary
LCP_DIR["src/langchain_pipeline/"]:::boundary
DB_DIR["src/database/"]:::boundary
UTIL_DIR["src/utils/"]:::boundary
CFG_FILE[".streamlit/config.toml"]:::boundary
ENV_FILE[".env.example"]:::boundary
REQ_FILE["requirements.txt"]:::boundary
PKG_FILE["packages.txt"]:::boundary
DEVCONT_FILE[".devcontainer/devcontainer.json"]:::boundary

%% keep boundaries vertically stacked and connected lightly
PARSERS_DIR -.-> JDP
SCORING_DIR -.-> SE
LCP_DIR -.-> LG
DB_DIR -.-> DBH
UTIL_DIR -.-> HELP
CFG_FILE -.-> CFG
ENV_FILE -.-> CFG
REQ_FILE -.-> APP2
PKG_FILE -.-> APP2
DEVCONT_FILE -.-> APP2

click PARSERS_DIR "https://github.com/harshith051104/automated-resume-relevance-check-system/tree/main/src/parsers/"
click SCORING_DIR "https://github.com/harshith051104/automated-resume-relevance-check-system/tree/main/src/scoring/"
click LCP_DIR "https://github.com/harshith051104/automated-resume-relevance-check-system/tree/main/src/langchain_pipeline/"
click DB_DIR "https://github.com/harshith051104/automated-resume-relevance-check-system/tree/main/src/database/"
click UTIL_DIR "https://github.com/harshith051104/automated-resume-relevance-check-system/tree/main/src/utils/"
click CFG_FILE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/.streamlit/config.toml"
click ENV_FILE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/.env.example"
click REQ_FILE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/requirements.txt"
click PKG_FILE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/packages.txt"
click DEVCONT_FILE "https://github.com/harshith051104/automated-resume-relevance-check-system/blob/main/.devcontainer/devcontainer.json"

%% =========================
%% Styles
%% =========================
classDef ui fill:#1f77b4,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
classDef runtime fill:#0d9488,stroke:#064e3b,color:#ffffff,stroke-width:1.5px
classDef component fill:#22c55e,stroke:#14532d,color:#052e16,stroke-width:1.2px
classDef datastore fill:#f59e0b,stroke:#7c2d12,color:#1f1300,stroke-width:1.5px
classDef external fill:#94a3b8,stroke:#334155,color:#0b1220,stroke-width:1.2px
classDef externalCloud fill:#a78bfa,stroke:#4c1d95,color:#1f0a3d,stroke-width:1.2px
classDef config fill:#f97316,stroke:#7c2d12,color:#1f1300,stroke-width:1.2px
classDef library fill:#fde047,stroke:#a16207,color:#1f1300,stroke-width:1.0px
classDef note fill:#fff7ed,stroke:#9a3412,color:#7c2d12,stroke-dasharray: 4 3
classDef boundary fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-dasharray: 5 4
```
