# omi-kalix/ai-powered-candidate-screening architecture

> Architecture diagram of the GitHub repository omi-kalix/ai-powered-candidate-screening, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omi-kalix/ai-powered-candidate-screening
- Repository: https://github.com/omi-kalix/ai-powered-candidate-screening

## Overview

1. **Overall shape**
   - This repository is a **batch-processing LLM workflow** for screening candidates from a CSV file.
   - The architecture is centered on a **LangGraph state machine**: each candidate flows through a fixed sequence of evaluation nodes, then results are persisted and the next candidate begins.

2. **Entry point and orchestration**
   - `app.py` is the runtime entry point.
   - It likely wires together the graph, loads configuration/data, starts execution, and triggers final export.
   - The orchestration boundary is important: application startup is separate from the per-candidate workflow.

3. **Workflow engine boundary**
   - `graph/graph.py` is the likely place where the **LangGraph graph topology** is assembled.
   - This is where linear steps, conditional edges, and batch looping behavior are defined:
     - load batch once
     - process each candidate through the evaluation chain
     - branch to either the next candidate or CSV export
   - In an architecture diagram, treat this as the **control plane** of the system.

4. **Node-level processing**
   - `nodes/nodes.py` contains the discrete workflow steps described in the README:
     - load batch
     - initialize candidate
     - preprocess
     - feature extraction
     - technical match
     - seniority match
     - culture match
     - aggregate score
     - recruiter summary
     - self review
     - save result
     - next candidate
     - export CSV
   - These are the **functional units** where candidate data is transformed and enriched.

5. **LLM chain layer**
   - `chains/chains.py` likely encapsulates the LLM calls and prompt execution logic used by the nodes.
   - This is the boundary between orchestration and model interaction: nodes decide *when* to call the model, chains define *how* to call it.
   - If drawing the architecture, place this layer between node logic and the model provider.

6. **Model provider integration**
   - `model/model.py` is the abstraction for the LLM backend.
   - The README indicates the system uses **Ollama** locally and a Qwen2.5 model, so the model layer is effectively an adapter to a **local LLM runtime** rather than a hosted API.
   - This is a key external dependency: the app expects Ollama to be running and a model to be pulled.

7. **Prompting and evaluation policy**
   - `prompts/prompts.py` contains the actual prompt templates for extraction, scoring, summary generation, and self-review.
   - The prompt layer is where candidate evaluation criteria are encoded, so it materially affects output quality and consistency.
   - In a diagram, it sits beside the chain/model path as a configuration-like dependency.

8. **Typed state and schema boundaries**
   - `state/state.py` defines the workflow state carried through the graph from node to node.
   - `schemas/schema.py` likely defines Pydantic models for structured outputs such as extracted candidate features, scores, feedback, and final result records.
   - This is an important boundary: raw resume text becomes structured state, then structured output becomes persisted results.

9. **Data flow: batch input to per-candidate evaluation**
   - Input starts from `candidates.csv`, which is read as a batch dataset.
   - Each row becomes one candidate instance in the graph.
   - The candidate is normalized, parsed into structured features, scored across multiple dimensions, summarized, reviewed, and stored.

10. **Data flow: self-review before persistence**
   - The self-review stage acts as a quality gate before saving.
   - It checks summary consistency against scores and flags hallucinations, contradictions, or formatting issues.
   - If validation fails, the summary is regenerated before the result is committed.
   - This is a notable reliability boundary in the pipeline.

11. **Output and persistence**
   - Evaluated candidates are accumulated and written to `candidate_results.csv`.
   - The system appears file-based rather than database-backed, so persistence is an export step at the end of the batch rather than incremental storage.
   - `assets/tmp` suggests transient artifacts or working files may be created during execution.

12. **Supporting assets and packaging**
   - `assets/` contains screenshots used in the README, not core runtime logic.
   - `requirements.txt` captures the Python dependency set, including LangGraph, LangChain, Pandas, Pydantic, and Ollama-related tooling.
   - `Docker` is supported as a deployment wrapper, but the architecture still depends on an externally running Ollama service on the host.

