# rafatosta/zapzap architecture

> Architecture diagram of the GitHub repository rafatosta/zapzap, 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/rafatosta/zapzap
- Repository: https://github.com/rafatosta/zapzap

## Overview

ZapZap is a Python/PyQt6 desktop wrapper for WhatsApp Web. A user launches the desktop app, which sets up the runtime and opens the browser shell; that shell manages isolated account sessions and embedded WhatsApp Web pages. The app also adds native desktop capabilities including tray controls, notifications, themes, downloads, spell checking, and account-specific customization. The graph preserves these documented feature areas, but unsampled subsystems are represented at their existing directory paths; their internal call wiring is not inferred.

Main entry points: [`zapzap/app/main_window_controller.py`](https://github.com/rafatosta/zapzap/blob/main/zapzap/app/main_window_controller.py) (Main window), [`zapzap/app/application.py`](https://github.com/rafatosta/zapzap/blob/main/zapzap/app/application.py) (Application startup), [`zapzap/features/browser/shell/browser_controller.py`](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/browser/shell/browser_controller.py) (Browser shell), [`zapzap/features/downloads/download_manager.py`](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/downloads/download_manager.py) (Download handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["App lifecycle"]
  node_application["Application startup<br/>[application.py]"]
  node_main_window["Main window"]
  node_runtime_setup["Runtime setup<br/>[setup_manager.py]"]
end

subgraph group_browser["Web and accounts"]
  node_browser_controller["Browser shell"]
  node_web_page["Embedded web page<br/>[web_view.py]"]
  node_account_profiles["Account profiles<br/>[user.py]"]
  node_account_controls["Account management"]
end

subgraph group_native["Desktop integrations"]
  node_tray["System tray"]
  node_notifications["Desktop notifications"]
  node_downloads["Download handling"]
  node_spellcheck["Spell checking"]
  node_donations["Donation page<br/>[page.py]"]
  node_zapzap_features_download_events["Download events<br/>[download_events.py]"]
end

subgraph group_preferences["Settings and customization"]
  node_theme["Theme manager<br/>[theme_manager.py]"]
  node_settings[("Settings store")]
  node_customizations["CSS and JS customization"]
  node_settings_ui["Settings interface"]
end

node_user(("Desktop user"))
node_whatsapp["WhatsApp Web"]

node_user -->|"launches"| node_application
node_application -->|"creates"| node_main_window
node_application -->|"configures"| node_runtime_setup
node_main_window -->|"opens"| node_browser_controller
node_browser_controller -->|"creates"| node_web_page
node_web_page -->|"loads"| node_whatsapp
node_browser_controller -->|"manages"| node_account_profiles
node_account_controls -->|"uses"| node_account_profiles
node_main_window -->|"opens"| node_settings_ui
node_main_window -->|"uses"| node_downloads
node_downloads -->|"emits events"| node_zapzap_features_download_events
node_main_window -->|"uses"| node_theme
node_theme -->|"reads and writes"| node_settings
node_main_window -->|"binds window"| node_tray
node_main_window -->|"opens"| node_donations
node_user -->|"receives"| node_notifications
node_user -->|"uses"| node_spellcheck
node_user -->|"configures"| node_customizations
node_user -->|"controls"| node_tray
node_user -->|"downloads through"| node_downloads
node_settings_ui -->|"configures"| node_customizations

click node_application "https://github.com/rafatosta/zapzap/blob/main/zapzap/app/application.py"
click node_main_window "https://github.com/rafatosta/zapzap/blob/main/zapzap/app/main_window_controller.py"
click node_runtime_setup "https://github.com/rafatosta/zapzap/blob/main/zapzap/core/environment/setup_manager.py"
click node_browser_controller "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/browser/shell/browser_controller.py"
click node_web_page "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/browser/web/web_view.py"
click node_account_profiles "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/accounts/domain/user.py"
click node_account_controls "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/accounts/card_user_controller.py"
click node_tray "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/tray/sys_tray_manager.py"
click node_notifications "https://github.com/rafatosta/zapzap/tree/main/zapzap/features/notifications"
click node_downloads "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/downloads/download_manager.py"
click node_spellcheck "https://github.com/rafatosta/zapzap/tree/main/zapzap/features/dictionaries"
click node_theme "https://github.com/rafatosta/zapzap/blob/main/zapzap/core/theme/theme_manager.py"
click node_settings "https://github.com/rafatosta/zapzap/blob/main/zapzap/core/config/settings_manager.py"
click node_customizations "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/customizations/customizations_manager.py"
click node_settings_ui "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/settings/shell/settings_controller.py"
click node_donations "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/donation/page.py"
click node_zapzap_features_download_events "https://github.com/rafatosta/zapzap/blob/main/zapzap/features/downloads/download_events.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_application,node_main_window,node_runtime_setup,node_user toneBlue
class node_browser_controller,node_web_page,node_account_profiles,node_account_controls toneAmber
class node_tray,node_notifications,node_downloads,node_spellcheck,node_donations,node_zapzap_features_download_events toneMint
class node_theme,node_settings,node_customizations,node_settings_ui toneRose
class node_whatsapp toneIndigo
```

## Components

### App lifecycle

- [Application startup](https://github.com/rafatosta/zapzap/blob/main/zapzap/app/application.py): `zapzap/app/application.py`
- [Main window](https://github.com/rafatosta/zapzap/blob/main/zapzap/app/main_window_controller.py): `zapzap/app/main_window_controller.py`
- [Runtime setup](https://github.com/rafatosta/zapzap/blob/main/zapzap/core/environment/setup_manager.py): `zapzap/core/environment/setup_manager.py`

### Web and accounts

- [Browser shell](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/browser/shell/browser_controller.py): `zapzap/features/browser/shell/browser_controller.py`
- [Embedded web page](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/browser/web/web_view.py): `zapzap/features/browser/web/web_view.py`
- [Account profiles](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/accounts/domain/user.py): `zapzap/features/accounts/domain/user.py`
- [Account management](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/accounts/card_user_controller.py): `zapzap/features/accounts/card_user_controller.py`

### Desktop integrations

- [System tray](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/tray/sys_tray_manager.py): `zapzap/features/tray/sys_tray_manager.py`
- [Desktop notifications](https://github.com/rafatosta/zapzap/tree/main/zapzap/features/notifications): `zapzap/features/notifications`
- [Download handling](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/downloads/download_manager.py): `zapzap/features/downloads/download_manager.py`
- [Spell checking](https://github.com/rafatosta/zapzap/tree/main/zapzap/features/dictionaries): `zapzap/features/dictionaries`
- [Donation page](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/donation/page.py): `zapzap/features/donation/page.py`
- [Download events](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/downloads/download_events.py): `zapzap/features/downloads/download_events.py`

### Settings and customization

- [Theme manager](https://github.com/rafatosta/zapzap/blob/main/zapzap/core/theme/theme_manager.py): `zapzap/core/theme/theme_manager.py`
- [Settings store](https://github.com/rafatosta/zapzap/blob/main/zapzap/core/config/settings_manager.py): `zapzap/core/config/settings_manager.py`
- [CSS and JS customization](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/customizations/customizations_manager.py): `zapzap/features/customizations/customizations_manager.py`
- [Settings interface](https://github.com/rafatosta/zapzap/blob/main/zapzap/features/settings/shell/settings_controller.py): `zapzap/features/settings/shell/settings_controller.py`

### Other components

- **Desktop user**
- **WhatsApp Web**

## Connections

- Desktop user → Application startup: launches (evidence: `README.md`)
- Application startup → Main window: creates (evidence: `zapzap/app/application.py`)
- Application startup → Runtime setup: configures (evidence: `zapzap/app/application.py`)
- Main window → Browser shell: opens (evidence: `zapzap/app/main_window_controller.py`)
- Browser shell → Embedded web page: creates (evidence: `zapzap/features/browser/shell/browser_controller.py`)
- Embedded web page → WhatsApp Web: loads (evidence: `README.md`)
- Browser shell → Account profiles: manages (evidence: `zapzap/features/browser/shell/browser_controller.py`)
- Account management → Account profiles: uses (evidence: `zapzap/features/accounts/card_user_controller.py`)
- Main window → Settings interface: opens (evidence: `zapzap/app/main_window_controller.py`)
- Main window → Download handling: uses (evidence: `zapzap/app/main_window_controller.py`)
- Download handling → Download events: emits events (evidence: `zapzap/features/downloads/download_manager.py`)
- Main window → Theme manager: uses (evidence: `zapzap/app/main_window_controller.py`)
- Theme manager → Settings store: reads and writes (evidence: `zapzap/core/theme/theme_manager.py`)
- Main window → System tray: binds window (evidence: `zapzap/app/main_window_controller.py`)
- Main window → Donation page: opens
- Desktop user → Desktop notifications: receives (evidence: `README.md`)
- Desktop user → Spell checking: uses (evidence: `README.md`)
- Desktop user → CSS and JS customization: configures (evidence: `README.md`)
- Desktop user → System tray: controls (evidence: `README.md`)
- Desktop user → Download handling: downloads through (evidence: `README.md`)
- Settings interface → CSS and JS customization: configures
