# ebullioscopic/atoll architecture

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

- Interactive diagram: https://gitdiagram.com/ebullioscopic/atoll
- Repository: https://github.com/ebullioscopic/atoll

## Overview

Atoll is a macOS notch-based command surface. Users open the notch, choose a surface such as Media, Stats, or Timers, and interact with native controls backed by media controllers, system monitors, and utility managers. It also presents Live Activities and configurable lock-screen widgets. The README documents these major capabilities; sampled excerpts show details of media control, usage refresh, temporary-file handling, sharing lifecycle, and screen-capture visibility, but do not establish every runtime connection, so uncertain wiring is omitted.

Main entry points: [`DynamicIsland/managers/MusicManager.swift`](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/MusicManager.swift) (Music manager), [`DynamicIsland/DynamicIslandApp.swift`](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/DynamicIslandApp.swift) (App lifecycle), [`DynamicIsland/components/Notch/NotchHomeView.swift`](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Notch/NotchHomeView.swift) (Notch surfaces), [`DynamicIsland/MediaControllers/SpotifyController.swift`](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/SpotifyController.swift) (Spotify controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Surface"]
  node_app["App lifecycle"]
  node_coordinator["Island coordinator"]
  node_notch["Notch surfaces"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_capturevisibility["Capture visibility"]
end

subgraph group_media["Media"]
  node_musicmanager["Music manager<br/>[MusicManager.swift]"]
  node_mediaprotocol["Controller protocol"]
  node_spotify["Spotify controller"]
  node_youtube["YouTube Music"]
  node_mediaui["Music controls"]
end

subgraph group_system["System Insight"]
  node_statsmanager["Stats manager<br/>[StatsManager.swift]"]
  node_statsui["System metrics UI"]
  node_audio["Audio visualization"]
  node_systemhud["System HUDs"]
end

subgraph group_utilities["Utilities"]
  node_timer["Timer service<br/>[TimerManager.swift]"]
  node_clipboard["Clipboard tools"]
  node_calendar["Calendar service"]
  node_shelf["File Shelf<br/>[ShelfView.swift]"]
  node_usage["LLM usage"]
end

subgraph group_lockext["Lock Screen &amp; Extensions"]
  node_lockmanager["Lock-screen manager"]
  node_lockwidgets["Lock-screen widgets"]
  node_extensionrpc["Extension RPC"]
  node_extensionwidgets["Extension widgets"]
end

node_user(("Mac user"))
node_spotifyapp["Spotify app"]
node_youtubeapp["YouTube Music app"]
node_macos["macOS services"]

node_user -->|"launches"| node_app
node_app -->|"starts"| node_coordinator
node_user -->|"opens"| node_notch
node_notch -->|"shows media"| node_mediaui
node_mediaui -->|"requests playback"| node_musicmanager
node_musicmanager -->|"uses"| node_mediaprotocol
node_musicmanager -->|"selects"| node_spotify
node_musicmanager -->|"selects"| node_youtube
node_spotify -->|"controls and reads"| node_spotifyapp
node_youtube -->|"controls and reads"| node_youtubeapp
node_user -->|"opens metrics"| node_statsui
node_statsui -->|"displays metrics"| node_statsmanager
node_user -->|"views spectrum"| node_audio
node_user -->|"triggers HUD"| node_systemhud
node_user -->|"sets timer"| node_timer
node_user -->|"uses clipboard"| node_clipboard
node_user -->|"views calendar"| node_calendar
node_user -->|"drops files"| node_shelf
node_user -->|"checks usage"| node_usage
node_user -->|"customizes"| node_settings
node_user -->|"views widgets"| node_lockwidgets
node_lockmanager -->|"presents"| node_lockwidgets
node_extensionrpc -->|"delivers payloads"| node_extensionwidgets
node_extensionwidgets -->|"creates windows"| node_macos
node_capturevisibility -->|"sets capture visibility"| node_macos

click node_app "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/DynamicIslandApp.swift"
click node_coordinator "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/DynamicIslandViewCoordinator.swift"
click node_notch "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Notch/NotchHomeView.swift"
click node_settings "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Settings/SettingsView.swift"
click node_musicmanager "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/MusicManager.swift"
click node_mediaprotocol "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/MediaControllerProtocol.swift"
click node_spotify "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/SpotifyController.swift"
click node_youtube "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/YouTube%20Music%20Controller/YouTubeMusicController.swift"
click node_mediaui "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Notch/MinimalisticMusicPlayerView.swift"
click node_statsmanager "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/StatsManager.swift"
click node_statsui "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Stats/CPUStatsDetailView.swift"
click node_audio "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/audio/AudioVisualizerView.swift"
click node_systemhud "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/SystemHUDManager.swift"
click node_timer "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/TimerManager.swift"
click node_clipboard "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/ClipboardManager.swift"
click node_calendar "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/CalendarManager.swift"
click node_shelf "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Shelf/Views/ShelfView.swift"
click node_usage "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/LLMUsage/LLMUsageManager.swift"
click node_lockmanager "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/LockScreenManager.swift"
click node_lockwidgets "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/LockScreen/LockScreenLiveActivity.swift"
click node_extensionrpc "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/services/Extensions/ExtensionRPCService.swift"
click node_extensionwidgets "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/Extensions/ExtensionLockScreenWidgetPresentationController.swift"
click node_capturevisibility "https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/helpers/ScreenCaptureVisibilityManager.swift"

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_app,node_coordinator,node_notch,node_settings,node_capturevisibility,node_user toneBlue
class node_musicmanager,node_mediaprotocol,node_spotify,node_youtube,node_mediaui toneAmber
class node_statsmanager,node_statsui,node_audio,node_systemhud toneMint
class node_timer,node_clipboard,node_calendar,node_shelf,node_usage toneRose
class node_lockmanager,node_lockwidgets,node_extensionrpc,node_extensionwidgets,node_spotifyapp,node_youtubeapp,node_macos toneIndigo
```

## Components

### App Surface

- [App lifecycle](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/DynamicIslandApp.swift): `DynamicIsland/DynamicIslandApp.swift`
- [Island coordinator](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/DynamicIslandViewCoordinator.swift): `DynamicIsland/DynamicIslandViewCoordinator.swift`
- [Notch surfaces](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Notch/NotchHomeView.swift): `DynamicIsland/components/Notch/NotchHomeView.swift`
- [Settings](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Settings/SettingsView.swift): `DynamicIsland/components/Settings/SettingsView.swift`
- [Capture visibility](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/helpers/ScreenCaptureVisibilityManager.swift): `DynamicIsland/helpers/ScreenCaptureVisibilityManager.swift`

### Media

- [Music manager](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/MusicManager.swift): `DynamicIsland/managers/MusicManager.swift`
- [Controller protocol](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/MediaControllerProtocol.swift): `DynamicIsland/MediaControllers/MediaControllerProtocol.swift`
- [Spotify controller](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/SpotifyController.swift): `DynamicIsland/MediaControllers/SpotifyController.swift`
- [YouTube Music](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/MediaControllers/YouTube%20Music%20Controller/YouTubeMusicController.swift): `DynamicIsland/MediaControllers/YouTube Music Controller/YouTubeMusicController.swift`
- [Music controls](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Notch/MinimalisticMusicPlayerView.swift): `DynamicIsland/components/Notch/MinimalisticMusicPlayerView.swift`

### System Insight

- [Stats manager](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/StatsManager.swift): `DynamicIsland/managers/StatsManager.swift`
- [System metrics UI](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Stats/CPUStatsDetailView.swift): `DynamicIsland/components/Stats/CPUStatsDetailView.swift`
- [Audio visualization](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/audio/AudioVisualizerView.swift): `DynamicIsland/audio/AudioVisualizerView.swift`
- [System HUDs](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/SystemHUDManager.swift): `DynamicIsland/managers/SystemHUDManager.swift`

### Utilities

- [Timer service](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/TimerManager.swift): `DynamicIsland/managers/TimerManager.swift`
- [Clipboard tools](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/ClipboardManager.swift): `DynamicIsland/managers/ClipboardManager.swift`
- [Calendar service](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/CalendarManager.swift): `DynamicIsland/managers/CalendarManager.swift`
- [File Shelf](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/Shelf/Views/ShelfView.swift): `DynamicIsland/components/Shelf/Views/ShelfView.swift`
- [LLM usage](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/LLMUsage/LLMUsageManager.swift): `DynamicIsland/managers/LLMUsage/LLMUsageManager.swift`

### Lock Screen & Extensions

- [Lock-screen manager](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/LockScreenManager.swift): `DynamicIsland/managers/LockScreenManager.swift`
- [Lock-screen widgets](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/components/LockScreen/LockScreenLiveActivity.swift): `DynamicIsland/components/LockScreen/LockScreenLiveActivity.swift`
- [Extension RPC](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/services/Extensions/ExtensionRPCService.swift): `DynamicIsland/services/Extensions/ExtensionRPCService.swift`
- [Extension widgets](https://github.com/ebullioscopic/atoll/blob/dev/DynamicIsland/managers/Extensions/ExtensionLockScreenWidgetPresentationController.swift): `DynamicIsland/managers/Extensions/ExtensionLockScreenWidgetPresentationController.swift`

### Other components

- **Mac user**
- **Spotify app**
- **YouTube Music app**
- **macOS services**

## Connections

- Mac user → App lifecycle: launches
- App lifecycle → Island coordinator: starts
- Mac user → Notch surfaces: opens
- Notch surfaces → Music controls: shows media
- Music controls → Music manager: requests playback
- Music manager → Controller protocol: uses
- Music manager → Spotify controller: selects
- Music manager → YouTube Music: selects
- Spotify controller → Spotify app: controls and reads
- YouTube Music → YouTube Music app: controls and reads
- Mac user → System metrics UI: opens metrics
- System metrics UI → Stats manager: displays metrics
- Mac user → Audio visualization: views spectrum
- Mac user → System HUDs: triggers HUD
- Mac user → Timer service: sets timer
- Mac user → Clipboard tools: uses clipboard
- Mac user → Calendar service: views calendar
- Mac user → File Shelf: drops files
- Mac user → LLM usage: checks usage
- Mac user → Settings: customizes
- Mac user → Lock-screen widgets: views widgets
- Lock-screen manager → Lock-screen widgets: presents
- Extension RPC → Extension widgets: delivers payloads
- Extension widgets → macOS services: creates windows
- Capture visibility → macOS services: sets capture visibility