# hyacinthe-primus/dynamic-island architecture

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

- Interactive diagram: https://gitdiagram.com/hyacinthe-primus/dynamic-island
- Repository: https://github.com/hyacinthe-primus/dynamic-island

## Overview

Dynamic Island is a Windows 11 desktop shell: a floating pill and application dock expose system controls and productivity tools. The runtime starts through a watchdog, launches the Qt application and island window, then presents tabbed features backed by engines, Windows services, and local JSON storage. The README documents additional feature breadth and optional integrations; where their implementation was not sampled, the graph uses documented relationships rather than asserting unseen calls.

Main entry points: [`src/dynamic_island/ui/windows/island.py`](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/windows/island.py) (Island window), [`src/dynamic_island/app.py`](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/app.py) (Qt application), [`src/dynamic_island/ui/tabs`](https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/ui/tabs) (Feature tabs), [`src/dynamic_island/main.py`](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/main.py) (Runtime entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and UI"]
  node_entry["Runtime entry<br/>[main.py]"]
  node_watchdog["Watchdog<br/>[watchdog.py]"]
  node_application["Qt application<br/>[app.py]"]
  node_island["Island window<br/>[island.py]"]
  node_painting["Island rendering<br/>[painting.py]"]
  node_tabs["Feature tabs"]
  node_tray["Tray controls<br/>[tray.py]"]
end

subgraph group_features["Product Features"]
  node_agenda["Agenda<br/>[agenda.py]"]
  node_tasks["Tasks and notes<br/>[tasks.py]"]
  node_timers["Timers<br/>[timers.py]"]
  node_launcher["App launcher<br/>[launcher.py]"]
  node_files["File shelf<br/>[files.py]"]
  node_clipboard["Clipboard history<br/>[clipboard.py]"]
  node_info_wallet_dev["Info, wallet, developer"]
end

subgraph group_platform["Platform Services"]
  node_connectivity["Network controls<br/>[network.py]"]
  node_hotspot["Hotspot controls<br/>[hotspot.py]"]
  node_phone["Phone service<br/>[phone.py]"]
  node_system["Windows controls<br/>[system.py]"]
end

subgraph group_foundation["Shared Foundations"]
  node_collection[("JSON collections<br/>[collection.py]")]
  node_settings[("Settings<br/>[settings.py]")]
  node_paths["Data paths<br/>[paths.py]"]
  node_localization["Localization"]
  node_nlp["Natural-language parsing<br/>[nlp.py]"]
end

node_user(("Desktop user"))

node_user -->|"starts app"| node_entry
node_entry -->|"starts by default"| node_watchdog
node_entry -->|"runs island mode"| node_application
node_watchdog -.->|"launches app"| node_application
node_application -->|"creates window"| node_island
node_application -->|"creates tray"| node_tray
node_island -->|"renders window"| node_painting
node_island -->|"shows features"| node_tabs
node_island -->|"reads agenda"| node_agenda
node_island -->|"uses tasks"| node_tasks
node_island -->|"uses timers"| node_timers
node_island -->|"uses launcher"| node_launcher
node_island -->|"uses file shelf"| node_files
node_island -->|"uses clipboard"| node_clipboard
node_island -->|"uses feature engines"| node_info_wallet_dev
node_island -->|"uses hotspot"| node_hotspot
node_island -->|"controls taskbar"| node_system
node_agenda -->|"parses entries"| node_nlp
node_tasks -->|"parses tasks"| node_nlp
node_tasks -->|"stores items"| node_collection
node_agenda -->|"stores events"| node_collection
node_collection -->|"reads sync setting"| node_settings
node_collection -->|"resolves data folder"| node_paths
node_application -->|"resolves icon"| node_paths
node_application -->|"sets window style"| node_system
node_entry -.->|"phone integration"| node_phone
node_tabs -.->|"offers network panels"| node_connectivity
node_tabs -.->|"offers phone tools"| node_phone
node_tabs -.->|"offers documented tools"| node_info_wallet_dev
node_tabs -.->|"localized interface"| node_localization

click node_entry "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/main.py"
click node_watchdog "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/application/watchdog.py"
click node_application "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/app.py"
click node_island "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/windows/island.py"
click node_painting "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/components/painting.py"
click node_tabs "https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/ui/tabs"
click node_tray "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/components/tray.py"
click node_agenda "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/agenda.py"
click node_tasks "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/tasks.py"
click node_timers "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/timers.py"
click node_launcher "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/launcher.py"
click node_files "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/files.py"
click node_clipboard "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/clipboard.py"
click node_info_wallet_dev "https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/engines"
click node_connectivity "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/network.py"
click node_hotspot "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/hotspot.py"
click node_phone "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/services/phone.py"
click node_system "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/services/system.py"
click node_collection "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/infrastructure/storage/collection.py"
click node_settings "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/config/settings.py"
click node_paths "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/config/paths.py"
click node_localization "https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/core/localization"
click node_nlp "https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/nlp.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_entry,node_watchdog,node_application,node_island,node_painting,node_tabs,node_tray,node_user toneBlue
class node_agenda,node_tasks,node_timers,node_launcher,node_files,node_clipboard,node_info_wallet_dev toneAmber
class node_connectivity,node_hotspot,node_phone,node_system toneMint
class node_collection,node_settings,node_paths,node_localization,node_nlp toneRose
```

## Components

### Runtime and UI

- [Runtime entry](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/main.py): `src/dynamic_island/main.py`
- [Watchdog](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/application/watchdog.py): `src/dynamic_island/core/application/watchdog.py`
- [Qt application](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/app.py): `src/dynamic_island/app.py`
- [Island window](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/windows/island.py): `src/dynamic_island/ui/windows/island.py`
- [Island rendering](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/components/painting.py): `src/dynamic_island/ui/components/painting.py`
- [Feature tabs](https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/ui/tabs): `src/dynamic_island/ui/tabs`
- [Tray controls](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/ui/components/tray.py): `src/dynamic_island/ui/components/tray.py`

### Product Features

- [Agenda](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/agenda.py): `src/dynamic_island/engines/agenda.py`
- [Tasks and notes](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/tasks.py): `src/dynamic_island/engines/tasks.py`
- [Timers](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/timers.py): `src/dynamic_island/engines/timers.py`
- [App launcher](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/launcher.py): `src/dynamic_island/engines/launcher.py`
- [File shelf](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/files.py): `src/dynamic_island/engines/files.py`
- [Clipboard history](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/clipboard.py): `src/dynamic_island/engines/clipboard.py`
- [Info, wallet, developer](https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/engines): `src/dynamic_island/engines`

### Platform Services

- [Network controls](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/network.py): `src/dynamic_island/engines/network.py`
- [Hotspot controls](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/hotspot.py): `src/dynamic_island/engines/hotspot.py`
- [Phone service](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/services/phone.py): `src/dynamic_island/services/phone.py`
- [Windows controls](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/services/system.py): `src/dynamic_island/services/system.py`

### Shared Foundations

- [JSON collections](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/infrastructure/storage/collection.py): `src/dynamic_island/infrastructure/storage/collection.py`
- [Settings](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/config/settings.py): `src/dynamic_island/core/config/settings.py`
- [Data paths](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/core/config/paths.py): `src/dynamic_island/core/config/paths.py`
- [Localization](https://github.com/hyacinthe-primus/dynamic-island/tree/main/src/dynamic_island/core/localization): `src/dynamic_island/core/localization`
- [Natural-language parsing](https://github.com/hyacinthe-primus/dynamic-island/blob/main/src/dynamic_island/engines/nlp.py): `src/dynamic_island/engines/nlp.py`

### Other components

- **Desktop user**

## Connections

- Desktop user → Runtime entry: starts app (evidence: `README.md`)
- Runtime entry → Watchdog: starts by default (evidence: `src/dynamic_island/main.py`)
- Runtime entry → Qt application: runs island mode (evidence: `src/dynamic_island/main.py`)
- Watchdog → Qt application: launches app
- Qt application → Island window: creates window (evidence: `src/dynamic_island/app.py`)
- Qt application → Tray controls: creates tray (evidence: `src/dynamic_island/app.py`)
- Island window → Island rendering: renders window (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Feature tabs: shows features (evidence: `README.md`)
- Island window → Agenda: reads agenda (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Tasks and notes: uses tasks (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Timers: uses timers (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → App launcher: uses launcher (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → File shelf: uses file shelf (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Clipboard history: uses clipboard (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Info, wallet, developer: uses feature engines (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Hotspot controls: uses hotspot (evidence: `src/dynamic_island/ui/windows/island.py`)
- Island window → Windows controls: controls taskbar (evidence: `src/dynamic_island/ui/windows/island.py`)
- Agenda → Natural-language parsing: parses entries (evidence: `src/dynamic_island/engines/agenda.py`)
- Tasks and notes → Natural-language parsing: parses tasks (evidence: `src/dynamic_island/engines/tasks.py`)
- Tasks and notes → JSON collections: stores items (evidence: `src/dynamic_island/engines/tasks.py`)
- Agenda → JSON collections: stores events (evidence: `src/dynamic_island/engines/agenda.py`)
- JSON collections → Settings: reads sync setting (evidence: `src/dynamic_island/infrastructure/storage/collection.py`)
- JSON collections → Data paths: resolves data folder (evidence: `src/dynamic_island/infrastructure/storage/collection.py`)
- Qt application → Data paths: resolves icon (evidence: `src/dynamic_island/app.py`)
- Qt application → Windows controls: sets window style (evidence: `src/dynamic_island/app.py`)
- Runtime entry → Phone service: phone integration (evidence: `src/dynamic_island/main.py`)
- Feature tabs → Network controls: offers network panels (evidence: `README.md`)
- Feature tabs → Phone service: offers phone tools (evidence: `README.md`)
- Feature tabs → Info, wallet, developer: offers documented tools (evidence: `README.md`)
- Feature tabs → Localization: localized interface (evidence: `README.md`)