# perryvegehan/pwp_jobhunt architecture

> Architecture diagram of the GitHub repository perryvegehan/pwp_jobhunt, 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/perryvegehan/pwp_jobhunt
- Repository: https://github.com/perryvegehan/pwp_jobhunt

## Overview

jobhunt is a personal job-search agent: it fetches public ATS postings, filters and deduplicates them, screens and ranks matches, drafts optional application materials, then builds and optionally emails a digest for human review. It also turns a resume into a reusable profile and tracks seen/applied jobs with CSV export. The CLI owns the workflow; sampled fetch, filter, LLM, storage, rendering, and mail code supports the main boundaries. Some stage wiring is documented in the README rather than fully visible in the excerpts.

Main entry points: [`jobhunt/cli.py`](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/cli.py) (CLI workflow), [`jobhunt/llm.py`](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/llm.py) (Resume profile), [`jobhunt/fetch.py`](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/fetch.py) (ATS fetch and parse), [`jobhunt/store.py`](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/store.py) (Seen and applied tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and profile"]
  node_cli["CLI workflow<br/>[cli.py]"]
  node_profile["Resume profile<br/>[llm.py]"]
  node_profile_file["Profile JSON"]
end

subgraph group_jobs["Job discovery"]
  node_fetch["ATS fetch and parse<br/>[fetch.py]"]
  node_mock["Mock board payloads<br/>[mock.py]"]
  node_prefilter["Title/location/age gate<br/>[prefilter.py]"]
end

subgraph group_matching["Matching and drafting"]
  node_llm["Screen and draft<br/>[llm.py]"]
  node_providers["LLM provider clients<br/>[providers.py]"]
end

subgraph group_delivery["Digest and tracking"]
  node_store[("Seen and applied tracker<br/>[store.py]")]
  node_digest["HTML digest<br/>[digest.py]"]
  node_digest_file["Digest HTML file"]
  node_mailer["SMTP mailer<br/>[mailer.py]"]
  node_tracker_csv["Tracker CSV"]
end

node_user(("Job seeker"))
node_ats["Public ATS boards"]
node_llm_services["LLM services"]
node_smtp["SMTP service"]

node_user -->|"runs commands"| node_cli
node_cli -->|"builds profile"| node_profile
node_profile -->|"extracts resume data"| node_llm_services
node_profile -->|"writes profile"| node_profile_file
node_cli -->|"loads profile"| node_profile_file
node_cli -->|"fetches boards"| node_fetch
node_fetch -->|"requests postings"| node_ats
node_cli -->|"selects mock data"| node_mock
node_mock -->|"uses real parsers"| node_fetch
node_cli -->|"filters postings"| node_prefilter
node_cli -->|"deduplicates jobs"| node_store
node_cli -->|"screens and drafts"| node_llm
node_llm -->|"requests completions"| node_providers
node_providers -->|"calls provider APIs"| node_llm_services
node_cli -->|"builds digest"| node_digest
node_digest -->|"writes HTML"| node_digest_file
node_cli -->|"sends when requested"| node_mailer
node_mailer -->|"sends email"| node_smtp
node_cli -->|"records results"| node_store
node_store -->|"exports CSV"| node_tracker_csv
node_user -->|"reviews digest"| node_digest_file
node_user -->|"marks applied or checks stats"| node_cli

click node_cli "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/cli.py"
click node_profile "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/llm.py"
click node_fetch "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/fetch.py"
click node_mock "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/mock.py"
click node_prefilter "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/prefilter.py"
click node_store "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/store.py"
click node_llm "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/llm.py"
click node_providers "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/providers.py"
click node_digest "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/digest.py"
click node_mailer "https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/mailer.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_profile,node_profile_file toneBlue
class node_fetch,node_mock,node_prefilter toneAmber
class node_llm,node_providers toneMint
class node_store,node_digest,node_digest_file,node_mailer,node_tracker_csv toneRose
class node_user,node_ats,node_llm_services,node_smtp toneIndigo
```

## Components

### CLI and profile

- [CLI workflow](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/cli.py): `jobhunt/cli.py`
- [Resume profile](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/llm.py): `jobhunt/llm.py`
- **Profile JSON**

### Job discovery

- [ATS fetch and parse](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/fetch.py): `jobhunt/fetch.py`
- [Mock board payloads](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/mock.py): `jobhunt/mock.py`
- [Title/location/age gate](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/prefilter.py): `jobhunt/prefilter.py`

### Matching and drafting

- [Screen and draft](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/llm.py): `jobhunt/llm.py`
- [LLM provider clients](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/providers.py): `jobhunt/providers.py`

### Digest and tracking

- [Seen and applied tracker](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/store.py): `jobhunt/store.py`
- [HTML digest](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/digest.py): `jobhunt/digest.py`
- **Digest HTML file**
- [SMTP mailer](https://github.com/perryvegehan/pwp_jobhunt/blob/main/jobhunt/mailer.py): `jobhunt/mailer.py`
- **Tracker CSV**

### Other components

- **Job seeker**
- **Public ATS boards**
- **LLM services**
- **SMTP service**

## Connections

- Job seeker → CLI workflow: runs commands (evidence: `README.md`)
- CLI workflow → Resume profile: builds profile (evidence: `README.md`)
- Resume profile → LLM services: extracts resume data (evidence: `jobhunt/llm.py`)
- Resume profile → Profile JSON: writes profile (evidence: `README.md`)
- CLI workflow → Profile JSON: loads profile (evidence: `jobhunt/cli.py`)
- CLI workflow → ATS fetch and parse: fetches boards (evidence: `jobhunt/cli.py`)
- ATS fetch and parse → Public ATS boards: requests postings (evidence: `jobhunt/fetch.py`)
- CLI workflow → Mock board payloads: selects mock data (evidence: `jobhunt/cli.py`)
- Mock board payloads → ATS fetch and parse: uses real parsers (evidence: `jobhunt/mock.py`)
- CLI workflow → Title/location/age gate: filters postings (evidence: `jobhunt/cli.py`)
- CLI workflow → Seen and applied tracker: deduplicates jobs (evidence: `README.md`)
- CLI workflow → Screen and draft: screens and drafts (evidence: `jobhunt/cli.py`)
- Screen and draft → LLM provider clients: requests completions (evidence: `jobhunt/llm.py`)
- LLM provider clients → LLM services: calls provider APIs (evidence: `jobhunt/providers.py`)
- CLI workflow → HTML digest: builds digest (evidence: `jobhunt/cli.py`)
- HTML digest → Digest HTML file: writes HTML (evidence: `jobhunt/digest.py`)
- CLI workflow → SMTP mailer: sends when requested (evidence: `jobhunt/cli.py`)
- SMTP mailer → SMTP service: sends email (evidence: `jobhunt/mailer.py`)
- CLI workflow → Seen and applied tracker: records results (evidence: `jobhunt/cli.py`)
- Seen and applied tracker → Tracker CSV: exports CSV (evidence: `README.md`)
- Job seeker → Digest HTML file: reviews digest (evidence: `README.md`)
- Job seeker → CLI workflow: marks applied or checks stats (evidence: `README.md`)
