# f0whb/zugzwang architecture

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

- Interactive diagram: https://gitdiagram.com/f0whb/zugzwang
- Repository: https://github.com/f0whb/zugzwang

## Overview

ZUGZWANG is a local-first desktop workstation for finding German employers, enriching leads, reviewing applications, and sending paced SMTP outreach. The documented path runs from a user search through scraping and local lead results, then contact enrichment, application-PDF preparation, and email dispatch; import/export and saved profiles support that workflow. The graph includes only relationships evidenced by the README or supplied source/index references. Several feature modules are unsampled, so their internal call paths are not asserted.

Main entry points: [`src/services/orchestrator.py`](https://github.com/f0whb/zugzwang/blob/main/src/services/orchestrator.py) (Scraping orchestrator), [`src/core/config.py`](https://github.com/f0whb/zugzwang/blob/main/src/core/config.py) (Local SQLite data), [`src/ui/email_sender_page.py`](https://github.com/f0whb/zugzwang/blob/main/src/ui/email_sender_page.py) (Outreach workspace), [`src/ui/main_window.py`](https://github.com/f0whb/zugzwang/blob/main/src/ui/main_window.py) (Application window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Discovery and leads"]
  node_orchestrator["Scraping orchestrator<br/>[orchestrator.py]"]
  node_scrapers["Portal scrapers"]
  node_browser["Browser automation<br/>[browser.py]"]
  node_lead_models["Lead records<br/>[models.py]"]
  node_export_import["Lead import and export<br/>[export_service.py]"]
end

subgraph group_outreach["Enrichment and outreach"]
  node_enrichment["Website and email enrichment<br/>[website_crawler.py]"]
  node_email_extractor["Email extraction<br/>[email_extractor.py]"]
  node_pdf_builder["Application PDF builder"]
  node_profiles["Sender and applicant profiles<br/>[profile_service.py]"]
  node_smtp["SMTP mail service"]
end

subgraph group_desktop["Desktop experience"]
  node_search_ui["Search workspace<br/>[search_page.py]"]
  node_results_ui["Results review<br/>[results_page.py]"]
  node_edit_ui["Lead editing<br/>[edit_page.py]"]
  node_email_ui["Outreach workspace"]
  node_event_bridge["UI event bridge<br/>[event_bridge.py]"]
  node_main_window["Application window<br/>[main_window.py]"]
end

subgraph group_platform["Local services"]
  node_local_db[("Local SQLite data<br/>[config.py]")]
  node_event_bus["Application events<br/>[events.py]"]
  node_security["License and trial controls<br/>[security.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_backup["Backup and recovery<br/>[backup_service.py]"]
end

node_user(("Candidate or recruiter"))
node_external_portals["German job and business portals"]
node_employer_sites["Employer websites"]
node_email_accounts["User SMTP account"]

node_user -->|"enters search"| node_search_ui
node_search_ui -->|"starts searches"| node_orchestrator
node_orchestrator -->|"dispatches jobs"| node_scrapers
node_orchestrator -->|"manages sessions"| node_browser
node_scrapers -->|"collect listings"| node_external_portals
node_scrapers -.->|"produce leads"| node_lead_models
node_orchestrator -->|"uses import/export"| node_export_import
node_orchestrator -->|"publishes job events"| node_event_bus
node_results_ui -->|"uses job results"| node_orchestrator
node_results_ui -->|"exports results"| node_export_import
node_edit_ui -->|"manages profiles"| node_profiles
node_edit_ui -->|"uses extraction"| node_email_extractor
node_edit_ui -->|"builds applications"| node_pdf_builder
node_email_extractor -->|"finds contacts"| node_employer_sites
node_email_ui -->|"loads profiles"| node_profiles
node_email_ui -->|"sends paced mail"| node_smtp
node_smtp -->|"authenticates and sends"| node_email_accounts
node_email_ui -->|"records outreach"| node_orchestrator
node_export_import -->|"saves project data"| node_local_db
node_profiles -->|"stores profile data"| node_local_db
node_search_ui -->|"uses search history"| node_local_db
node_main_window -->|"hosts workspace"| node_search_ui
node_main_window -->|"hosts results"| node_results_ui
node_main_window -->|"hosts editor"| node_edit_ui
node_main_window -->|"hosts outreach"| node_email_ui
node_event_bridge -->|"subscribes events"| node_event_bus
node_security -->|"persists trial settings"| node_local_db
node_diagnostics -->|"reads configuration"| node_local_db
node_backup -->|"backs up settings"| node_local_db
node_user -->|"reviews and sends"| node_email_ui

click node_search_ui "https://github.com/f0whb/zugzwang/blob/main/src/ui/search_page.py"
click node_orchestrator "https://github.com/f0whb/zugzwang/blob/main/src/services/orchestrator.py"
click node_scrapers "https://github.com/f0whb/zugzwang/tree/main/src/services"
click node_browser "https://github.com/f0whb/zugzwang/blob/main/src/services/browser.py"
click node_lead_models "https://github.com/f0whb/zugzwang/blob/main/src/core/models.py"
click node_results_ui "https://github.com/f0whb/zugzwang/blob/main/src/ui/results_page.py"
click node_enrichment "https://github.com/f0whb/zugzwang/blob/main/src/services/website_crawler.py"
click node_email_extractor "https://github.com/f0whb/zugzwang/blob/main/src/services/email_extractor.py"
click node_edit_ui "https://github.com/f0whb/zugzwang/blob/main/src/ui/edit_page.py"
click node_pdf_builder "https://github.com/f0whb/zugzwang/blob/main/src/services/bewerbung_pdf_service.py"
click node_profiles "https://github.com/f0whb/zugzwang/blob/main/src/services/profile_service.py"
click node_email_ui "https://github.com/f0whb/zugzwang/blob/main/src/ui/email_sender_page.py"
click node_export_import "https://github.com/f0whb/zugzwang/blob/main/src/services/export_service.py"
click node_local_db "https://github.com/f0whb/zugzwang/blob/main/src/core/config.py"
click node_event_bus "https://github.com/f0whb/zugzwang/blob/main/src/core/events.py"
click node_event_bridge "https://github.com/f0whb/zugzwang/blob/main/src/ui/event_bridge.py"
click node_main_window "https://github.com/f0whb/zugzwang/blob/main/src/ui/main_window.py"
click node_security "https://github.com/f0whb/zugzwang/blob/main/src/core/security.py"
click node_diagnostics "https://github.com/f0whb/zugzwang/blob/main/src/diagnostics.py"
click node_backup "https://github.com/f0whb/zugzwang/blob/main/src/services/backup_service.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_orchestrator,node_scrapers,node_browser,node_lead_models,node_export_import,node_email_accounts toneBlue
class node_enrichment,node_email_extractor,node_pdf_builder,node_profiles,node_smtp toneAmber
class node_search_ui,node_results_ui,node_edit_ui,node_email_ui,node_event_bridge,node_main_window toneMint
class node_local_db,node_event_bus,node_security,node_diagnostics,node_backup toneRose
class node_user,node_external_portals,node_employer_sites toneIndigo
```

## Components

### Discovery and leads

- [Scraping orchestrator](https://github.com/f0whb/zugzwang/blob/main/src/services/orchestrator.py): `src/services/orchestrator.py`
- [Portal scrapers](https://github.com/f0whb/zugzwang/tree/main/src/services): `src/services`
- [Browser automation](https://github.com/f0whb/zugzwang/blob/main/src/services/browser.py): `src/services/browser.py`
- [Lead records](https://github.com/f0whb/zugzwang/blob/main/src/core/models.py): `src/core/models.py`
- [Lead import and export](https://github.com/f0whb/zugzwang/blob/main/src/services/export_service.py): `src/services/export_service.py`

### Enrichment and outreach

- [Website and email enrichment](https://github.com/f0whb/zugzwang/blob/main/src/services/website_crawler.py): `src/services/website_crawler.py`
- [Email extraction](https://github.com/f0whb/zugzwang/blob/main/src/services/email_extractor.py): `src/services/email_extractor.py`
- [Application PDF builder](https://github.com/f0whb/zugzwang/blob/main/src/services/bewerbung_pdf_service.py): `src/services/bewerbung_pdf_service.py`
- [Sender and applicant profiles](https://github.com/f0whb/zugzwang/blob/main/src/services/profile_service.py): `src/services/profile_service.py`
- **SMTP mail service**

### Desktop experience

- [Search workspace](https://github.com/f0whb/zugzwang/blob/main/src/ui/search_page.py): `src/ui/search_page.py`
- [Results review](https://github.com/f0whb/zugzwang/blob/main/src/ui/results_page.py): `src/ui/results_page.py`
- [Lead editing](https://github.com/f0whb/zugzwang/blob/main/src/ui/edit_page.py): `src/ui/edit_page.py`
- [Outreach workspace](https://github.com/f0whb/zugzwang/blob/main/src/ui/email_sender_page.py): `src/ui/email_sender_page.py`
- [UI event bridge](https://github.com/f0whb/zugzwang/blob/main/src/ui/event_bridge.py): `src/ui/event_bridge.py`
- [Application window](https://github.com/f0whb/zugzwang/blob/main/src/ui/main_window.py): `src/ui/main_window.py`

### Local services

- [Local SQLite data](https://github.com/f0whb/zugzwang/blob/main/src/core/config.py): `src/core/config.py`
- [Application events](https://github.com/f0whb/zugzwang/blob/main/src/core/events.py): `src/core/events.py`
- [License and trial controls](https://github.com/f0whb/zugzwang/blob/main/src/core/security.py): `src/core/security.py`
- [Diagnostics](https://github.com/f0whb/zugzwang/blob/main/src/diagnostics.py): `src/diagnostics.py`
- [Backup and recovery](https://github.com/f0whb/zugzwang/blob/main/src/services/backup_service.py): `src/services/backup_service.py`

### Other components

- **Candidate or recruiter**
- **German job and business portals**
- **Employer websites**
- **User SMTP account**

## Connections

- Candidate or recruiter → Search workspace: enters search
- Search workspace → Scraping orchestrator: starts searches (evidence: `src/ui/search_page.py`)
- Scraping orchestrator → Portal scrapers: dispatches jobs (evidence: `src/services/orchestrator.py`)
- Scraping orchestrator → Browser automation: manages sessions (evidence: `src/services/orchestrator.py`)
- Portal scrapers → German job and business portals: collect listings
- Portal scrapers → Lead records: produce leads (evidence: `src/services/export_service.py`)
- Scraping orchestrator → Lead import and export: uses import/export (evidence: `src/services/orchestrator.py`)
- Scraping orchestrator → Application events: publishes job events (evidence: `src/core/events.py`)
- Results review → Scraping orchestrator: uses job results (evidence: `src/ui/results_page.py`)
- Results review → Lead import and export: exports results (evidence: `src/ui/results_page.py`)
- Lead editing → Sender and applicant profiles: manages profiles (evidence: `src/ui/edit_page.py`)
- Lead editing → Email extraction: uses extraction (evidence: `src/ui/edit_page.py`)
- Lead editing → Application PDF builder: builds applications (evidence: `src/ui/edit_page.py`)
- Email extraction → Employer websites: finds contacts
- Outreach workspace → Sender and applicant profiles: loads profiles (evidence: `src/ui/email_sender_page.py`)
- Outreach workspace → SMTP mail service: sends paced mail
- SMTP mail service → User SMTP account: authenticates and sends
- Outreach workspace → Scraping orchestrator: records outreach (evidence: `src/services/orchestrator.py`)
- Lead import and export → Local SQLite data: saves project data (evidence: `src/services/export_service.py`)
- Sender and applicant profiles → Local SQLite data: stores profile data (evidence: `src/services/profile_service.py`)
- Search workspace → Local SQLite data: uses search history (evidence: `src/core/config.py`)
- Application window → Search workspace: hosts workspace (evidence: `src/ui/main_window.py`)
- Application window → Results review: hosts results (evidence: `src/ui/main_window.py`)
- Application window → Lead editing: hosts editor (evidence: `src/ui/main_window.py`)
- Application window → Outreach workspace: hosts outreach (evidence: `src/ui/main_window.py`)
- UI event bridge → Application events: subscribes events (evidence: `src/ui/event_bridge.py`)
- License and trial controls → Local SQLite data: persists trial settings (evidence: `src/core/security.py`)
- Diagnostics → Local SQLite data: reads configuration (evidence: `src/diagnostics.py`)
- Backup and recovery → Local SQLite data: backs up settings (evidence: `src/services/backup_service.py`)
- Candidate or recruiter → Outreach workspace: reviews and sends
