# sunilbelde/job-hunt-hq architecture

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

- Interactive diagram: https://gitdiagram.com/sunilbelde/job-hunt-hq
- Repository: https://github.com/sunilbelde/job-hunt-hq

## Overview

job-hunt-hq is a locally hosted job-application service. A user or external tool records a posting, then requests a resume or cover letter; the service retrieves the stored application, generates and checks a document, saves it locally, and exposes job status. The local viewer also supports application management and form-filling workflows, while email-status updates and applying from a link are separate capabilities. Relationships are based on the README and supplied source excerpts/index; some route details and subsystem internals were not sampled.

Main entry points: [`app/main.py`](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/main.py) (HTTP API), [`app/cover_letter.py`](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/cover_letter.py) (Cover Letter Writing), [`app/generation.py`](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/generation.py) (Resume Selection), [`app/tailoring.py`](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/tailoring.py) (Resume Tailoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_service["HTTP API<br/>[main.py]"]
  node_listener["Local Listeners<br/>[serve.py]"]
  node_models["Request Models<br/>[models.py]"]
end

subgraph group_records["Applications"]
  node_appstore[("Application Store<br/>[applications.py]")]
  node_record["Application Record<br/>[models.py]"]
end

subgraph group_documents["Document Generation"]
  node_resume["Resume Selection<br/>[generation.py]"]
  node_tailoring["Resume Tailoring<br/>[tailoring.py]"]
  node_coverletter["Cover Letter Writing<br/>[cover_letter.py]"]
  node_renderer["PDF Rendering<br/>[rendering.py]"]
end

subgraph group_viewer["Viewer Workflows"]
  node_viewer["Resume Viewer<br/>[viewer.py]"]
  node_formfill["Form Filler<br/>[form_filler.py]"]
end

subgraph group_runtime["Local Runtime"]
  node_settings["Configuration<br/>[settings.py]"]
  node_files[("Document Storage<br/>[storage.py]")]
end

node_caller(("User or Tool"))
node_claude{{"Claude Code"}}
node_tectonic{{"Tectonic"}}
node_herdr{{"Herdr"}}

node_caller -->|"sends requests"| node_listener
node_listener -->|"routes requests"| node_service
node_service -->|"uses config"| node_settings
node_service -->|"validates requests"| node_models
node_service -->|"records and updates"| node_appstore
node_appstore -->|"stores records"| node_record
node_service -->|"starts resume job"| node_resume
node_resume -->|"scores and tailors"| node_tailoring
node_resume -->|"renders base PDF"| node_renderer
node_tailoring -->|"runs skill"| node_claude
node_renderer -->|"compiles TeX"| node_tectonic
node_service -->|"starts letter job"| node_coverletter
node_coverletter -->|"uses run support"| node_tailoring
node_coverletter -->|"runs writing skill"| node_claude
node_coverletter -->|"renders PDF"| node_renderer
node_service -->|"saves outputs"| node_files
node_service -->|"serves viewer"| node_viewer
node_viewer -->|"calls viewer endpoints"| node_service
node_service -->|"starts form filling"| node_formfill
node_formfill -->|"opens workspace tabs"| node_herdr

click node_service "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/main.py"
click node_listener "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/serve.py"
click node_settings "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/settings.py"
click node_models "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/models.py"
click node_appstore "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/applications.py"
click node_record "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/models.py"
click node_resume "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/generation.py"
click node_tailoring "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/tailoring.py"
click node_coverletter "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/cover_letter.py"
click node_renderer "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/rendering.py"
click node_files "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/storage.py"
click node_viewer "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/viewer.py"
click node_formfill "https://github.com/sunilbelde/job-hunt-hq/blob/main/app/form_filler.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_service,node_listener,node_models,node_caller toneBlue
class node_appstore,node_record toneAmber
class node_resume,node_tailoring,node_coverletter,node_renderer toneMint
class node_viewer,node_formfill toneRose
class node_settings,node_files,node_claude,node_tectonic,node_herdr toneIndigo
```

## Components

### Service API

- [HTTP API](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/main.py): `app/main.py`
- [Local Listeners](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/serve.py): `app/serve.py`
- [Request Models](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/models.py): `app/models.py`

### Applications

- [Application Store](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/applications.py): `app/applications.py`
- [Application Record](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/models.py): `app/models.py`

### Document Generation

- [Resume Selection](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/generation.py): `app/generation.py`
- [Resume Tailoring](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/tailoring.py): `app/tailoring.py`
- [Cover Letter Writing](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/cover_letter.py): `app/cover_letter.py`
- [PDF Rendering](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/rendering.py): `app/rendering.py`

### Viewer Workflows

- [Resume Viewer](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/viewer.py): `app/viewer.py`
- [Form Filler](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/form_filler.py): `app/form_filler.py`

### Local Runtime

- [Configuration](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/settings.py): `app/settings.py`
- [Document Storage](https://github.com/sunilbelde/job-hunt-hq/blob/main/app/storage.py): `app/storage.py`

### Other components

- **User or Tool**
- **Claude Code**
- **Tectonic**
- **Herdr**

## Connections

- User or Tool → Local Listeners: sends requests (evidence: `README.md`)
- Local Listeners → HTTP API: routes requests (evidence: `app/serve.py`)
- HTTP API → Configuration: uses config (evidence: `app/main.py`)
- HTTP API → Request Models: validates requests (evidence: `app/main.py`)
- HTTP API → Application Store: records and updates (evidence: `app/main.py`)
- Application Store → Application Record: stores records (evidence: `app/applications.py`)
- HTTP API → Resume Selection: starts resume job (evidence: `README.md`)
- Resume Selection → Resume Tailoring: scores and tailors (evidence: `app/generation.py`)
- Resume Selection → PDF Rendering: renders base PDF (evidence: `app/generation.py`)
- Resume Tailoring → Claude Code: runs skill (evidence: `app/tailoring.py`)
- PDF Rendering → Tectonic: compiles TeX (evidence: `app/rendering.py`)
- HTTP API → Cover Letter Writing: starts letter job (evidence: `README.md`)
- Cover Letter Writing → Resume Tailoring: uses run support (evidence: `app/cover_letter.py`)
- Cover Letter Writing → Claude Code: runs writing skill (evidence: `app/cover_letter.py`)
- Cover Letter Writing → PDF Rendering: renders PDF (evidence: `app/cover_letter.py`)
- HTTP API → Document Storage: saves outputs (evidence: `README.md`)
- HTTP API → Resume Viewer: serves viewer (evidence: `README.md`)
- Resume Viewer → HTTP API: calls viewer endpoints (evidence: `app/viewer.py`)
- HTTP API → Form Filler: starts form filling (evidence: `app/main.py`)
- Form Filler → Herdr: opens workspace tabs (evidence: `app/form_filler.py`)