# keralia/nlp-resume-matching-system architecture

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

- Interactive diagram: https://gitdiagram.com/keralia/nlp-resume-matching-system
- Repository: https://github.com/keralia/nlp-resume-matching-system

## Overview

TalentMatch is a resume-to-job matching product with a browser-based role discovery and ATS audit experience, plus a Python matching and academic evaluation suite. The user-facing flow initializes the browser engine with bundled resume, job, and skill data; users select a role or provide resume text and receive match diagnostics. The Python path loads the same kinds of inputs, prepares and scores candidates, and evaluates rankings. Browser component interactions are limited to the shown excerpts; unsampled integrations are not inferred.

Main entry points: [`run_experiments.py`](https://github.com/keralia/nlp-resume-matching-system/blob/main/run_experiments.py) (Experiment runner), [`src/hybrid_engine.py`](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/hybrid_engine.py) (Hybrid ranking), [`src/data_loader.py`](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/data_loader.py) (Data loader), [`js/app.js`](https://github.com/keralia/nlp-resume-matching-system/blob/main/js/app.js) (TalentMatch UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_browser["TalentMatch UI<br/>[app.js]"]
  node_demo["Interactive demo<br/>[demo.py]"]
end

subgraph group_data["Matching inputs"]
  node_browser_data["Browser data<br/>[data.js]"]
  node_resumes["Resume corpus"]
  node_job_data["Job descriptions"]
  node_taxonomy["Skills taxonomy"]
end

subgraph group_matching["Matching engine"]
  node_browser_engine["Browser matcher<br/>[engine.js]"]
  node_loader["Data loader<br/>[data_loader.py]"]
  node_preprocessor["Resume preprocessing<br/>[preprocessor.py]"]
  node_skill_extractor["Skill diagnostics<br/>[skill_extractor.py]"]
  node_lexical["TF-IDF and BM25"]
  node_semantic["Semantic matching"]
  node_hybrid["Hybrid ranking<br/>[hybrid_engine.py]"]
end

subgraph group_evaluation["Python evaluation"]
  node_benchmark["Experiment runner<br/>[run_experiments.py]"]
  node_evaluator["Ranking metrics<br/>[evaluate.py]"]
end

node_recruiter(("Recruiter"))

node_recruiter -->|"selects role"| node_browser
node_browser -->|"reads data"| node_browser_data
node_browser -->|"initializes"| node_browser_engine
node_browser_engine -->|"returns diagnostics"| node_browser
node_loader -->|"loads"| node_resumes
node_loader -->|"loads"| node_job_data
node_loader -->|"loads"| node_taxonomy
node_demo -->|"loads corpus"| node_loader
node_demo -->|"ranks candidates"| node_hybrid
node_benchmark -->|"loads corpus"| node_loader
node_benchmark -->|"extracts sections"| node_preprocessor
node_benchmark -->|"computes skill scores"| node_skill_extractor
node_benchmark -->|"scores lexical"| node_lexical
node_benchmark -->|"scores semantics"| node_semantic
node_benchmark -->|"ranks candidates"| node_hybrid
node_benchmark -->|"evaluates rankings"| node_evaluator
node_hybrid -->|"extracts sections"| node_preprocessor
node_hybrid -->|"computes lexical scores"| node_lexical
node_hybrid -->|"computes semantic score"| node_semantic
node_hybrid -->|"computes skill metrics"| node_skill_extractor
node_lexical -->|"tokenizes text"| node_preprocessor
node_semantic -->|"tokenizes text"| node_preprocessor
node_browser_engine -.->|"uses skill taxonomy"| node_taxonomy

click node_browser "https://github.com/keralia/nlp-resume-matching-system/blob/main/js/app.js"
click node_browser_engine "https://github.com/keralia/nlp-resume-matching-system/blob/main/js/engine.js"
click node_browser_data "https://github.com/keralia/nlp-resume-matching-system/blob/main/js/data.js"
click node_resumes "https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/resumes_corpus.json"
click node_job_data "https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/job_descriptions.json"
click node_taxonomy "https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/skills_taxonomy.json"
click node_loader "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/data_loader.py"
click node_preprocessor "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/preprocessor.py"
click node_skill_extractor "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/skill_extractor.py"
click node_lexical "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/baseline_matcher.py"
click node_semantic "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/semantic_matcher.py"
click node_hybrid "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/hybrid_engine.py"
click node_demo "https://github.com/keralia/nlp-resume-matching-system/blob/main/demo.py"
click node_benchmark "https://github.com/keralia/nlp-resume-matching-system/blob/main/run_experiments.py"
click node_evaluator "https://github.com/keralia/nlp-resume-matching-system/blob/main/src/evaluate.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_browser,node_demo toneBlue
class node_browser_data,node_resumes,node_job_data,node_taxonomy toneAmber
class node_browser_engine,node_loader,node_preprocessor,node_skill_extractor,node_lexical,node_semantic,node_hybrid toneMint
class node_benchmark,node_evaluator toneRose
class node_recruiter toneIndigo
```

## Components

### Browser experience

- [TalentMatch UI](https://github.com/keralia/nlp-resume-matching-system/blob/main/js/app.js): `js/app.js`
- [Interactive demo](https://github.com/keralia/nlp-resume-matching-system/blob/main/demo.py): `demo.py`

### Matching inputs

- [Browser data](https://github.com/keralia/nlp-resume-matching-system/blob/main/js/data.js): `js/data.js`
- [Resume corpus](https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/resumes_corpus.json): `dataset/resumes_corpus.json`
- [Job descriptions](https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/job_descriptions.json): `dataset/job_descriptions.json`
- [Skills taxonomy](https://github.com/keralia/nlp-resume-matching-system/blob/main/dataset/skills_taxonomy.json): `dataset/skills_taxonomy.json`

### Matching engine

- [Browser matcher](https://github.com/keralia/nlp-resume-matching-system/blob/main/js/engine.js): `js/engine.js`
- [Data loader](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/data_loader.py): `src/data_loader.py`
- [Resume preprocessing](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/preprocessor.py): `src/preprocessor.py`
- [Skill diagnostics](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/skill_extractor.py): `src/skill_extractor.py`
- [TF-IDF and BM25](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/baseline_matcher.py): `src/baseline_matcher.py`
- [Semantic matching](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/semantic_matcher.py): `src/semantic_matcher.py`
- [Hybrid ranking](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/hybrid_engine.py): `src/hybrid_engine.py`

### Python evaluation

- [Experiment runner](https://github.com/keralia/nlp-resume-matching-system/blob/main/run_experiments.py): `run_experiments.py`
- [Ranking metrics](https://github.com/keralia/nlp-resume-matching-system/blob/main/src/evaluate.py): `src/evaluate.py`

### Other components

- **Recruiter**

## Connections

- Recruiter → TalentMatch UI: selects role (evidence: `js/app.js`)
- TalentMatch UI → Browser data: reads data (evidence: `js/app.js`)
- TalentMatch UI → Browser matcher: initializes (evidence: `js/app.js`)
- Browser matcher → TalentMatch UI: returns diagnostics (evidence: `js/engine.js`)
- Data loader → Resume corpus: loads (evidence: `src/data_loader.py`)
- Data loader → Job descriptions: loads (evidence: `src/data_loader.py`)
- Data loader → Skills taxonomy: loads (evidence: `src/data_loader.py`)
- Interactive demo → Data loader: loads corpus (evidence: `demo.py`)
- Interactive demo → Hybrid ranking: ranks candidates (evidence: `demo.py`)
- Experiment runner → Data loader: loads corpus (evidence: `run_experiments.py`)
- Experiment runner → Resume preprocessing: extracts sections (evidence: `run_experiments.py`)
- Experiment runner → Skill diagnostics: computes skill scores (evidence: `run_experiments.py`)
- Experiment runner → TF-IDF and BM25: scores lexical (evidence: `run_experiments.py`)
- Experiment runner → Semantic matching: scores semantics (evidence: `run_experiments.py`)
- Experiment runner → Hybrid ranking: ranks candidates (evidence: `run_experiments.py`)
- Experiment runner → Ranking metrics: evaluates rankings (evidence: `run_experiments.py`)
- Hybrid ranking → Resume preprocessing: extracts sections (evidence: `src/hybrid_engine.py`)
- Hybrid ranking → TF-IDF and BM25: computes lexical scores (evidence: `src/hybrid_engine.py`)
- Hybrid ranking → Semantic matching: computes semantic score (evidence: `src/hybrid_engine.py`)
- Hybrid ranking → Skill diagnostics: computes skill metrics (evidence: `src/hybrid_engine.py`)
- TF-IDF and BM25 → Resume preprocessing: tokenizes text (evidence: `src/baseline_matcher.py`)
- Semantic matching → Resume preprocessing: tokenizes text (evidence: `src/semantic_matcher.py`)
- Browser matcher → Skills taxonomy: uses skill taxonomy
