# crpf-mitadt/hiring-screening-engine architecture

> Architecture diagram of the GitHub repository crpf-mitadt/hiring-screening-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crpf-mitadt/hiring-screening-engine
- Repository: https://github.com/crpf-mitadt/hiring-screening-engine

## Overview

Chandra Eval is a specialized resume/JD screening engine, not the recruitment platform. Its main workflow accepts a JD and resume, extracts structured records (using full-document Chandra OCR for raw resume PDFs and Gemma-based structuring), evaluates eligibility and evidence deterministically, and writes decision-support reports that require human review. The graph preserves the documented OCR, safety, provenance, caching/artifact, and reporting capabilities. Some links are supported by the SOURCE INDEX’s import references rather than inspected call sites; unsampled implementation details are not asserted.

Main entry points: [`src/chandra_eval/pipeline/match_workflow.py`](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/match_workflow.py) (Match workflow), [`src/chandra_eval/scoring/engine.py`](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/engine.py) (Deterministic scoring), [`src/chandra_eval/pipeline/resume_structuring.py`](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/resume_structuring.py) (Resume structuring), [`src/chandra_eval/pipeline/candidate_evaluation.py`](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/candidate_evaluation.py) (Candidate evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Workflow entry"]
  node_cli["Match CLI<br/>[cli.py]"]
  node_workflow["Match workflow<br/>[match_workflow.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_documents["Document processing"]
  node_jd_ingest["JD ingestion<br/>[jd_document.py]"]
  node_jd_structuring["JD structuring<br/>[jd_structuring.py]"]
  node_ocr["Full-document OCR<br/>[full_document.py]"]
  node_chandra_client["Chandra client<br/>[chandra_client.py]"]
  node_resume_ingest["Resume ingestion<br/>[resume_document.py]"]
  node_resume_structuring["Resume structuring"]
  node_gemma["Gemma client<br/>[gemma_client.py]"]
  node_sanitizer["Candidate sanitizer"]
end

subgraph group_evaluation["Evaluation"]
  node_schemas["Typed schemas<br/>[common.py]"]
  node_jd_schema["JD schema<br/>[jd.py]"]
  node_resume_schema["Resume schema<br/>[resume.py]"]
  node_evaluation_schema["Evaluation schema<br/>[evaluation.py]"]
  node_candidate_eval["Candidate evaluation"]
  node_scoring["Deterministic scoring<br/>[engine.py]"]
  node_eligibility["Eligibility checks<br/>[eligibility.py]"]
  node_matching["Evidence matching<br/>[matching.py]"]
  node_dimensions["Scoring dimensions<br/>[dimensions.py]"]
  node_provenance["Evidence provenance<br/>[provenance.py]"]
end

subgraph group_outputs["Results and configuration"]
  node_reports["Report writers"]
  node_artifacts["Run artifacts"]
end

node_operator(("Engineer / reviewer"))
node_chandra_server{{"Chandra OCR server"}}
node_gemma_server{{"Gemma service"}}

node_operator -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_workflow
node_cli -->|"loads settings"| node_settings
node_workflow -->|"reads settings"| node_settings
node_workflow -->|"loads JD"| node_jd_ingest
node_workflow -->|"requests structuring"| node_jd_structuring
node_workflow -->|"runs OCR"| node_ocr
node_ocr -->|"requests pages"| node_chandra_client
node_chandra_client -->|"sends OCR request"| node_chandra_server
node_workflow -->|"loads resume"| node_resume_ingest
node_workflow -->|"requests structuring"| node_resume_structuring
node_jd_structuring -->|"reads document"| node_jd_ingest
node_jd_structuring -->|"requests extraction"| node_gemma
node_resume_structuring -->|"reads OCR artifacts"| node_resume_ingest
node_resume_structuring -->|"requests extraction"| node_gemma
node_gemma -.->|"sends model request"| node_gemma_server
node_resume_structuring -->|"sanitizes profile"| node_sanitizer
node_resume_ingest -->|"builds safe profile"| node_sanitizer
node_jd_structuring -->|"validates output"| node_jd_schema
node_resume_structuring -->|"validates output"| node_resume_schema
node_candidate_eval -->|"loads JD"| node_jd_ingest
node_candidate_eval -->|"loads candidate"| node_resume_ingest
node_candidate_eval -->|"evaluates candidate"| node_scoring
node_workflow -->|"runs evaluation"| node_candidate_eval
node_scoring -->|"checks eligibility"| node_eligibility
node_scoring -->|"matches evidence"| node_matching
node_scoring -->|"scores dimensions"| node_dimensions
node_scoring -->|"tracks evidence"| node_provenance
node_scoring -->|"produces result"| node_evaluation_schema
node_schemas -->|"supports"| node_jd_schema
node_schemas -->|"supports"| node_resume_schema
node_schemas -->|"supports"| node_evaluation_schema
node_candidate_eval -->|"writes reports"| node_reports
node_workflow -->|"writes run reports"| node_reports
node_reports -->|"writes JSON CSV HTML"| node_artifacts
node_operator -->|"reviews evidence"| node_artifacts

click node_cli "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/cli.py"
click node_workflow "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/match_workflow.py"
click node_settings "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/config.py"
click node_jd_ingest "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ingestion/jd_document.py"
click node_jd_structuring "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/jd_structuring.py"
click node_ocr "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ocr/full_document.py"
click node_chandra_client "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ocr/chandra_client.py"
click node_resume_ingest "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ingestion/resume_document.py"
click node_resume_structuring "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/resume_structuring.py"
click node_gemma "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/llm/gemma_client.py"
click node_sanitizer "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/safety/candidate_sanitizer.py"
click node_schemas "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/common.py"
click node_jd_schema "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/jd.py"
click node_resume_schema "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/resume.py"
click node_evaluation_schema "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/evaluation.py"
click node_candidate_eval "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/candidate_evaluation.py"
click node_scoring "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/engine.py"
click node_eligibility "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/eligibility.py"
click node_matching "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/matching.py"
click node_dimensions "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/dimensions.py"
click node_provenance "https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/provenance.py"
click node_reports "https://github.com/crpf-mitadt/hiring-screening-engine/tree/main/src/chandra_eval/reports"

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_cli,node_workflow,node_settings,node_operator toneBlue
class node_jd_ingest,node_jd_structuring,node_ocr,node_chandra_client,node_resume_ingest,node_resume_structuring,node_gemma,node_sanitizer toneAmber
class node_schemas,node_jd_schema,node_resume_schema,node_evaluation_schema,node_candidate_eval,node_scoring,node_eligibility,node_matching,node_dimensions,node_provenance,node_chandra_server toneMint
class node_reports,node_artifacts toneRose
class node_gemma_server toneIndigo
```

## Components

### Workflow entry

- [Match CLI](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/cli.py): `src/chandra_eval/cli.py`
- [Match workflow](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/match_workflow.py): `src/chandra_eval/pipeline/match_workflow.py`
- [Runtime settings](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/config.py): `src/chandra_eval/config.py`

### Document processing

- [JD ingestion](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ingestion/jd_document.py): `src/chandra_eval/ingestion/jd_document.py`
- [JD structuring](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/jd_structuring.py): `src/chandra_eval/pipeline/jd_structuring.py`
- [Full-document OCR](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ocr/full_document.py): `src/chandra_eval/ocr/full_document.py`
- [Chandra client](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ocr/chandra_client.py): `src/chandra_eval/ocr/chandra_client.py`
- [Resume ingestion](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/ingestion/resume_document.py): `src/chandra_eval/ingestion/resume_document.py`
- [Resume structuring](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/resume_structuring.py): `src/chandra_eval/pipeline/resume_structuring.py`
- [Gemma client](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/llm/gemma_client.py): `src/chandra_eval/llm/gemma_client.py`
- [Candidate sanitizer](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/safety/candidate_sanitizer.py): `src/chandra_eval/safety/candidate_sanitizer.py`

### Evaluation

- [Typed schemas](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/common.py): `src/chandra_eval/schemas/common.py`
- [JD schema](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/jd.py): `src/chandra_eval/schemas/jd.py`
- [Resume schema](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/resume.py): `src/chandra_eval/schemas/resume.py`
- [Evaluation schema](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/schemas/evaluation.py): `src/chandra_eval/schemas/evaluation.py`
- [Candidate evaluation](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/pipeline/candidate_evaluation.py): `src/chandra_eval/pipeline/candidate_evaluation.py`
- [Deterministic scoring](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/engine.py): `src/chandra_eval/scoring/engine.py`
- [Eligibility checks](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/eligibility.py): `src/chandra_eval/scoring/eligibility.py`
- [Evidence matching](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/matching.py): `src/chandra_eval/scoring/matching.py`
- [Scoring dimensions](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/dimensions.py): `src/chandra_eval/scoring/dimensions.py`
- [Evidence provenance](https://github.com/crpf-mitadt/hiring-screening-engine/blob/main/src/chandra_eval/scoring/provenance.py): `src/chandra_eval/scoring/provenance.py`

### Results and configuration

- [Report writers](https://github.com/crpf-mitadt/hiring-screening-engine/tree/main/src/chandra_eval/reports): `src/chandra_eval/reports`
- **Run artifacts**

### Other components

- **Engineer / reviewer**
- **Chandra OCR server**
- **Gemma service**

## Connections

- Engineer / reviewer → Match CLI: invokes (evidence: `README.md`)
- Match CLI → Match workflow: dispatches (evidence: `src/chandra_eval/cli.py`)
- Match CLI → Runtime settings: loads settings (evidence: `src/chandra_eval/cli.py`)
- Match workflow → Runtime settings: reads settings (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Match workflow → JD ingestion: loads JD (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Match workflow → JD structuring: requests structuring (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Match workflow → Full-document OCR: runs OCR (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Full-document OCR → Chandra client: requests pages (evidence: `src/chandra_eval/ocr/full_document.py`)
- Chandra client → Chandra OCR server: sends OCR request (evidence: `README.md`)
- Match workflow → Resume ingestion: loads resume (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Match workflow → Resume structuring: requests structuring (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- JD structuring → JD ingestion: reads document (evidence: `src/chandra_eval/pipeline/jd_structuring.py`)
- JD structuring → Gemma client: requests extraction (evidence: `src/chandra_eval/pipeline/jd_structuring.py`)
- Resume structuring → Resume ingestion: reads OCR artifacts (evidence: `src/chandra_eval/pipeline/resume_structuring.py`)
- Resume structuring → Gemma client: requests extraction (evidence: `src/chandra_eval/pipeline/resume_structuring.py`)
- Gemma client → Gemma service: sends model request
- Resume structuring → Candidate sanitizer: sanitizes profile (evidence: `src/chandra_eval/pipeline/resume_structuring.py`)
- Resume ingestion → Candidate sanitizer: builds safe profile (evidence: `src/chandra_eval/ingestion/resume_document.py`)
- JD structuring → JD schema: validates output (evidence: `src/chandra_eval/pipeline/jd_structuring.py`)
- Resume structuring → Resume schema: validates output (evidence: `src/chandra_eval/pipeline/resume_structuring.py`)
- Candidate evaluation → JD ingestion: loads JD (evidence: `src/chandra_eval/pipeline/candidate_evaluation.py`)
- Candidate evaluation → Resume ingestion: loads candidate (evidence: `src/chandra_eval/pipeline/candidate_evaluation.py`)
- Candidate evaluation → Deterministic scoring: evaluates candidate (evidence: `src/chandra_eval/pipeline/candidate_evaluation.py`)
- Match workflow → Candidate evaluation: runs evaluation (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Deterministic scoring → Eligibility checks: checks eligibility (evidence: `src/chandra_eval/scoring/engine.py`)
- Deterministic scoring → Evidence matching: matches evidence (evidence: `src/chandra_eval/scoring/engine.py`)
- Deterministic scoring → Scoring dimensions: scores dimensions (evidence: `src/chandra_eval/scoring/engine.py`)
- Deterministic scoring → Evidence provenance: tracks evidence (evidence: `src/chandra_eval/scoring/engine.py`)
- Deterministic scoring → Evaluation schema: produces result (evidence: `src/chandra_eval/scoring/engine.py`)
- Typed schemas → JD schema: supports (evidence: `src/chandra_eval/schemas/jd.py`)
- Typed schemas → Resume schema: supports (evidence: `src/chandra_eval/schemas/resume.py`)
- Typed schemas → Evaluation schema: supports (evidence: `src/chandra_eval/schemas/evaluation.py`)
- Candidate evaluation → Report writers: writes reports (evidence: `src/chandra_eval/pipeline/candidate_evaluation.py`)
- Match workflow → Report writers: writes run reports (evidence: `src/chandra_eval/pipeline/match_workflow.py`)
- Report writers → Run artifacts: writes JSON CSV HTML (evidence: `README.md`)
- Engineer / reviewer → Run artifacts: reviews evidence (evidence: `README.md`)