13. **How to draw the main boundaries**
   - A clean diagram would show:
     - CSV input on the left
     - LangGraph orchestration in the center
     - node sequence as the candidate processing pipeline
     - LLM/model interaction as an external service boundary
     - final CSV export on the right
   - The most important internal separation is between **workflow control**, **node logic**, **LLM prompting/model access**, and **typed state/output**.

Main entry points: [`nodes/nodes.py`](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py) (Nodes), [`graph/graph.py`](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/graph/graph.py) (Graph), [`chains/chains.py`](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/chains/chains.py) (Chains), [`app.py`](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/app.py) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App<br/>entrypoint<br/>[app.py]"]
end

subgraph group_workflow["Workflow"]
  node_graph{{"Graph<br/>[graph.py]"}}
  node_nodes["Nodes<br/>workflow steps<br/>[nodes.py]"]
  node_load(("Load Batch<br/>step<br/>[nodes.py]"))
  node_prep(("Prep<br/>step<br/>[nodes.py]"))
  node_extract(("Extract<br/>step<br/>[nodes.py]"))
  node_score(("Score<br/>step<br/>[nodes.py]"))
  node_review(("Review<br/>step<br/>[nodes.py]"))
  node_save(("Save<br/>step<br/>[nodes.py]"))
  node_export(("Export<br/>step<br/>[nodes.py]"))
end

subgraph group_llm["LLM Layer"]
  node_chains["Chains<br/>[chains.py]"]
  node_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_model["Model<br/>ollama adapter<br/>[model.py]"]
end

subgraph group_contracts["Contracts"]
  node_state["State<br/>[state.py]"]
  node_schema["Schema<br/>structured models<br/>[schema.py]"]
end

subgraph group_data["Data"]
  node_inputcsv[("Candidates<br/>batch input<br/>[candidates.csv]")]
  node_outputcsv[("Results<br/>batch output")]
  node_tmp["Tmp<br/>working files"]
end

node_app -->|"bootstraps"| node_graph
node_app -->|"loads"| node_inputcsv
node_graph -->|"routes to"| node_load
node_load -->|"seeds"| node_state
node_load -->|"next"| node_prep
node_prep -->|"feeds"| node_extract
node_extract -->|"invokes"| node_chains
node_chains -->|"uses"| node_prompts
node_chains -->|"calls"| node_model
node_extract -->|"produces"| node_schema
node_extract -->|"feeds"| node_score
node_score -->|"invokes"| node_chains
node_score -->|"updates"| node_state
node_score -->|"next"| node_review
node_review -->|"checks"| node_schema
node_review -->|"passes"| node_save
node_save -->|"accumulates"| node_outputcsv
node_save -->|"loops or ends"| node_export
node_export -->|"writes"| node_outputcsv
node_nodes -->|"implements"| node_load
node_nodes -->|"implements"| node_prep
node_nodes -->|"implements"| node_extract
node_nodes -->|"implements"| node_score
node_nodes -->|"implements"| node_review
node_nodes -->|"implements"| node_save
node_nodes -->|"implements"| node_export
node_graph -->|"depends on"| node_state
node_graph -->|"wires"| node_nodes
node_app -->|"uses"| node_tmp

