# will825/job-hunter architecture

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

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

## Overview

Job Hunter is a self-hosted job-search application: it gathers postings from company ATS boards and aggregators, enriches and scores them against a local profile, then presents matches in a dashboard or sends a daily digest. The shared scan pipeline is the principal route from watched sources to stored results; the web API and CLI initiate or expose that workflow. The README documents dashboard features and optional integrations beyond the sampled route excerpts; those are represented at the server/UI level. Some internal calls are supported by the SOURCE INDEX rather than complete excerpts.

Main entry points: [`src/pipeline.rs`](https://github.com/will825/job-hunter/blob/main/src/pipeline.rs) (Scan pipeline), [`src/server.rs`](https://github.com/will825/job-hunter/blob/main/src/server.rs) (Web API), [`src/main.rs`](https://github.com/will825/job-hunter/blob/main/src/main.rs) (CLI commands), [`src/fetchers/mod.rs`](https://github.com/will825/job-hunter/blob/main/src/fetchers/mod.rs) (Fetcher dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sourcing["Job sourcing"]
  node_pipeline["Scan pipeline<br/>[pipeline.rs]"]
  node_sources["Watchlist sources<br/>[sources.rs]"]
  node_fetch_dispatch["Fetcher dispatch<br/>[mod.rs]"]
  node_ats_fetchers["ATS fetchers<br/>[greenhouse.rs]"]
  node_aggregator_fetchers["Aggregator fetchers<br/>[adzuna.rs]"]
  node_page_detect["Careers URL detection<br/>[detect.rs]"]
  node_custom_reader["Custom page reader<br/>[custom_page.rs]"]
end

subgraph group_matching["Enrichment and scoring"]
  node_job_model["Normalized job model<br/>[models.rs]"]
  node_text_utils["Text and dedup<br/>[text.rs]"]
  node_classification["Job classification<br/>[classify.rs]"]
  node_profile["User profile<br/>[profile.rs]"]
  node_keyword_score["Keyword scoring<br/>[score.rs]"]
  node_llm["LLM scoring<br/>[llm.rs]"]
end

subgraph group_storage["Local persistence"]
  node_database[("SQLite database<br/>[db.rs]")]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_dashboard["Web dashboard<br/>[index.html]"]
  node_web_api["Web API<br/>[server.rs]"]
end

subgraph group_delivery["Notifications"]
  node_email["Digest email<br/>[email.rs]"]
end

node_user(("Job seeker"))
node_ats["ATS boards"]
node_aggregators["Job aggregators"]
node_groq["Groq API"]
node_resend["Resend API"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses dashboard"| node_dashboard
node_dashboard -->|"calls API"| node_web_api
node_cli -->|"starts scans"| node_pipeline
node_web_api -->|"starts scans"| node_pipeline
node_pipeline -->|"loads watchlist"| node_sources
node_pipeline -->|"fetches sources"| node_fetch_dispatch
node_ats -->|"provides postings"| node_ats_fetchers
node_aggregators -->|"provides postings"| node_aggregator_fetchers
node_fetch_dispatch -->|"dispatches to"| node_ats_fetchers
node_fetch_dispatch -->|"dispatches to"| node_aggregator_fetchers
node_pipeline -->|"processes jobs"| node_job_model
node_ats_fetchers -->|"normalizes postings"| node_job_model
node_aggregator_fetchers -->|"normalizes postings"| node_job_model
node_job_model -->|"computes dedup key"| node_text_utils
node_pipeline -->|"classifies jobs"| node_classification
node_pipeline -->|"scores jobs"| node_keyword_score
node_pipeline -->|"uses profile"| node_profile
node_keyword_score -->|"uses scoring profile"| node_profile
node_pipeline -->|"reranks shortlist"| node_llm
node_custom_reader -->|"extracts job listings"| node_llm
node_web_api -->|"validates careers URL"| node_page_detect
node_page_detect -->|"validates board"| node_fetch_dispatch
node_pipeline -->|"reads custom pages"| node_custom_reader
node_llm -->|"requests scoring"| node_groq
node_pipeline -->|"stores scan results"| node_database
node_web_api -->|"reads and updates"| node_database
node_web_api -->|"serves embedded UI"| node_dashboard
node_cli -->|"reads and updates"| node_database
node_cli -->|"sends digest"| node_email
node_email -->|"loads and marks matches"| node_database
node_email -->|"sends email"| node_resend

click node_cli "https://github.com/will825/job-hunter/blob/main/src/main.rs"
click node_dashboard "https://github.com/will825/job-hunter/blob/main/src/web/index.html"
click node_web_api "https://github.com/will825/job-hunter/blob/main/src/server.rs"
click node_pipeline "https://github.com/will825/job-hunter/blob/main/src/pipeline.rs"
click node_sources "https://github.com/will825/job-hunter/blob/main/src/sources.rs"
click node_fetch_dispatch "https://github.com/will825/job-hunter/blob/main/src/fetchers/mod.rs"
click node_ats_fetchers "https://github.com/will825/job-hunter/blob/main/src/fetchers/greenhouse.rs"
click node_aggregator_fetchers "https://github.com/will825/job-hunter/blob/main/src/fetchers/adzuna.rs"
click node_page_detect "https://github.com/will825/job-hunter/blob/main/src/detect.rs"
click node_custom_reader "https://github.com/will825/job-hunter/blob/main/src/custom_page.rs"
click node_job_model "https://github.com/will825/job-hunter/blob/main/src/models.rs"
click node_text_utils "https://github.com/will825/job-hunter/blob/main/src/text.rs"
click node_classification "https://github.com/will825/job-hunter/blob/main/src/classify.rs"
click node_profile "https://github.com/will825/job-hunter/blob/main/src/profile.rs"
click node_keyword_score "https://github.com/will825/job-hunter/blob/main/src/score.rs"
click node_llm "https://github.com/will825/job-hunter/blob/main/src/llm.rs"
click node_database "https://github.com/will825/job-hunter/blob/main/src/db.rs"
click node_email "https://github.com/will825/job-hunter/blob/main/src/email.rs"

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_pipeline,node_sources,node_fetch_dispatch,node_ats_fetchers,node_aggregator_fetchers,node_page_detect,node_custom_reader toneBlue
class node_job_model,node_text_utils,node_classification,node_profile,node_keyword_score,node_llm toneAmber
class node_database,node_groq,node_resend toneMint
class node_cli,node_dashboard,node_web_api toneRose
class node_email,node_user,node_ats,node_aggregators toneIndigo
```

## Components

### Job sourcing

- [Scan pipeline](https://github.com/will825/job-hunter/blob/main/src/pipeline.rs): `src/pipeline.rs`
- [Watchlist sources](https://github.com/will825/job-hunter/blob/main/src/sources.rs): `src/sources.rs`
- [Fetcher dispatch](https://github.com/will825/job-hunter/blob/main/src/fetchers/mod.rs): `src/fetchers/mod.rs`
- [ATS fetchers](https://github.com/will825/job-hunter/blob/main/src/fetchers/greenhouse.rs): `src/fetchers/greenhouse.rs`
- [Aggregator fetchers](https://github.com/will825/job-hunter/blob/main/src/fetchers/adzuna.rs): `src/fetchers/adzuna.rs`
- [Careers URL detection](https://github.com/will825/job-hunter/blob/main/src/detect.rs): `src/detect.rs`
- [Custom page reader](https://github.com/will825/job-hunter/blob/main/src/custom_page.rs): `src/custom_page.rs`

### Enrichment and scoring

- [Normalized job model](https://github.com/will825/job-hunter/blob/main/src/models.rs): `src/models.rs`
- [Text and dedup](https://github.com/will825/job-hunter/blob/main/src/text.rs): `src/text.rs`
- [Job classification](https://github.com/will825/job-hunter/blob/main/src/classify.rs): `src/classify.rs`
- [User profile](https://github.com/will825/job-hunter/blob/main/src/profile.rs): `src/profile.rs`
- [Keyword scoring](https://github.com/will825/job-hunter/blob/main/src/score.rs): `src/score.rs`
- [LLM scoring](https://github.com/will825/job-hunter/blob/main/src/llm.rs): `src/llm.rs`

### Local persistence

- [SQLite database](https://github.com/will825/job-hunter/blob/main/src/db.rs): `src/db.rs`

### User interfaces

- [CLI commands](https://github.com/will825/job-hunter/blob/main/src/main.rs): `src/main.rs`
- [Web dashboard](https://github.com/will825/job-hunter/blob/main/src/web/index.html): `src/web/index.html`
- [Web API](https://github.com/will825/job-hunter/blob/main/src/server.rs): `src/server.rs`

### Notifications

- [Digest email](https://github.com/will825/job-hunter/blob/main/src/email.rs): `src/email.rs`

### Other components

- **Job seeker**
- **ATS boards**
- **Job aggregators**
- **Groq API**
- **Resend API**

## Connections

- Job seeker → CLI commands: runs commands (evidence: `README.md`)
- Job seeker → Web dashboard: uses dashboard (evidence: `README.md`)
- Web dashboard → Web API: calls API (evidence: `src/server.rs`)
- CLI commands → Scan pipeline: starts scans (evidence: `src/main.rs`)
- Web API → Scan pipeline: starts scans (evidence: `src/server.rs`)
- Scan pipeline → Watchlist sources: loads watchlist (evidence: `src/pipeline.rs`)
- Scan pipeline → Fetcher dispatch: fetches sources (evidence: `src/pipeline.rs`)
- ATS boards → ATS fetchers: provides postings (evidence: `README.md`)
- Job aggregators → Aggregator fetchers: provides postings (evidence: `README.md`)
- Fetcher dispatch → ATS fetchers: dispatches to (evidence: `src/fetchers/mod.rs`)
- Fetcher dispatch → Aggregator fetchers: dispatches to (evidence: `src/fetchers/mod.rs`)
- Scan pipeline → Normalized job model: processes jobs (evidence: `src/pipeline.rs`)
- ATS fetchers → Normalized job model: normalizes postings (evidence: `src/fetchers/mod.rs`)
- Aggregator fetchers → Normalized job model: normalizes postings (evidence: `src/fetchers/mod.rs`)
- Normalized job model → Text and dedup: computes dedup key (evidence: `src/models.rs`)
- Scan pipeline → Job classification: classifies jobs (evidence: `src/pipeline.rs`)
- Scan pipeline → Keyword scoring: scores jobs (evidence: `src/pipeline.rs`)
- Scan pipeline → User profile: uses profile (evidence: `src/pipeline.rs`)
- Keyword scoring → User profile: uses scoring profile (evidence: `src/score.rs`)
- Scan pipeline → LLM scoring: reranks shortlist (evidence: `src/pipeline.rs`)
- Custom page reader → LLM scoring: extracts job listings (evidence: `src/custom_page.rs`)
- Web API → Careers URL detection: validates careers URL (evidence: `src/server.rs`)
- Careers URL detection → Fetcher dispatch: validates board (evidence: `src/detect.rs`)
- Scan pipeline → Custom page reader: reads custom pages (evidence: `src/pipeline.rs`)
- LLM scoring → Groq API: requests scoring (evidence: `README.md`)
- Scan pipeline → SQLite database: stores scan results (evidence: `src/pipeline.rs`)
- Web API → SQLite database: reads and updates (evidence: `src/server.rs`)
- Web API → Web dashboard: serves embedded UI (evidence: `README.md`)
- CLI commands → SQLite database: reads and updates (evidence: `src/main.rs`)
- CLI commands → Digest email: sends digest (evidence: `src/main.rs`)
- Digest email → SQLite database: loads and marks matches (evidence: `src/email.rs`)
- Digest email → Resend API: sends email (evidence: `README.md`)
