# aillian/cvsagent architecture

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

- Interactive diagram: https://gitdiagram.com/aillian/cvsagent
- Repository: https://github.com/aillian/cvsagent

## Overview

CVsAgent is a CLI résumé-extraction tool: a user supplies PDF/DOCX CVs and optional job-matching or custom-field settings, then receives a tabular report. The CLI orchestrator loads documents, checks cached results, estimates cost and runs extraction when needed, then flattens and exports results. OpenAI and local Ollama are documented provider options. The main source excerpts show the loader, cache, pipeline, mapper, and exporter responsibilities; some orchestration calls and prompt wiring are only partially sampled, so those connections are limited to the evidence shown.

Main entry points: [`cvs_agent/app.py`](https://github.com/aillian/cvsagent/blob/main/cvs_agent/app.py) (Run orchestration), [`cvs_agent/pipeline.py`](https://github.com/aillian/cvsagent/blob/main/cvs_agent/pipeline.py) (LLM extraction), [`main.py`](https://github.com/aillian/cvsagent/blob/main/main.py) (CLI entry), [`cvs_agent/cache.py`](https://github.com/aillian/cvsagent/blob/main/cvs_agent/cache.py) (Extraction cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_flow["CLI workflow"]
  node_entry["CLI entry<br/>[main.py]"]
  node_orchestrator["Run orchestration<br/>[app.py]"]
  node_cv_files["CV files"]
  node_loader["Document loader<br/>[loader.py]"]
  node_config["Run configuration<br/>[config.py]"]
  node_cache[("Extraction cache<br/>[cache.py]")]
  node_cache_files[("Cache files")]
  node_console["CLI feedback<br/>[console.py]"]
end

subgraph group_extraction["Extraction"]
  node_pipeline["LLM extraction<br/>[pipeline.py]"]
  node_schema["CV data schema<br/>[schema.py]"]
  node_prompts["Extraction prompts<br/>[prompts.py]"]
  node_llm{{"LLM provider"}}
  node_job_description["Job description"]
end

subgraph group_results["Results"]
  node_mapper["Row mapping<br/>[mapper.py]"]
  node_utils["List formatting<br/>[utils.py]"]
  node_exporter["Report exporter<br/>[exporter.py]"]
  node_report["Report files"]
end

node_user(("CLI user"))

node_user -->|"runs"| node_entry
node_entry -->|"starts"| node_orchestrator
node_user -->|"supplies"| node_cv_files
node_orchestrator -->|"loads CVs"| node_loader
node_cv_files -->|"parsed from"| node_loader
node_orchestrator -->|"checks results"| node_cache
node_cache -->|"reads and writes"| node_cache_files
node_orchestrator -->|"runs extraction"| node_pipeline
node_pipeline -->|"builds schema"| node_schema
node_pipeline -->|"invokes"| node_llm
node_pipeline -.->|"uses prompt"| node_prompts
node_job_description -->|"configures match"| node_orchestrator
node_orchestrator -->|"flattens results"| node_mapper
node_mapper -->|"formats lists"| node_utils
node_orchestrator -->|"saves results"| node_exporter
node_exporter -->|"writes report"| node_report
node_orchestrator -->|"uses settings"| node_config
node_orchestrator -->|"reports progress"| node_console

click node_entry "https://github.com/aillian/cvsagent/blob/main/main.py"
click node_orchestrator "https://github.com/aillian/cvsagent/blob/main/cvs_agent/app.py"
click node_loader "https://github.com/aillian/cvsagent/blob/main/cvs_agent/loader.py"
click node_config "https://github.com/aillian/cvsagent/blob/main/cvs_agent/config.py"
click node_cache "https://github.com/aillian/cvsagent/blob/main/cvs_agent/cache.py"
click node_pipeline "https://github.com/aillian/cvsagent/blob/main/cvs_agent/pipeline.py"
click node_schema "https://github.com/aillian/cvsagent/blob/main/cvs_agent/schema.py"
click node_prompts "https://github.com/aillian/cvsagent/blob/main/cvs_agent/prompts.py"
click node_mapper "https://github.com/aillian/cvsagent/blob/main/cvs_agent/mapper.py"
click node_utils "https://github.com/aillian/cvsagent/blob/main/cvs_agent/utils.py"
click node_exporter "https://github.com/aillian/cvsagent/blob/main/cvs_agent/exporter.py"
click node_console "https://github.com/aillian/cvsagent/blob/main/cvs_agent/console.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_entry,node_orchestrator,node_cv_files,node_loader,node_config,node_cache,node_cache_files,node_console,node_user toneBlue
class node_pipeline,node_schema,node_prompts,node_llm,node_job_description toneAmber
class node_mapper,node_utils,node_exporter,node_report toneMint
```

## Components

### CLI workflow

- [CLI entry](https://github.com/aillian/cvsagent/blob/main/main.py): `main.py`
- [Run orchestration](https://github.com/aillian/cvsagent/blob/main/cvs_agent/app.py): `cvs_agent/app.py`
- **CV files**
- [Document loader](https://github.com/aillian/cvsagent/blob/main/cvs_agent/loader.py): `cvs_agent/loader.py`
- [Run configuration](https://github.com/aillian/cvsagent/blob/main/cvs_agent/config.py): `cvs_agent/config.py`
- [Extraction cache](https://github.com/aillian/cvsagent/blob/main/cvs_agent/cache.py): `cvs_agent/cache.py`
- **Cache files**
- [CLI feedback](https://github.com/aillian/cvsagent/blob/main/cvs_agent/console.py): `cvs_agent/console.py`

### Extraction

- [LLM extraction](https://github.com/aillian/cvsagent/blob/main/cvs_agent/pipeline.py): `cvs_agent/pipeline.py`
- [CV data schema](https://github.com/aillian/cvsagent/blob/main/cvs_agent/schema.py): `cvs_agent/schema.py`
- [Extraction prompts](https://github.com/aillian/cvsagent/blob/main/cvs_agent/prompts.py): `cvs_agent/prompts.py`
- **LLM provider**
- **Job description**

### Results

- [Row mapping](https://github.com/aillian/cvsagent/blob/main/cvs_agent/mapper.py): `cvs_agent/mapper.py`
- [List formatting](https://github.com/aillian/cvsagent/blob/main/cvs_agent/utils.py): `cvs_agent/utils.py`
- [Report exporter](https://github.com/aillian/cvsagent/blob/main/cvs_agent/exporter.py): `cvs_agent/exporter.py`
- **Report files**

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: runs (evidence: `README.md`)
- CLI entry → Run orchestration: starts (evidence: `main.py`)
- CLI user → CV files: supplies (evidence: `README.md`)
- Run orchestration → Document loader: loads CVs (evidence: `cvs_agent/app.py`)
- CV files → Document loader: parsed from (evidence: `cvs_agent/loader.py`)
- Run orchestration → Extraction cache: checks results (evidence: `cvs_agent/app.py`)
- Extraction cache → Cache files: reads and writes (evidence: `cvs_agent/cache.py`)
- Run orchestration → LLM extraction: runs extraction (evidence: `cvs_agent/app.py`)
- LLM extraction → CV data schema: builds schema (evidence: `cvs_agent/pipeline.py`)
- LLM extraction → LLM provider: invokes (evidence: `cvs_agent/pipeline.py`)
- LLM extraction → Extraction prompts: uses prompt (evidence: `cvs_agent/pipeline.py`)
- Job description → Run orchestration: configures match (evidence: `README.md`)
- Run orchestration → Row mapping: flattens results (evidence: `cvs_agent/app.py`)
- Row mapping → List formatting: formats lists (evidence: `cvs_agent/mapper.py`)
- Run orchestration → Report exporter: saves results (evidence: `cvs_agent/app.py`)
- Report exporter → Report files: writes report (evidence: `cvs_agent/exporter.py`)
- Run orchestration → Run configuration: uses settings (evidence: `cvs_agent/app.py`)
- Run orchestration → CLI feedback: reports progress (evidence: `cvs_agent/app.py`)