# nandavits/job-hunter architecture

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

- Interactive diagram: https://gitdiagram.com/nandavits/job-hunter
- Repository: https://github.com/nandavits/job-hunter

## Overview

Job Hunter is a personal job-search and application-preparation pipeline, with a human deliberately retaining the final submit action. The main flow gathers postings from public career feeds, the German federal job API, and read-only alert email; normalizes and filters them; persists matches and application status; prepares tailored documents; and sends a digest. The CLI also supports manual job entry, discovery, tracking, and browser form prefill. Relationships reflect the README and shown source references; unsampled implementation details are not inferred.

Main entry points: [`jobhunter/pipeline.py`](https://github.com/nandavits/job-hunter/blob/main/jobhunter/pipeline.py) (Daily pipeline), [`jobhunter/__main__.py`](https://github.com/nandavits/job-hunter/blob/main/jobhunter/__main__.py) (Job Hunter CLI), [`jobhunter/collectors/__init__.py`](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/__init__.py) (Source coordinator), [`jobhunter/models.py`](https://github.com/nandavits/job-hunter/blob/main/jobhunter/models.py) (Normalized job record)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and settings"]
  node_cli["Job Hunter CLI<br/>[__main__.py]"]
  node_settings["Settings loader<br/>[config.py]"]
end

subgraph group_gather["Job collection"]
  node_collect["Source coordinator<br/>[__init__.py]"]
  node_ats["Career-feed collectors<br/>[ats.py]"]
  node_agency["Federal job API<br/>[arbeitsagentur.py]"]
  node_alerts["Alert-email parser<br/>[email_alerts.py]"]
  node_http["HTTP helpers<br/>[base.py]"]
end

subgraph group_screen["Matching and storage"]
  node_job["Normalized job record<br/>[models.py]"]
  node_filter["Filter and score<br/>[filters.py]"]
  node_store[("Job and tracker store<br/>[storage.py]")]
  node_pipeline["Daily pipeline<br/>[pipeline.py]"]
end

subgraph group_prepare["Application preparation"]
  node_tailor["CV and letter tailoring<br/>[tailor.py]"]
  node_documents["Document generator<br/>[documents.py]"]
  node_autofill["Application form filler<br/>[autofill.py]"]
end

subgraph group_delivery["Digest and review"]
  node_notify["Digest and notifications<br/>[notify.py]"]
end

node_person(("Job seeker"))
node_career_sites[("Company career feeds")]
node_ba_api["Arbeitsagentur API"]
node_mailbox["Alert mailbox"]
node_claude["Claude API"]
node_telegram["Telegram"]
node_review(("Human review"))

node_person -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"runs search"| node_pipeline
node_cli -->|"manages jobs"| node_store
node_cli -->|"fills forms"| node_autofill
node_pipeline -->|"collects jobs"| node_collect
node_collect -->|"fetches boards"| node_ats
node_collect -->|"fetches listings"| node_agency
node_collect -->|"reads alerts"| node_alerts
node_collect -->|"creates session"| node_http
node_ats -->|"reads feeds"| node_career_sites
node_agency -->|"searches listings"| node_ba_api
node_alerts -->|"reads read-only"| node_mailbox
node_ats -->|"normalizes postings"| node_job
node_agency -->|"normalizes postings"| node_job
node_alerts -->|"parses postings"| node_job
node_pipeline -->|"filters and scores"| node_filter
node_pipeline -->|"saves matches"| node_store
node_filter -->|"scores records"| node_job
node_store -->|"stores records"| node_job
node_pipeline -->|"tailors candidates"| node_tailor
node_pipeline -->|"generates documents"| node_documents
node_documents -->|"uses tailoring"| node_tailor
node_tailor -.->|"requests tailoring"| node_claude
node_pipeline -->|"builds digest"| node_notify
node_notify -->|"sends digest"| node_telegram
node_autofill -->|"waits for review"| node_review
node_person -->|"reviews and submits"| node_review

click node_cli "https://github.com/nandavits/job-hunter/blob/main/jobhunter/__main__.py"
click node_settings "https://github.com/nandavits/job-hunter/blob/main/jobhunter/config.py"
click node_collect "https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/__init__.py"
click node_ats "https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/ats.py"
click node_agency "https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/arbeitsagentur.py"
click node_alerts "https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/email_alerts.py"
click node_http "https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/base.py"
click node_job "https://github.com/nandavits/job-hunter/blob/main/jobhunter/models.py"
click node_filter "https://github.com/nandavits/job-hunter/blob/main/jobhunter/filters.py"
click node_store "https://github.com/nandavits/job-hunter/blob/main/jobhunter/storage.py"
click node_pipeline "https://github.com/nandavits/job-hunter/blob/main/jobhunter/pipeline.py"
click node_tailor "https://github.com/nandavits/job-hunter/blob/main/jobhunter/tailor.py"
click node_documents "https://github.com/nandavits/job-hunter/blob/main/jobhunter/documents.py"
click node_autofill "https://github.com/nandavits/job-hunter/blob/main/jobhunter/autofill.py"
click node_notify "https://github.com/nandavits/job-hunter/blob/main/jobhunter/notify.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_cli,node_settings,node_review toneBlue
class node_collect,node_ats,node_agency,node_alerts,node_http,node_career_sites toneAmber
class node_job,node_filter,node_store,node_pipeline,node_ba_api,node_claude toneMint
class node_tailor,node_documents,node_autofill toneRose
class node_notify,node_person,node_mailbox,node_telegram toneIndigo
```

## Components

### CLI and settings

- [Job Hunter CLI](https://github.com/nandavits/job-hunter/blob/main/jobhunter/__main__.py): `jobhunter/__main__.py`
- [Settings loader](https://github.com/nandavits/job-hunter/blob/main/jobhunter/config.py): `jobhunter/config.py`

### Job collection

- [Source coordinator](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/__init__.py): `jobhunter/collectors/__init__.py`
- [Career-feed collectors](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/ats.py): `jobhunter/collectors/ats.py`
- [Federal job API](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/arbeitsagentur.py): `jobhunter/collectors/arbeitsagentur.py`
- [Alert-email parser](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/email_alerts.py): `jobhunter/collectors/email_alerts.py`
- [HTTP helpers](https://github.com/nandavits/job-hunter/blob/main/jobhunter/collectors/base.py): `jobhunter/collectors/base.py`

### Matching and storage

- [Normalized job record](https://github.com/nandavits/job-hunter/blob/main/jobhunter/models.py): `jobhunter/models.py`
- [Filter and score](https://github.com/nandavits/job-hunter/blob/main/jobhunter/filters.py): `jobhunter/filters.py`
- [Job and tracker store](https://github.com/nandavits/job-hunter/blob/main/jobhunter/storage.py): `jobhunter/storage.py`
- [Daily pipeline](https://github.com/nandavits/job-hunter/blob/main/jobhunter/pipeline.py): `jobhunter/pipeline.py`

### Application preparation

- [CV and letter tailoring](https://github.com/nandavits/job-hunter/blob/main/jobhunter/tailor.py): `jobhunter/tailor.py`
- [Document generator](https://github.com/nandavits/job-hunter/blob/main/jobhunter/documents.py): `jobhunter/documents.py`
- [Application form filler](https://github.com/nandavits/job-hunter/blob/main/jobhunter/autofill.py): `jobhunter/autofill.py`

### Digest and review

- [Digest and notifications](https://github.com/nandavits/job-hunter/blob/main/jobhunter/notify.py): `jobhunter/notify.py`

### Other components

- **Job seeker**
- **Company career feeds**
- **Arbeitsagentur API**
- **Alert mailbox**
- **Claude API**
- **Telegram**
- **Human review**

## Connections

- Job seeker → Job Hunter CLI: runs commands (evidence: `README.md`)
- Job Hunter CLI → Settings loader: loads settings (evidence: `jobhunter/__main__.py`)
- Job Hunter CLI → Daily pipeline: runs search (evidence: `jobhunter/__main__.py`)
- Job Hunter CLI → Job and tracker store: manages jobs (evidence: `jobhunter/__main__.py`)
- Job Hunter CLI → Application form filler: fills forms (evidence: `jobhunter/__main__.py`)
- Daily pipeline → Source coordinator: collects jobs (evidence: `jobhunter/pipeline.py`)
- Source coordinator → Career-feed collectors: fetches boards (evidence: `jobhunter/collectors/__init__.py`)
- Source coordinator → Federal job API: fetches listings (evidence: `jobhunter/collectors/__init__.py`)
- Source coordinator → Alert-email parser: reads alerts (evidence: `jobhunter/collectors/__init__.py`)
- Source coordinator → HTTP helpers: creates session (evidence: `jobhunter/collectors/__init__.py`)
- Career-feed collectors → Company career feeds: reads feeds (evidence: `README.md`)
- Federal job API → Arbeitsagentur API: searches listings (evidence: `jobhunter/collectors/arbeitsagentur.py`)
- Alert-email parser → Alert mailbox: reads read-only (evidence: `jobhunter/collectors/email_alerts.py`)
- Career-feed collectors → Normalized job record: normalizes postings (evidence: `jobhunter/collectors/ats.py`)
- Federal job API → Normalized job record: normalizes postings (evidence: `jobhunter/collectors/arbeitsagentur.py`)
- Alert-email parser → Normalized job record: parses postings (evidence: `jobhunter/collectors/email_alerts.py`)
- Daily pipeline → Filter and score: filters and scores (evidence: `jobhunter/pipeline.py`)
- Daily pipeline → Job and tracker store: saves matches (evidence: `jobhunter/pipeline.py`)
- Filter and score → Normalized job record: scores records (evidence: `jobhunter/filters.py`)
- Job and tracker store → Normalized job record: stores records (evidence: `jobhunter/storage.py`)
- Daily pipeline → CV and letter tailoring: tailors candidates (evidence: `jobhunter/pipeline.py`)
- Daily pipeline → Document generator: generates documents (evidence: `jobhunter/pipeline.py`)
- Document generator → CV and letter tailoring: uses tailoring (evidence: `jobhunter/documents.py`)
- CV and letter tailoring → Claude API: requests tailoring (evidence: `README.md`)
- Daily pipeline → Digest and notifications: builds digest (evidence: `jobhunter/pipeline.py`)
- Digest and notifications → Telegram: sends digest (evidence: `README.md`)
- Application form filler → Human review: waits for review (evidence: `README.md`)
- Job seeker → Human review: reviews and submits (evidence: `README.md`)
