# shizzka/job-hunter architecture

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

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

## Overview

Job Hunter automates a safety-first job-search workflow: it searches and deduplicates vacancies, filters and evaluates fit, grounds candidate-facing text in profile evidence, then skips, queues for review, or applies through platform adapters. Telegram provides human control and approval; separate workflows cover HH chat replies and recruiter Google Forms. Local profile-scoped state and analytics support isolation and outcome tracking. Edges reflect README descriptions and SOURCE INDEX references; several central implementations were not excerpted, so their internal links are documented rather than inferred from names.

Main entry points: [`search_pipeline.py`](https://github.com/shizzka/job-hunter/blob/main/search_pipeline.py) (Vacancy search), [`hh/apply.py`](https://github.com/shizzka/job-hunter/blob/main/hh/apply.py) (HH applications), [`answer_grounding.py`](https://github.com/shizzka/job-hunter/blob/main/answer_grounding.py) (Answer grounding), [`telegram_app/callbacks.py`](https://github.com/shizzka/job-hunter/blob/main/telegram_app/callbacks.py) (Telegram control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_search["Search and matching"]
  node_search_flow["Vacancy search<br/>[search_pipeline.py]"]
  node_board_adapters["Board adapters"]
  node_filters["Pre-filters<br/>[filters.py]"]
  node_matcher["LLM matcher<br/>[matcher.py]"]
  node_decision["Apply decision"]
end

subgraph group_candidate["Candidate evidence"]
  node_profile["Candidate profiles<br/>[profile.py]"]
  node_facts["Candidate facts<br/>[facts.py]"]
  node_grounding["Answer grounding"]
  node_prompts["Prompt context<br/>[prompt_blocks.py]"]
  node_llm["LLM providers<br/>[llm_client.py]"]
end

subgraph group_apply["Applications and forms"]
  node_hh_apply["HH applications<br/>[apply.py]"]
  node_hh_client["HH adapter<br/>[hh_client.py]"]
  node_safety["Browser safety"]
  node_forms["Google Forms"]
  node_form_workflow["Form approvals<br/>[workflow.py]"]
  node_form_drafts["Form drafts<br/>[drafts.py]"]
end

subgraph group_control["Human control"]
  node_telegram["Telegram control<br/>[callbacks.py]"]
  node_notifier["Notifications<br/>[notifier.py]"]
  node_chat["HH chat replies"]
end

subgraph group_state["State and insights"]
  node_analytics["Application analytics<br/>[analytics.py]"]
  node_state[("Profile state<br/>[json_store.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_candidate(("Candidate"))
node_boards(("Job boards"))

node_boards -->|"provide vacancies"| node_search_flow
node_search_flow -->|"queries sources"| node_board_adapters
node_search_flow -.->|"filters results"| node_filters
node_search_flow -->|"evaluates fit"| node_matcher
node_matcher -.->|"requests scoring"| node_llm
node_search_flow -.->|"routes matches"| node_decision
node_candidate -->|"sets up profile"| node_profile
node_profile -->|"isolates facts"| node_facts
node_profile -->|"isolates runtime state"| node_state
node_grounding -->|"loads evidence"| node_facts
node_grounding -->|"builds context"| node_prompts
node_grounding -->|"grounds answers"| node_llm
node_decision -->|"selects apply path"| node_hh_apply
node_hh_apply -->|"uses platform adapter"| node_hh_client
node_hh_apply -->|"checks browser actions"| node_safety
node_hh_apply -.->|"records outcomes"| node_analytics
node_telegram -->|"routes form actions"| node_forms
node_forms -->|"uses revisions"| node_form_workflow
node_form_workflow -->|"claims drafts"| node_form_drafts
node_form_drafts -->|"persists drafts"| node_state
node_telegram -->|"routes chat actions"| node_chat
node_telegram -.->|"sends controls"| node_notifier
node_search_flow -->|"records funnel"| node_analytics
node_analytics -->|"persists events"| node_state
node_search_flow -->|"reads search settings"| node_config

click node_search_flow "https://github.com/shizzka/job-hunter/blob/main/search_pipeline.py"
click node_filters "https://github.com/shizzka/job-hunter/blob/main/filters.py"
click node_matcher "https://github.com/shizzka/job-hunter/blob/main/matcher.py"
click node_decision "https://github.com/shizzka/job-hunter/blob/main/apply_orchestrator.py"
click node_profile "https://github.com/shizzka/job-hunter/blob/main/profile.py"
click node_facts "https://github.com/shizzka/job-hunter/blob/main/facts.py"
click node_grounding "https://github.com/shizzka/job-hunter/blob/main/answer_grounding.py"
click node_prompts "https://github.com/shizzka/job-hunter/blob/main/prompt_blocks.py"
click node_llm "https://github.com/shizzka/job-hunter/blob/main/llm_client.py"
click node_hh_apply "https://github.com/shizzka/job-hunter/blob/main/hh/apply.py"
click node_hh_client "https://github.com/shizzka/job-hunter/blob/main/hh_client.py"
click node_safety "https://github.com/shizzka/job-hunter/blob/main/browser_action_boundary.py"
click node_forms "https://github.com/shizzka/job-hunter/blob/main/google_form_filler.py"
click node_form_workflow "https://github.com/shizzka/job-hunter/blob/main/google_forms/workflow.py"
click node_form_drafts "https://github.com/shizzka/job-hunter/blob/main/google_forms/drafts.py"
click node_telegram "https://github.com/shizzka/job-hunter/blob/main/telegram_app/callbacks.py"
click node_notifier "https://github.com/shizzka/job-hunter/blob/main/notifier.py"
click node_chat "https://github.com/shizzka/job-hunter/blob/main/hh_chat_responder.py"
click node_analytics "https://github.com/shizzka/job-hunter/blob/main/analytics.py"
click node_state "https://github.com/shizzka/job-hunter/blob/main/state_store/json_store.py"
click node_config "https://github.com/shizzka/job-hunter/blob/main/config.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_search_flow,node_board_adapters,node_filters,node_matcher,node_decision toneBlue
class node_profile,node_facts,node_grounding,node_prompts,node_llm toneAmber
class node_hh_apply,node_hh_client,node_safety,node_forms,node_form_workflow,node_form_drafts toneMint
class node_telegram,node_notifier,node_chat toneRose
class node_analytics,node_state,node_config,node_candidate,node_boards toneIndigo
```

## Components

### Search and matching

- [Vacancy search](https://github.com/shizzka/job-hunter/blob/main/search_pipeline.py): `search_pipeline.py`
- **Board adapters**
- [Pre-filters](https://github.com/shizzka/job-hunter/blob/main/filters.py): `filters.py`
- [LLM matcher](https://github.com/shizzka/job-hunter/blob/main/matcher.py): `matcher.py`
- [Apply decision](https://github.com/shizzka/job-hunter/blob/main/apply_orchestrator.py): `apply_orchestrator.py`

### Candidate evidence

- [Candidate profiles](https://github.com/shizzka/job-hunter/blob/main/profile.py): `profile.py`
- [Candidate facts](https://github.com/shizzka/job-hunter/blob/main/facts.py): `facts.py`
- [Answer grounding](https://github.com/shizzka/job-hunter/blob/main/answer_grounding.py): `answer_grounding.py`
- [Prompt context](https://github.com/shizzka/job-hunter/blob/main/prompt_blocks.py): `prompt_blocks.py`
- [LLM providers](https://github.com/shizzka/job-hunter/blob/main/llm_client.py): `llm_client.py`

### Applications and forms

- [HH applications](https://github.com/shizzka/job-hunter/blob/main/hh/apply.py): `hh/apply.py`
- [HH adapter](https://github.com/shizzka/job-hunter/blob/main/hh_client.py): `hh_client.py`
- [Browser safety](https://github.com/shizzka/job-hunter/blob/main/browser_action_boundary.py): `browser_action_boundary.py`
- [Google Forms](https://github.com/shizzka/job-hunter/blob/main/google_form_filler.py): `google_form_filler.py`
- [Form approvals](https://github.com/shizzka/job-hunter/blob/main/google_forms/workflow.py): `google_forms/workflow.py`
- [Form drafts](https://github.com/shizzka/job-hunter/blob/main/google_forms/drafts.py): `google_forms/drafts.py`

### Human control

- [Telegram control](https://github.com/shizzka/job-hunter/blob/main/telegram_app/callbacks.py): `telegram_app/callbacks.py`
- [Notifications](https://github.com/shizzka/job-hunter/blob/main/notifier.py): `notifier.py`
- [HH chat replies](https://github.com/shizzka/job-hunter/blob/main/hh_chat_responder.py): `hh_chat_responder.py`

### State and insights

- [Application analytics](https://github.com/shizzka/job-hunter/blob/main/analytics.py): `analytics.py`
- [Profile state](https://github.com/shizzka/job-hunter/blob/main/state_store/json_store.py): `state_store/json_store.py`
- [Runtime configuration](https://github.com/shizzka/job-hunter/blob/main/config.py): `config.py`

### Other components

- **Candidate**
- **Job boards**

## Connections

- Job boards → Vacancy search: provide vacancies (evidence: `README.md`)
- Vacancy search → Board adapters: queries sources (evidence: `search_pipeline.py`)
- Vacancy search → Pre-filters: filters results (evidence: `search_pipeline.py`)
- Vacancy search → LLM matcher: evaluates fit (evidence: `README.md`)
- LLM matcher → LLM providers: requests scoring
- Vacancy search → Apply decision: routes matches
- Candidate → Candidate profiles: sets up profile (evidence: `README.md`)
- Candidate profiles → Candidate facts: isolates facts (evidence: `README.md`)
- Candidate profiles → Profile state: isolates runtime state (evidence: `README.md`)
- Answer grounding → Candidate facts: loads evidence (evidence: `answer_grounding.py`)
- Answer grounding → Prompt context: builds context (evidence: `answer_grounding.py`)
- Answer grounding → LLM providers: grounds answers (evidence: `answer_grounding.py`)
- Apply decision → HH applications: selects apply path (evidence: `README.md`)
- HH applications → HH adapter: uses platform adapter (evidence: `hh_client.py`)
- HH applications → Browser safety: checks browser actions (evidence: `hh/apply.py`)
- HH applications → Application analytics: records outcomes
- Telegram control → Google Forms: routes form actions (evidence: `telegram_app/callbacks.py`)
- Google Forms → Form approvals: uses revisions (evidence: `google_form_filler.py`)
- Form approvals → Form drafts: claims drafts (evidence: `google_forms/workflow.py`)
- Form drafts → Profile state: persists drafts (evidence: `google_forms/drafts.py`)
- Telegram control → HH chat replies: routes chat actions (evidence: `telegram_app/callbacks.py`)
- Telegram control → Notifications: sends controls
- Vacancy search → Application analytics: records funnel (evidence: `search_pipeline.py`)
- Application analytics → Profile state: persists events (evidence: `analytics.py`)
- Vacancy search → Runtime configuration: reads search settings (evidence: `search_pipeline.py`)
