# akash030605/job_hunt_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/akash030605/job_hunt_assistant
- Repository: https://github.com/akash030605/job_hunt_assistant

## Overview

Job Hunt Assistant is a terminal workflow that turns a resume into a candidate profile, collects and filters company job postings, scores matches, drafts application emails, and optionally sends a digest. The CLI orchestrates both profile creation and job runs; configuration, normalized data models, and persistent JSON files support those stages. The README documents the three ATS integrations and terminal results. Source excerpts show the main orchestration and integrations; unsampled implementation details are omitted where their connections are not evidenced.

Main entry points: [`jobhunt-project/jobhunt/cli.py`](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/cli.py) (CLI Orchestrator), [`jobhunt-project/jobhunt/__main__.py`](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/__main__.py) (Module Entry), [`jobhunt-project/jobhunt/config.py`](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/config.py) (Settings Loader), [`jobhunt-project/jobhunt/fetcher.py`](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/fetcher.py) (ATS Job Fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI Workflow"]
  node_entry["Module Entry<br/>[__main__.py]"]
  node_cli["CLI Orchestrator<br/>[cli.py]"]
  node_settings["Settings Loader<br/>[config.py]"]
  node_preferences["Run Preferences<br/>[config.yaml]"]
end

subgraph group_jobs["Job Discovery"]
  node_company_list["Company Sources<br/>[companies.yaml]"]
  node_fetch["ATS Job Fetcher<br/>[fetcher.py]"]
  node_ats{{"Public ATS APIs"}}
  node_prefilter["Free Prefilter<br/>[prefilter.py]"]
end

subgraph group_matching["Profile and Matching"]
  node_profile_parse["Resume Profile Parsing<br/>[llm.py]"]
  node_resume["Resume PDF<br/>[resume.pdf]"]
  node_profile_data["Candidate Profile<br/>[profile.json]"]
  node_matching_data["Shared Data Models<br/>[models.py]"]
  node_gemini{{"Gemini API"}}
  node_score_draft["Scoring and Drafting<br/>[llm.py]"]
end

subgraph group_delivery["Persistence and Delivery"]
  node_seen_store["Seen Job Store<br/>[store.py]"]
  node_seen_data[("Seen Jobs<br/>[seen.json]")]
  node_digest["Digest Output<br/>[digest.json]"]
  node_terminal_results["Terminal Results<br/>[cli.py]"]
  node_mailer["HTML Digest Mailer<br/>[mailer.py]"]
  node_smtp{{"SMTP Service"}}
end

node_user(("Terminal User"))

node_user -->|"runs commands"| node_entry
node_entry -->|"starts app"| node_cli
node_cli -->|"loads settings"| node_settings
node_settings -->|"reads YAML"| node_preferences
node_cli -->|"loads companies"| node_company_list
node_cli -->|"fetches jobs"| node_fetch
node_fetch -->|"requests postings"| node_ats
node_cli -->|"filters jobs"| node_prefilter
node_cli -->|"reads PDF"| node_resume
node_cli -->|"requests extraction"| node_profile_parse
node_profile_parse -->|"parses resume"| node_gemini
node_cli -->|"saves profile"| node_profile_data
node_cli -->|"builds scored jobs"| node_matching_data
node_cli -->|"scores and drafts"| node_score_draft
node_score_draft -->|"scores and drafts"| node_gemini
node_cli -->|"checks and marks"| node_seen_store
node_seen_store -->|"reads and writes"| node_seen_data
node_cli -->|"writes results"| node_digest
node_cli -->|"prints table"| node_terminal_results
node_cli -->|"sends digest"| node_mailer
node_mailer -->|"sends email"| node_smtp

click node_entry "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/__main__.py"
click node_cli "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/cli.py"
click node_settings "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/config.py"
click node_preferences "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/config.yaml"
click node_company_list "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/companies.yaml"
click node_fetch "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/fetcher.py"
click node_prefilter "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/prefilter.py"
click node_profile_parse "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/llm.py"
click node_resume "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/resume.pdf"
click node_profile_data "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/profile.json"
click node_matching_data "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/models.py"
click node_score_draft "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/llm.py"
click node_seen_store "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/store.py"
click node_seen_data "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/seen.json"
click node_digest "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/out/digest.json"
click node_terminal_results "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/cli.py"
click node_mailer "https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/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_entry,node_cli,node_settings,node_preferences,node_user toneBlue
class node_company_list,node_fetch,node_ats,node_prefilter toneAmber
class node_profile_parse,node_resume,node_profile_data,node_matching_data,node_gemini,node_score_draft toneMint
class node_seen_store,node_seen_data,node_digest,node_terminal_results,node_mailer,node_smtp toneRose
```

## Components

### CLI Workflow

- [Module Entry](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/__main__.py): `jobhunt-project/jobhunt/__main__.py`
- [CLI Orchestrator](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/cli.py): `jobhunt-project/jobhunt/cli.py`
- [Settings Loader](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/config.py): `jobhunt-project/jobhunt/config.py`
- [Run Preferences](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/config.yaml): `jobhunt-project/config.yaml`

### Job Discovery

- [Company Sources](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/companies.yaml): `jobhunt-project/companies.yaml`
- [ATS Job Fetcher](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/fetcher.py): `jobhunt-project/jobhunt/fetcher.py`
- **Public ATS APIs**
- [Free Prefilter](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/prefilter.py): `jobhunt-project/jobhunt/prefilter.py`

### Profile and Matching

- [Resume Profile Parsing](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/llm.py): `jobhunt-project/jobhunt/llm.py`
- [Resume PDF](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/resume.pdf): `jobhunt-project/resume.pdf`
- [Candidate Profile](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/profile.json): `jobhunt-project/profile.json`
- [Shared Data Models](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/models.py): `jobhunt-project/jobhunt/models.py`
- **Gemini API**
- [Scoring and Drafting](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/llm.py): `jobhunt-project/jobhunt/llm.py`

### Persistence and Delivery

- [Seen Job Store](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/store.py): `jobhunt-project/jobhunt/store.py`
- [Seen Jobs](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/seen.json): `jobhunt-project/seen.json`
- [Digest Output](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/out/digest.json): `jobhunt-project/out/digest.json`
- [Terminal Results](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/cli.py): `jobhunt-project/jobhunt/cli.py`
- [HTML Digest Mailer](https://github.com/akash030605/job_hunt_assistant/blob/main/jobhunt-project/jobhunt/mailer.py): `jobhunt-project/jobhunt/mailer.py`
- **SMTP Service**

### Other components

- **Terminal User**

## Connections

- Terminal User → Module Entry: runs commands (evidence: `README.md`)
- Module Entry → CLI Orchestrator: starts app (evidence: `jobhunt-project/jobhunt/__main__.py`)
- CLI Orchestrator → Settings Loader: loads settings (evidence: `jobhunt-project/jobhunt/cli.py`)
- Settings Loader → Run Preferences: reads YAML (evidence: `jobhunt-project/jobhunt/config.py`)
- CLI Orchestrator → Company Sources: loads companies (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → ATS Job Fetcher: fetches jobs (evidence: `jobhunt-project/jobhunt/cli.py`)
- ATS Job Fetcher → Public ATS APIs: requests postings (evidence: `jobhunt-project/jobhunt/fetcher.py`)
- CLI Orchestrator → Free Prefilter: filters jobs (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → Resume PDF: reads PDF (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → Resume Profile Parsing: requests extraction (evidence: `jobhunt-project/jobhunt/cli.py`)
- Resume Profile Parsing → Gemini API: parses resume (evidence: `jobhunt-project/jobhunt/llm.py`)
- CLI Orchestrator → Candidate Profile: saves profile (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → Shared Data Models: builds scored jobs (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → Scoring and Drafting: scores and drafts (evidence: `jobhunt-project/jobhunt/cli.py`)
- Scoring and Drafting → Gemini API: scores and drafts (evidence: `jobhunt-project/jobhunt/llm.py`)
- CLI Orchestrator → Seen Job Store: checks and marks (evidence: `jobhunt-project/jobhunt/cli.py`)
- Seen Job Store → Seen Jobs: reads and writes (evidence: `jobhunt-project/jobhunt/store.py`)
- CLI Orchestrator → Digest Output: writes results (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → Terminal Results: prints table (evidence: `jobhunt-project/jobhunt/cli.py`)
- CLI Orchestrator → HTML Digest Mailer: sends digest (evidence: `jobhunt-project/jobhunt/cli.py`)
- HTML Digest Mailer → SMTP Service: sends email (evidence: `jobhunt-project/jobhunt/mailer.py`)
