# s3rgeym/hh-applicant-tool architecture

> Architecture diagram of the GitHub repository s3rgeym/hh-applicant-tool, 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/s3rgeym/hh-applicant-tool
- Repository: https://github.com/s3rgeym/hh-applicant-tool

## Overview

HH Applicant Tool is a local CLI and scriptable job-application assistant for HeadHunter. Users authorize an account, manage profiles and resumes, then apply to vacancies; application handling can generate cover letters, address tests, and send employer messages or email. A browser-based UI supports profile and preset management. Local storage retains resumes, vacancies, employer details, contacts, and settings. The README documents major capabilities that are not fully visible in sampled implementation excerpts; those branches are shown as unverified where wiring is not evidenced.

Main entry points: [`src/hh_applicant_tool/operations/apply_vacancies.py`](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py) (Vacancy applications), [`src/hh_applicant_tool/api/client.py`](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/api/client.py) (HeadHunter API), [`src/hh_applicant_tool/ui/api.py`](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ui/api.py) (Browser UI), [`src/hh_applicant_tool/main.py`](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/main.py) (CLI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI runtime<br/>[main.py]"]
  node_webui["Browser UI<br/>[api.py]"]
end

subgraph group_application["Applications"]
  node_vacancy_apply["Vacancy applications<br/>[apply_vacancies.py]"]
  node_letter_ai["Letter generation<br/>[openai.py]"]
  node_test_solving["Application tests<br/>[apply_vacancies.py]"]
  node_employer_chat["Employer chat<br/>[reply_employers.py]"]
  node_email["Employer email<br/>[apply_vacancies.py]"]
  node_autoresponder["Chat autoresponder<br/>[autoresponder.py]"]
end

subgraph group_account["Accounts and profiles"]
  node_authorization["Browser authorization<br/>[authorize.py]"]
  node_profiles["Profiles and presets<br/>[profiles.py]"]
  node_hh_api["HeadHunter API<br/>[client.py]"]
end

subgraph group_persistence["Local persistence"]
  node_storage_facade["Storage facade<br/>[facade.py]"]
  node_repositories["Data repositories<br/>[base.py]"]
  node_models["Stored data models<br/>[base.py]"]
  node_sqlite[("Local database<br/>[utils.py]")]
end

node_user(("Applicant"))
node_hh_service["HeadHunter"]
node_ai_service["OpenAI-compatible AI"]
node_employers(("Employers"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses browser UI"| node_webui
node_cli -->|"creates client"| node_hh_api
node_cli -->|"uses storage"| node_storage_facade
node_webui -->|"routes authorization"| node_authorization
node_webui -->|"routes applications"| node_vacancy_apply
node_webui -->|"uses profiles"| node_profiles
node_profiles -.->|"configures account"| node_hh_api
node_authorization -.->|"authorizes account"| node_hh_api
node_vacancy_apply -.->|"requests vacancies"| node_hh_api
node_hh_api -.->|"sends API requests"| node_hh_service
node_vacancy_apply -.->|"generates letters"| node_letter_ai
node_letter_ai -.->|"requests generation"| node_ai_service
node_vacancy_apply -->|"handles tests"| node_test_solving
node_vacancy_apply -->|"sends email"| node_email
node_vacancy_apply -.->|"messages employers"| node_employer_chat
node_autoresponder -.->|"replies in chats"| node_employers
node_vacancy_apply -.->|"saves vacancy data"| node_storage_facade
node_storage_facade -->|"creates repositories"| node_repositories
node_repositories -->|"maps records"| node_models
node_repositories -.->|"reads and writes"| node_sqlite

click node_cli "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/main.py"
click node_webui "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ui/api.py"
click node_authorization "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/authorize.py"
click node_profiles "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ui/profiles.py"
click node_vacancy_apply "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py"
click node_letter_ai "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ai/openai.py"
click node_test_solving "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py"
click node_employer_chat "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/reply_employers.py"
click node_email "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py"
click node_autoresponder "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/autoresponder.py"
click node_hh_api "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/api/client.py"
click node_storage_facade "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/facade.py"
click node_repositories "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/repositories/base.py"
click node_models "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/models/base.py"
click node_sqlite "https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/utils.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_webui toneBlue
class node_vacancy_apply,node_letter_ai,node_test_solving,node_employer_chat,node_email,node_autoresponder toneAmber
class node_authorization,node_profiles,node_hh_api toneMint
class node_storage_facade,node_repositories,node_models,node_sqlite toneRose
class node_user,node_hh_service,node_ai_service,node_employers toneIndigo
```

## Components

### User entry

- [CLI runtime](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/main.py): `src/hh_applicant_tool/main.py`
- [Browser UI](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ui/api.py): `src/hh_applicant_tool/ui/api.py`

### Applications

- [Vacancy applications](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py): `src/hh_applicant_tool/operations/apply_vacancies.py`
- [Letter generation](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ai/openai.py): `src/hh_applicant_tool/ai/openai.py`
- [Application tests](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py): `src/hh_applicant_tool/operations/apply_vacancies.py`
- [Employer chat](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/reply_employers.py): `src/hh_applicant_tool/operations/reply_employers.py`
- [Employer email](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/apply_vacancies.py): `src/hh_applicant_tool/operations/apply_vacancies.py`
- [Chat autoresponder](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/autoresponder.py): `src/hh_applicant_tool/operations/autoresponder.py`

### Accounts and profiles

- [Browser authorization](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/operations/authorize.py): `src/hh_applicant_tool/operations/authorize.py`
- [Profiles and presets](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/ui/profiles.py): `src/hh_applicant_tool/ui/profiles.py`
- [HeadHunter API](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/api/client.py): `src/hh_applicant_tool/api/client.py`

### Local persistence

- [Storage facade](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/facade.py): `src/hh_applicant_tool/storage/facade.py`
- [Data repositories](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/repositories/base.py): `src/hh_applicant_tool/storage/repositories/base.py`
- [Stored data models](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/models/base.py): `src/hh_applicant_tool/storage/models/base.py`
- [Local database](https://github.com/s3rgeym/hh-applicant-tool/blob/main/src/hh_applicant_tool/storage/utils.py): `src/hh_applicant_tool/storage/utils.py`

### Other components

- **Applicant**
- **HeadHunter**
- **OpenAI-compatible AI**
- **Employers**

## Connections

- Applicant → CLI runtime: runs commands (evidence: `README.md`)
- Applicant → Browser UI: uses browser UI (evidence: `README.md`)
- CLI runtime → HeadHunter API: creates client (evidence: `src/hh_applicant_tool/main.py`)
- CLI runtime → Storage facade: uses storage (evidence: `src/hh_applicant_tool/main.py`)
- Browser UI → Browser authorization: routes authorization (evidence: `src/hh_applicant_tool/ui/api.py`)
- Browser UI → Vacancy applications: routes applications (evidence: `src/hh_applicant_tool/ui/api.py`)
- Browser UI → Profiles and presets: uses profiles (evidence: `src/hh_applicant_tool/ui/api.py`)
- Profiles and presets → HeadHunter API: configures account
- Browser authorization → HeadHunter API: authorizes account
- Vacancy applications → HeadHunter API: requests vacancies
- HeadHunter API → HeadHunter: sends API requests
- Vacancy applications → Letter generation: generates letters
- Letter generation → OpenAI-compatible AI: requests generation
- Vacancy applications → Application tests: handles tests (evidence: `src/hh_applicant_tool/operations/apply_vacancies.py`)
- Vacancy applications → Employer email: sends email (evidence: `src/hh_applicant_tool/operations/apply_vacancies.py`)
- Vacancy applications → Employer chat: messages employers
- Chat autoresponder → Employers: replies in chats
- Vacancy applications → Storage facade: saves vacancy data
- Storage facade → Data repositories: creates repositories (evidence: `src/hh_applicant_tool/storage/facade.py`)
- Data repositories → Stored data models: maps records (evidence: `src/hh_applicant_tool/storage/repositories/base.py`)
- Data repositories → Local database: reads and writes
