# muhammadsaim/twenty architecture

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

## Overview

TwenTy is a tray-resident desktop reminder: the app loads preferences, starts a timer, and presents synchronized break overlays when work time expires or the user requests a break. Tray and settings controls also pause/resume, skip, tune durations and sound, and configure start-on-login. The graph reflects sampled calls and README-documented capabilities; platform-specific autostart backends are shown as a documented branch, with unsampled implementation details not inferred.

Main entry points: [`src/twenty/app.py`](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/app.py) (App startup), [`src/twenty/ui/engine_controller.py`](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/engine_controller.py) (Qt timer bridge), [`src/twenty/ui/settings_window/settings_dialog.py`](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/settings_window/settings_dialog.py) (Settings window), [`src/twenty/ui/overlay/overlay_manager.py`](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/overlay_manager.py) (Overlay manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_application["App startup<br/>[app.py]"]
end

subgraph group_timing["Break Timing"]
  node_engine["Timer state machine<br/>[engine.py]"]
  node_engine_events["Timer event types<br/>[states.py]"]
  node_engine_controller["Qt timer bridge"]
end

subgraph group_presentation["Desktop UI"]
  node_tray["System tray<br/>[tray.py]"]
  node_overlay_manager["Overlay manager<br/>[overlay_manager.py]"]
  node_overlay_window["Break overlay<br/>[overlay_window.py]"]
  node_countdown["Countdown display"]
  node_settings_dialog["Settings window<br/>[settings_dialog.py]"]
  node_theme["Shared visual theme<br/>[palette.py]"]
end

subgraph group_preferences["Settings"]
  node_settings_controller["Settings controller"]
  node_settings_store[("Settings persistence<br/>[store.py]")]
  node_settings_model["Settings model<br/>[models.py]"]
end

subgraph group_support["Platform Services"]
  node_sound["Break chime<br/>[sound.py]"]
  node_autostart["Autostart interface<br/>[autostart.py]"]
  node_linux_autostart["Linux autostart<br/>[autostart_linux.py]"]
  node_macos_autostart["macOS autostart<br/>[autostart_macos.py]"]
  node_windows_autostart["Windows autostart"]
end

node_user(("Desktop user"))

node_user -->|"uses"| node_tray
node_application -->|"loads settings"| node_settings_store
node_application -->|"starts timer"| node_engine_controller
node_application -->|"creates"| node_overlay_manager
node_application -->|"creates"| node_sound
node_application -->|"creates"| node_tray
node_application -->|"creates"| node_settings_controller
node_engine_controller -->|"drives ticks"| node_engine
node_engine -->|"emits events"| node_engine_events
node_engine_controller -->|"translates events"| node_engine_events
node_tray -->|"controls timer"| node_engine_controller
node_tray -->|"opens"| node_settings_dialog
node_overlay_manager -->|"subscribes to events"| node_engine_controller
node_overlay_manager -->|"creates per-screen"| node_overlay_window
node_overlay_window -->|"displays countdown"| node_countdown
node_overlay_window -->|"requests skip"| node_engine_controller
node_settings_dialog -->|"updates preferences"| node_settings_controller
node_settings_controller -->|"loads and saves"| node_settings_store
node_settings_store -->|"validates settings"| node_settings_model
node_settings_dialog -->|"applies durations"| node_engine_controller
node_sound -->|"plays on break"| node_engine_controller
node_sound -->|"reads live settings"| node_settings_controller
node_settings_dialog -->|"configures login launch"| node_autostart
node_autostart -.->|"selects backend"| node_linux_autostart
node_autostart -.->|"selects backend"| node_macos_autostart
node_autostart -.->|"selects backend"| node_windows_autostart
node_application -->|"configures palette"| node_theme
node_overlay_manager -->|"uses palette"| node_theme
node_settings_dialog -->|"uses palette"| node_theme

click node_application "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/app.py"
click node_engine "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/core/engine.py"
click node_engine_events "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/core/states.py"
click node_engine_controller "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/engine_controller.py"
click node_tray "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/tray.py"
click node_overlay_manager "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/overlay_manager.py"
click node_overlay_window "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/overlay_window.py"
click node_countdown "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/countdown_widget.py"
click node_settings_dialog "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/settings_window/settings_dialog.py"
click node_settings_controller "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/settings_controller.py"
click node_settings_store "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/config/store.py"
click node_settings_model "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/config/models.py"
click node_sound "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/services/sound.py"
click node_autostart "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart.py"
click node_linux_autostart "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_linux.py"
click node_macos_autostart "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_macos.py"
click node_windows_autostart "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_windows.py"
click node_theme "https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/theme/palette.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_user toneBlue
class node_engine,node_engine_events,node_engine_controller toneAmber
class node_tray,node_overlay_manager,node_overlay_window,node_countdown,node_settings_dialog,node_theme toneMint
class node_settings_controller,node_settings_store,node_settings_model toneRose
class node_sound,node_autostart,node_linux_autostart,node_macos_autostart,node_windows_autostart toneIndigo
```

## Components

### Application

- [App startup](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/app.py): `src/twenty/app.py`

### Break Timing

- [Timer state machine](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/core/engine.py): `src/twenty/core/engine.py`
- [Timer event types](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/core/states.py): `src/twenty/core/states.py`
- [Qt timer bridge](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/engine_controller.py): `src/twenty/ui/engine_controller.py`

### Desktop UI

- [System tray](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/tray.py): `src/twenty/ui/tray.py`
- [Overlay manager](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/overlay_manager.py): `src/twenty/ui/overlay/overlay_manager.py`
- [Break overlay](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/overlay_window.py): `src/twenty/ui/overlay/overlay_window.py`
- [Countdown display](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/overlay/countdown_widget.py): `src/twenty/ui/overlay/countdown_widget.py`
- [Settings window](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/settings_window/settings_dialog.py): `src/twenty/ui/settings_window/settings_dialog.py`
- [Shared visual theme](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/theme/palette.py): `src/twenty/ui/theme/palette.py`

### Settings

- [Settings controller](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/ui/settings_controller.py): `src/twenty/ui/settings_controller.py`
- [Settings persistence](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/config/store.py): `src/twenty/config/store.py`
- [Settings model](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/config/models.py): `src/twenty/config/models.py`

### Platform Services

- [Break chime](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/services/sound.py): `src/twenty/services/sound.py`
- [Autostart interface](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart.py): `src/twenty/platform/autostart.py`
- [Linux autostart](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_linux.py): `src/twenty/platform/autostart_linux.py`
- [macOS autostart](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_macos.py): `src/twenty/platform/autostart_macos.py`
- [Windows autostart](https://github.com/muhammadsaim/twenty/blob/main/src/twenty/platform/autostart_windows.py): `src/twenty/platform/autostart_windows.py`

### Other components

- **Desktop user**

## Connections

- Desktop user → System tray: uses (evidence: `README.md`)
- App startup → Settings persistence: loads settings (evidence: `src/twenty/app.py`)
- App startup → Qt timer bridge: starts timer (evidence: `src/twenty/app.py`)
- App startup → Overlay manager: creates (evidence: `src/twenty/app.py`)
- App startup → Break chime: creates (evidence: `src/twenty/app.py`)
- App startup → System tray: creates (evidence: `src/twenty/app.py`)
- App startup → Settings controller: creates (evidence: `src/twenty/app.py`)
- Qt timer bridge → Timer state machine: drives ticks (evidence: `src/twenty/ui/engine_controller.py`)
- Timer state machine → Timer event types: emits events (evidence: `src/twenty/core/engine.py`)
- Qt timer bridge → Timer event types: translates events (evidence: `src/twenty/ui/engine_controller.py`)
- System tray → Qt timer bridge: controls timer (evidence: `src/twenty/ui/tray.py`)
- System tray → Settings window: opens (evidence: `src/twenty/ui/tray.py`)
- Overlay manager → Qt timer bridge: subscribes to events (evidence: `src/twenty/ui/overlay/overlay_manager.py`)
- Overlay manager → Break overlay: creates per-screen (evidence: `src/twenty/ui/overlay/overlay_manager.py`)
- Break overlay → Countdown display: displays countdown (evidence: `src/twenty/ui/overlay/overlay_window.py`)
- Break overlay → Qt timer bridge: requests skip (evidence: `src/twenty/ui/overlay/overlay_manager.py`)
- Settings window → Settings controller: updates preferences (evidence: `src/twenty/ui/settings_window/settings_dialog.py`)
- Settings controller → Settings persistence: loads and saves (evidence: `src/twenty/ui/settings_controller.py`)
- Settings persistence → Settings model: validates settings (evidence: `src/twenty/config/store.py`)
- Settings window → Qt timer bridge: applies durations (evidence: `src/twenty/ui/settings_window/settings_dialog.py`)
- Break chime → Qt timer bridge: plays on break (evidence: `src/twenty/services/sound.py`)
- Break chime → Settings controller: reads live settings (evidence: `src/twenty/services/sound.py`)
- Settings window → Autostart interface: configures login launch (evidence: `src/twenty/ui/settings_window/settings_dialog.py`)
- Autostart interface → Linux autostart: selects backend (evidence: `README.md`)
- Autostart interface → macOS autostart: selects backend (evidence: `README.md`)
- Autostart interface → Windows autostart: selects backend (evidence: `README.md`)
- App startup → Shared visual theme: configures palette (evidence: `src/twenty/app.py`)
- Overlay manager → Shared visual theme: uses palette (evidence: `src/twenty/ui/overlay/overlay_manager.py`)
- Settings window → Shared visual theme: uses palette (evidence: `src/twenty/ui/settings_window/settings_dialog.py`)
