# btseytlin/hr-breaker architecture

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

- Interactive diagram: https://gitdiagram.com/btseytlin/hr-breaker
- Repository: https://github.com/btseytlin/hr-breaker

## Overview

HR-Breaker turns resume material and a job posting into a tailored, validated PDF, through either the web UI or CLI. The main path parses the job, generates an optimized resume, runs filters and reviewer feedback through an iteration loop, then renders and stores the result. The product also supports multi-document profiles and job-matched synthesis. The README documents these capabilities; some subsystem links below are therefore documented rather than verified from sampled implementation.

Main entry points: [`src/hr_breaker/server.py`](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/server.py) (Web API), [`src/hr_breaker/orchestration.py`](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/orchestration.py) (Optimization loop), [`src/hr_breaker/services/profile_store.py`](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_store.py) (Profile archive), [`src/hr_breaker/services/profile_retrieval.py`](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_retrieval.py) (Profile ranking and synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_web["Web UI<br/>[app.js]"]
  node_cli["Command line<br/>[cli.py]"]
  node_server["Web API<br/>[server.py]"]
end

subgraph group_optimization["Optimization and validation"]
  node_orchestrator["Optimization loop<br/>[orchestration.py]"]
  node_job_parser["Job parser<br/>[job_parser.py]"]
  node_optimizer["Resume optimizer<br/>[optimizer.py]"]
  node_filter_registry["Filter registry<br/>[registry.py]"]
  node_keyword_filter["Keyword validation<br/>[keyword_matcher.py]"]
  node_llm_filter["Visual and ATS review<br/>[llm_checker.py]"]
  node_reviewer["Combined reviewer"]
end

subgraph group_profiles["Profiles and retrieval"]
  node_profiles[("Profile archive<br/>[profile_store.py]")]
  node_profile_model["Profile documents<br/>[profile.py]"]
  node_extractor["Document extraction"]
  node_profile_retrieval["Profile ranking and synthesis"]
  node_retrieval_methods["Lexical, vector, snippets, merger"]
end

subgraph group_services["Document services"]
  node_job_scraper["Job posting scraper<br/>[job_scraper.py]"]
  node_pdf_parser["PDF input parser<br/>[pdf_parser.py]"]
  node_renderer["Resume renderer<br/>[renderer.py]"]
  node_pdf_storage[("Generated PDF storage<br/>[pdf_storage.py]")]
  node_llm_provider["LLM providers<br/>[llm_providers.py]"]
end

node_user(("Resume user"))
node_llm_service{{"LLM service"}}

node_user -->|"submits resume"| node_web
node_user -->|"submits inputs"| node_cli
node_web -.->|"calls API"| node_server
node_cli -.->|"starts optimization"| node_orchestrator
node_server -->|"starts optimization"| node_orchestrator
node_server -->|"manages profiles"| node_profiles
node_server -->|"lists PDFs"| node_pdf_storage
node_server -.->|"fetches job URL"| node_job_scraper
node_orchestrator -->|"parses job text"| node_job_parser
node_orchestrator -->|"generates resume"| node_optimizer
node_orchestrator -->|"loads filters"| node_filter_registry
node_filter_registry -->|"registers filter"| node_keyword_filter
node_filter_registry -->|"registers filter"| node_llm_filter
node_llm_filter -->|"requests review"| node_reviewer
node_orchestrator -->|"renders PDF"| node_renderer
node_renderer -.->|"stores output"| node_pdf_storage
node_optimizer -.->|"uses configured model"| node_llm_provider
node_llm_provider -.->|"sends model requests"| node_llm_service
node_profiles -->|"stores documents"| node_profile_model
node_profiles -->|"parses PDF input"| node_pdf_parser
node_profiles -->|"extracts document data"| node_extractor
node_server -->|"queues extraction"| node_extractor
node_profile_retrieval -->|"delegates scoring and synthesis"| node_retrieval_methods
node_profile_retrieval -->|"checks keywords"| node_keyword_filter
node_server -->|"ranks profile documents"| node_profile_retrieval
node_profile_retrieval -.->|"supplies synthesized source"| node_orchestrator

click node_web "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/static/js/app.js"
click node_cli "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/cli.py"
click node_server "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/server.py"
click node_orchestrator "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/orchestration.py"
click node_job_parser "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/job_parser.py"
click node_optimizer "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/optimizer.py"
click node_filter_registry "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/registry.py"
click node_keyword_filter "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/keyword_matcher.py"
click node_llm_filter "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/llm_checker.py"
click node_reviewer "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/combined_reviewer.py"
click node_profiles "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_store.py"
click node_profile_model "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/models/profile.py"
click node_extractor "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/extraction_worker.py"
click node_profile_retrieval "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_retrieval.py"
click node_retrieval_methods "https://github.com/btseytlin/hr-breaker/tree/main/src/hr_breaker/services/retrieval"
click node_job_scraper "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/job_scraper.py"
click node_pdf_parser "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/pdf_parser.py"
click node_renderer "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/renderer.py"
click node_pdf_storage "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/pdf_storage.py"
click node_llm_provider "https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/llm_providers.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_web,node_cli,node_server,node_user toneBlue
class node_orchestrator,node_job_parser,node_optimizer,node_filter_registry,node_keyword_filter,node_llm_filter,node_reviewer toneAmber
class node_profiles,node_profile_model,node_extractor,node_profile_retrieval,node_retrieval_methods toneMint
class node_job_scraper,node_pdf_parser,node_renderer,node_pdf_storage,node_llm_provider toneRose
class node_llm_service toneIndigo
```

## Components

### User entry

- [Web UI](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/static/js/app.js): `src/hr_breaker/static/js/app.js`
- [Command line](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/cli.py): `src/hr_breaker/cli.py`
- [Web API](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/server.py): `src/hr_breaker/server.py`

### Optimization and validation

- [Optimization loop](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/orchestration.py): `src/hr_breaker/orchestration.py`
- [Job parser](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/job_parser.py): `src/hr_breaker/agents/job_parser.py`
- [Resume optimizer](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/optimizer.py): `src/hr_breaker/agents/optimizer.py`
- [Filter registry](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/registry.py): `src/hr_breaker/filters/registry.py`
- [Keyword validation](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/keyword_matcher.py): `src/hr_breaker/filters/keyword_matcher.py`
- [Visual and ATS review](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/filters/llm_checker.py): `src/hr_breaker/filters/llm_checker.py`
- [Combined reviewer](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/agents/combined_reviewer.py): `src/hr_breaker/agents/combined_reviewer.py`

### Profiles and retrieval

- [Profile archive](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_store.py): `src/hr_breaker/services/profile_store.py`
- [Profile documents](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/models/profile.py): `src/hr_breaker/models/profile.py`
- [Document extraction](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/extraction_worker.py): `src/hr_breaker/services/extraction_worker.py`
- [Profile ranking and synthesis](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/profile_retrieval.py): `src/hr_breaker/services/profile_retrieval.py`
- [Lexical, vector, snippets, merger](https://github.com/btseytlin/hr-breaker/tree/main/src/hr_breaker/services/retrieval): `src/hr_breaker/services/retrieval`

### Document services

- [Job posting scraper](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/job_scraper.py): `src/hr_breaker/services/job_scraper.py`
- [PDF input parser](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/pdf_parser.py): `src/hr_breaker/services/pdf_parser.py`
- [Resume renderer](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/renderer.py): `src/hr_breaker/services/renderer.py`
- [Generated PDF storage](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/pdf_storage.py): `src/hr_breaker/services/pdf_storage.py`
- [LLM providers](https://github.com/btseytlin/hr-breaker/blob/main/src/hr_breaker/services/llm_providers.py): `src/hr_breaker/services/llm_providers.py`

### Other components

- **Resume user**
- **LLM service**

## Connections

- Resume user → Web UI: submits resume (evidence: `README.md`)
- Resume user → Command line: submits inputs (evidence: `README.md`)
- Web UI → Web API: calls API
- Command line → Optimization loop: starts optimization
- Web API → Optimization loop: starts optimization (evidence: `src/hr_breaker/server.py`)
- Web API → Profile archive: manages profiles (evidence: `src/hr_breaker/server.py`)
- Web API → Generated PDF storage: lists PDFs (evidence: `src/hr_breaker/server.py`)
- Web API → Job posting scraper: fetches job URL
- Optimization loop → Job parser: parses job text (evidence: `src/hr_breaker/orchestration.py`)
- Optimization loop → Resume optimizer: generates resume (evidence: `src/hr_breaker/orchestration.py`)
- Optimization loop → Filter registry: loads filters (evidence: `src/hr_breaker/orchestration.py`)
- Filter registry → Keyword validation: registers filter (evidence: `src/hr_breaker/filters/registry.py`)
- Filter registry → Visual and ATS review: registers filter (evidence: `src/hr_breaker/filters/registry.py`)
- Visual and ATS review → Combined reviewer: requests review (evidence: `src/hr_breaker/filters/llm_checker.py`)
- Optimization loop → Resume renderer: renders PDF (evidence: `src/hr_breaker/orchestration.py`)
- Resume renderer → Generated PDF storage: stores output
- Resume optimizer → LLM providers: uses configured model
- LLM providers → LLM service: sends model requests
- Profile archive → Profile documents: stores documents (evidence: `src/hr_breaker/services/profile_store.py`)
- Profile archive → PDF input parser: parses PDF input (evidence: `src/hr_breaker/services/profile_store.py`)
- Profile archive → Document extraction: extracts document data (evidence: `src/hr_breaker/services/profile_store.py`)
- Web API → Document extraction: queues extraction (evidence: `src/hr_breaker/server.py`)
- Profile ranking and synthesis → Lexical, vector, snippets, merger: delegates scoring and synthesis (evidence: `src/hr_breaker/services/profile_retrieval.py`)
- Profile ranking and synthesis → Keyword validation: checks keywords (evidence: `src/hr_breaker/services/profile_retrieval.py`)
- Web API → Profile ranking and synthesis: ranks profile documents (evidence: `src/hr_breaker/server.py`)
- Profile ranking and synthesis → Optimization loop: supplies synthesized source