click node_app "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/app.py"
click node_graph "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/graph/graph.py"
click node_nodes "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_state "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/state/state.py"
click node_schema "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/schemas/schema.py"
click node_chains "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/chains/chains.py"
click node_prompts "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/prompts/prompts.py"
click node_model "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/model/model.py"
click node_inputcsv "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/candidates.csv"
click node_outputcsv "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/candidate_results.csv"
click node_tmp "https://github.com/omi-kalix/ai-powered-candidate-screening/tree/main/assets/tmp"
click node_load "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_prep "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_extract "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_score "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_review "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_save "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py"
click node_export "https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.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_app toneBlue
class node_graph,node_nodes,node_load,node_prep,node_extract,node_score,node_review,node_save,node_export toneAmber
class node_chains,node_prompts,node_model toneMint
class node_state,node_schema toneRose
class node_inputcsv,node_outputcsv,node_tmp toneIndigo
```

## Components

### Runtime

Application startup and batch execution

- [App](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/app.py): entrypoint · Starts the batch screening run · `app.py`

### Workflow

LangGraph control plane and candidate steps

- [Graph](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/graph/graph.py): langgraph topology · Assembles the state machine and routing · `graph/graph.py`
- [Nodes](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): workflow steps · Candidate processing stages · `nodes/nodes.py`
- [Load Batch](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Reads the candidate set · `nodes/nodes.py`
- [Prep](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Initializes and preprocesses a candidate · `nodes/nodes.py`
- [Extract](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Derives candidate features · `nodes/nodes.py`
- [Score](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Evaluates technical, seniority, and culture fit · `nodes/nodes.py`
- [Review](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Checks summary quality before save · `nodes/nodes.py`
- [Save](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Persists the evaluated candidate · `nodes/nodes.py`
- [Export](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/nodes/nodes.py): step · Writes the final CSV output · `nodes/nodes.py`

### LLM Layer

Prompting and model integration

- [Chains](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/chains/chains.py): llm chains · Prompt execution and model calls · `chains/chains.py`
- [Prompts](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/prompts/prompts.py): prompt templates · Scoring, summary, and review prompts · `prompts/prompts.py`
- [Model](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/model/model.py): ollama adapter · Local LLM backend integration · `model/model.py`

### Contracts

Typed state and structured outputs

- [State](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/state/state.py): workflow state · Mutable candidate and batch state · `state/state.py`
- [Schema](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/schemas/schema.py): structured models · Typed outputs for extraction and scoring · `schemas/schema.py`

### Data

Batch inputs, outputs, and working files

- [Candidates](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/candidates.csv): batch input · Source CSV of candidates · `candidates.csv`
- [Results](https://github.com/omi-kalix/ai-powered-candidate-screening/blob/main/candidate_results.csv): batch output · Final screened candidate export · `candidate_results.csv`
- [Tmp](https://github.com/omi-kalix/ai-powered-candidate-screening/tree/main/assets/tmp): working files · Transient artifacts during execution · `assets/tmp`

## Connections

- App → Graph: bootstraps · Application starts the workflow assembly
- App → Candidates: loads · Runtime consumes the candidate batch
- Graph → Load Batch: routes to · Graph begins with batch loading
- Load Batch → State: seeds · Batch and candidate state are initialized
- Load Batch → Prep: next · Loaded rows enter per-candidate processing
- Prep → Extract: feeds · Normalized candidate data is ready for feature extraction
- Extract → Chains: invokes · Extraction step delegates to LLM chains
- Chains → Prompts: uses · Chains render prompt templates
- Chains → Model: calls · Model requests go through the Ollama adapter
- Extract → Schema: produces · Structured features are validated against schemas
- Extract → Score: feeds · Extracted features move into scoring
- Score → Chains: invokes · Scoring and summary generation use the LLM layer
- Score → State: updates · Scores and summaries are stored in workflow state
- Score → Review: next · Self-review gate follows scoring
- Review → Schema: checks · Review compares output against typed records
- Review → Save: passes · Validated results proceed to persistence
- Save → Results: accumulates · Accepted candidates are written to the results export
- Save → Export: loops or ends · Graph advances to the next candidate or finishes batch export
- Export → Results: writes · Final batch output is emitted as CSV
- Nodes → Load Batch: implements · Workflow steps live in the nodes module
- Nodes → Prep: implements · Workflow steps live in the nodes module
- Nodes → Extract: implements · Workflow steps live in the nodes module
- Nodes → Score: implements · Workflow steps live in the nodes module
- Nodes → Review: implements · Workflow steps live in the nodes module
- Nodes → Save: implements · Workflow steps live in the nodes module
- Nodes → Export: implements · Workflow steps live in the nodes module
- Graph → State: depends on · Topology is driven by shared workflow state
- Graph → Nodes: wires · Graph connects the node functions
- App → Tmp: uses · Execution may create temporary artifacts
