# lochan87/resume_ranker architecture

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

- Interactive diagram: https://gitdiagram.com/lochan87/resume_ranker
- Repository: https://github.com/lochan87/resume_ranker

## Overview

This is a resume-screening and ranking product exposed through a CLI and a FastAPI wrapper. Its principal workflow ingests and deduplicates resumes, extracts candidate details, applies deterministic eligibility rules, enriches eligible candidates with GitHub data, assesses and scores them, then exports ranked results. The pipeline owns the screening-stage calls; the CLI and API own pipeline invocation and report handling. The graph also shows configuration, shared schemas, and external services. Some pipeline wiring is supported by the source index rather than a complete excerpt; unsampled implementation details are not inferred.

Main entry points: [`src/pipeline.py`](https://github.com/lochan87/resume_ranker/blob/main/src/pipeline.py) (Screening pipeline), [`main.py`](https://github.com/lochan87/resume_ranker/blob/main/main.py) (CLI), [`src/api.py`](https://github.com/lochan87/resume_ranker/blob/main/src/api.py) (Screening API), [`src/report.py`](https://github.com/lochan87/resume_ranker/blob/main/src/report.py) (Report exporters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_main_cli["CLI<br/>[main.py]"]
  node_screen_api["Screening API<br/>[api.py]"]
end

subgraph group_screening["Resume screening"]
  node_pipeline["Screening pipeline<br/>[pipeline.py]"]
  node_ingestion["Resume ingestion<br/>[ingestion.py]"]
  node_extraction["Candidate extraction<br/>[extraction.py]"]
  node_eligibility["Eligibility filter<br/>[eligibility.py]"]
end

subgraph group_assessment["Assessment and enrichment"]
  node_github_enrichment["GitHub enrichment"]
  node_llm_assessment["LLM assessment<br/>[llm.py]"]
  node_scoring["Scoring and ranking<br/>[scoring.py]"]
end

subgraph group_outputs["Configuration and results"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_models["Shared data models<br/>[models.py]"]
  node_report["Report exporters<br/>[report.py]"]
  node_result_files["JSON and CSV files"]
end

node_cli_user(("CLI user"))
node_api_client(("API client"))
node_gemini{{"Google Gemini"}}
node_github_service{{"GitHub REST API"}}

node_cli_user -->|"runs CLI"| node_main_cli
node_main_cli -->|"runs screening"| node_pipeline
node_main_cli -->|"exports results"| node_report
node_api_client -->|"submits request"| node_screen_api
node_screen_api -->|"runs screening"| node_pipeline
node_screen_api -->|"exports results"| node_report
node_screen_api -->|"reads results"| node_result_files
node_pipeline -->|"ingests resumes"| node_ingestion
node_pipeline -->|"extracts details"| node_extraction
node_pipeline -->|"checks eligibility"| node_eligibility
node_pipeline -->|"fetches profiles"| node_github_enrichment
node_pipeline -->|"assesses candidates"| node_llm_assessment
node_pipeline -->|"assembles scores"| node_scoring
node_pipeline -->|"uses schemas"| node_models
node_llm_assessment -->|"requests evaluation"| node_gemini
node_github_enrichment -->|"queries profiles"| node_github_service
node_main_cli -->|"reads defaults"| node_config
node_report -->|"reads privacy setting"| node_config
node_report -->|"writes exports"| node_result_files

click node_main_cli "https://github.com/lochan87/resume_ranker/blob/main/main.py"
click node_screen_api "https://github.com/lochan87/resume_ranker/blob/main/src/api.py"
click node_pipeline "https://github.com/lochan87/resume_ranker/blob/main/src/pipeline.py"
click node_ingestion "https://github.com/lochan87/resume_ranker/blob/main/src/ingestion.py"
click node_extraction "https://github.com/lochan87/resume_ranker/blob/main/src/extraction.py"
click node_eligibility "https://github.com/lochan87/resume_ranker/blob/main/src/eligibility.py"
click node_github_enrichment "https://github.com/lochan87/resume_ranker/blob/main/src/github_enrichment.py"
click node_llm_assessment "https://github.com/lochan87/resume_ranker/blob/main/src/llm.py"
click node_scoring "https://github.com/lochan87/resume_ranker/blob/main/src/scoring.py"
click node_config "https://github.com/lochan87/resume_ranker/blob/main/src/config.py"
click node_models "https://github.com/lochan87/resume_ranker/blob/main/src/models.py"
click node_report "https://github.com/lochan87/resume_ranker/blob/main/src/report.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_main_cli,node_screen_api,node_cli_user,node_api_client toneBlue
class node_pipeline,node_ingestion,node_extraction,node_eligibility toneAmber
class node_github_enrichment,node_llm_assessment,node_scoring,node_github_service toneMint
class node_config,node_models,node_report,node_result_files toneRose
class node_gemini toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/lochan87/resume_ranker/blob/main/main.py): `main.py`
- [Screening API](https://github.com/lochan87/resume_ranker/blob/main/src/api.py): `src/api.py`

### Resume screening

- [Screening pipeline](https://github.com/lochan87/resume_ranker/blob/main/src/pipeline.py): `src/pipeline.py`
- [Resume ingestion](https://github.com/lochan87/resume_ranker/blob/main/src/ingestion.py): `src/ingestion.py`
- [Candidate extraction](https://github.com/lochan87/resume_ranker/blob/main/src/extraction.py): `src/extraction.py`
- [Eligibility filter](https://github.com/lochan87/resume_ranker/blob/main/src/eligibility.py): `src/eligibility.py`

### Assessment and enrichment

- [GitHub enrichment](https://github.com/lochan87/resume_ranker/blob/main/src/github_enrichment.py): `src/github_enrichment.py`
- [LLM assessment](https://github.com/lochan87/resume_ranker/blob/main/src/llm.py): `src/llm.py`
- [Scoring and ranking](https://github.com/lochan87/resume_ranker/blob/main/src/scoring.py): `src/scoring.py`

### Configuration and results

- [Runtime configuration](https://github.com/lochan87/resume_ranker/blob/main/src/config.py): `src/config.py`
- [Shared data models](https://github.com/lochan87/resume_ranker/blob/main/src/models.py): `src/models.py`
- [Report exporters](https://github.com/lochan87/resume_ranker/blob/main/src/report.py): `src/report.py`
- **JSON and CSV files**

### Other components

- **CLI user**
- **API client**
- **Google Gemini**
- **GitHub REST API**

## Connections

- CLI user → CLI: runs CLI (evidence: `main.py`)
- CLI → Screening pipeline: runs screening (evidence: `main.py`)
- CLI → Report exporters: exports results (evidence: `main.py`)
- API client → Screening API: submits request (evidence: `src/api.py`)
- Screening API → Screening pipeline: runs screening (evidence: `src/api.py`)
- Screening API → Report exporters: exports results (evidence: `src/api.py`)
- Screening API → JSON and CSV files: reads results (evidence: `src/api.py`)
- Screening pipeline → Resume ingestion: ingests resumes (evidence: `src/pipeline.py`)
- Screening pipeline → Candidate extraction: extracts details (evidence: `src/pipeline.py`)
- Screening pipeline → Eligibility filter: checks eligibility (evidence: `src/pipeline.py`)
- Screening pipeline → GitHub enrichment: fetches profiles (evidence: `src/pipeline.py`)
- Screening pipeline → LLM assessment: assesses candidates (evidence: `src/pipeline.py`)
- Screening pipeline → Scoring and ranking: assembles scores (evidence: `src/pipeline.py`)
- Screening pipeline → Shared data models: uses schemas (evidence: `src/pipeline.py`)
- LLM assessment → Google Gemini: requests evaluation (evidence: `src/llm.py`)
- GitHub enrichment → GitHub REST API: queries profiles (evidence: `src/github_enrichment.py`)
- CLI → Runtime configuration: reads defaults (evidence: `main.py`)
- Report exporters → Runtime configuration: reads privacy setting (evidence: `src/report.py`)
- Report exporters → JSON and CSV files: writes exports
