# klisard/pomodoro_timer architecture

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

- Interactive diagram: https://gitdiagram.com/klisard/pomodoro_timer
- Repository: https://github.com/klisard/pomodoro_timer

## Overview

1. This repository is a cross-platform Flutter app centered on a Pomodoro timer. The shared application logic lives in `lib/`, while platform shells exist for Android, iOS, macOS, Windows, Linux, and Web.

2. The core UI is a small screen set in `lib/screens/`: `home_screen.dart` for the timer itself, `history_screen.dart` for past sessions, and `settings_screen.dart` for configuration. These screens are the top of the app’s dependency chain and should be drawn as the presentation layer.

3. State is organized with providers in `lib/providers/`: `timer_provider.dart`, `settings_provider.dart`, and `history_provider.dart`. They act as the app’s coordination layer, exposing timer state, user preferences, and session history to the screens.

4. The app’s data model is minimal and local-first. `lib/models/app_settings.dart` and `lib/models/session_record.dart` define the persisted configuration and the session history entries that flow through the providers and storage layer.

5. Persistent storage is handled by `lib/services/storage_service.dart`. This is the app’s long-term data boundary: settings and session records are stored locally and reloaded into the providers at startup or when the app resumes.

6. Timer behavior is split out from the UI into `lib/services/background_timer_service.dart`. This suggests the countdown continues independently of the visible screen lifecycle, and the timer provider delegates timing work to this service rather than owning it directly.

7. User feedback services are separated by concern: `lib/services/notification_service.dart` handles user notifications, `lib/services/audio_service.dart` handles sound cues, and `lib/services/now_bar_service.dart` manages a live “now bar”/ongoing-timer style display. These services are invoked from the timer flow when state changes or milestones are reached.

8. Android has the most explicit native integration. `android/app/src/main/kotlin/com/example/pomodoro_timer/TimerDisplayService.kt` and `NowBarManager.kt` indicate a platform-specific mechanism for persistent timer display and notification UI on Android, supported by custom notification layouts in `android/app/src/main/res/layout/`.

9. The native layer is otherwise thin. iOS, macOS, Windows, Linux, and Web are standard Flutter host projects with generated or minimal runner code, so the shared Dart code remains the main application architecture across platforms.

10. The likely runtime flow is: UI screen action -> provider state change -> service invocation -> storage/notification/audio/native display updates. That makes the important architectural boundaries: Flutter UI, app state providers, local persistence, background/timing services, and Android-only native presentation.

11. There are no obvious backend APIs or cloud dependencies in this repo. The architecture appears fully on-device, with local state and platform notifications as the primary integrations.

12. The `graphify-out/` directory is an analysis artifact, not part of the product runtime. It can be ignored in a system diagram.

Main entry points: [`lib/providers/timer_provider.dart`](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/timer_provider.dart) (Timer state), [`lib/screens/home_screen.dart`](https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/home_screen.dart) (Home), [`lib/providers/settings_provider.dart`](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/settings_provider.dart) (Settings state), [`lib/providers/history_provider.dart`](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/history_provider.dart) (History state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared Flutter App"]
  node_main["App entry<br/>bootstrap<br/>[main.dart]"]
  node_home_screen["Home<br/>screen<br/>[home_screen.dart]"]
  node_history_screen["History<br/>screen"]
  node_settings_screen["Settings<br/>screen"]
  node_timer_provider(("Timer state<br/>provider"))
  node_settings_provider(("Settings state<br/>provider"))
  node_history_provider(("History state<br/>provider"))
  node_app_settings["App settings<br/>model<br/>[app_settings.dart]"]
  node_session_record["Session record<br/>model"]
  node_storage_service[("Storage<br/>persistence")]
  node_background_timer_service{{"Background timer<br/>timer service"}}
  node_notification_service{{"Notifications"}}
  node_audio_service{{"Audio cues<br/>[audio_service.dart]"}}
  node_now_bar_service{{"Now bar"}}
end

subgraph group_android["Android Native"]
  node_main_activity["MainActivity<br/>android host<br/>[MainActivity.kt]"]
  node_timer_display_service{{"Timer display<br/>android service"}}
  node_now_bar_manager{{"Now bar mgr<br/>android coordinator<br/>[NowBarManager.kt]"}}
end

subgraph group_hosts["Platform Shells"]
  node_platform_hosts["Other hosts<br/>flutter hosts"]
end

node_main -->|"launches"| node_home_screen
node_home_screen -->|"reads/writes"| node_timer_provider
node_home_screen -->|"reads"| node_history_provider
node_home_screen -->|"reads"| node_settings_provider
node_history_screen -->|"reads"| node_history_provider
node_settings_screen -->|"reads/writes"| node_settings_provider
node_timer_provider -->|"delegates"| node_background_timer_service
node_timer_provider -->|"persists"| node_storage_service
node_timer_provider -->|"alerts"| node_notification_service
node_timer_provider -->|"sounds"| node_audio_service
node_timer_provider -->|"updates"| node_now_bar_service
node_settings_provider -->|"uses"| node_app_settings
node_settings_provider -->|"loads/saves"| node_storage_service
node_history_provider -->|"uses"| node_session_record
node_history_provider -->|"loads/saves"| node_storage_service
node_background_timer_service -.->|"syncs"| node_storage_service
node_now_bar_service -.->|"bridges"| node_now_bar_manager
node_notification_service -.->|"integrates"| node_timer_display_service
node_platform_hosts -.->|"hosts"| node_main_activity

click node_main "https://github.com/klisard/pomodoro_timer/blob/master/lib/main.dart"
click node_home_screen "https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/home_screen.dart"
click node_history_screen "https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/history_screen.dart"
click node_settings_screen "https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/settings_screen.dart"
click node_timer_provider "https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/timer_provider.dart"
click node_settings_provider "https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/settings_provider.dart"
click node_history_provider "https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/history_provider.dart"
click node_app_settings "https://github.com/klisard/pomodoro_timer/blob/master/lib/models/app_settings.dart"
click node_session_record "https://github.com/klisard/pomodoro_timer/blob/master/lib/models/session_record.dart"
click node_storage_service "https://github.com/klisard/pomodoro_timer/blob/master/lib/services/storage_service.dart"
click node_background_timer_service "https://github.com/klisard/pomodoro_timer/blob/master/lib/services/background_timer_service.dart"
click node_notification_service "https://github.com/klisard/pomodoro_timer/blob/master/lib/services/notification_service.dart"
click node_audio_service "https://github.com/klisard/pomodoro_timer/blob/master/lib/services/audio_service.dart"
click node_now_bar_service "https://github.com/klisard/pomodoro_timer/blob/master/lib/services/now_bar_service.dart"
click node_main_activity "https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/MainActivity.kt"
click node_timer_display_service "https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/TimerDisplayService.kt"
click node_now_bar_manager "https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/NowBarManager.kt"

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_main,node_home_screen,node_history_screen,node_settings_screen,node_timer_provider,node_settings_provider,node_history_provider,node_app_settings,node_session_record,node_storage_service,node_background_timer_service,node_notification_service,node_audio_service,node_now_bar_service toneBlue
class node_main_activity,node_timer_display_service,node_now_bar_manager toneAmber
class node_platform_hosts toneMint
```

## Components

### Shared Flutter App

Cross-platform Dart application logic and UI.

- [App entry](https://github.com/klisard/pomodoro_timer/blob/master/lib/main.dart): bootstrap · Initializes the Flutter app and wires the root widget tree. · `lib/main.dart`
- [Home](https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/home_screen.dart): screen · Primary Pomodoro timer screen. · `lib/screens/home_screen.dart`
- [History](https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/history_screen.dart): screen · Shows past session records. · `lib/screens/history_screen.dart`
- [Settings](https://github.com/klisard/pomodoro_timer/blob/master/lib/screens/settings_screen.dart): screen · Controls app and timer configuration. · `lib/screens/settings_screen.dart`
- [Timer state](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/timer_provider.dart): provider · Coordinates countdown state and timer lifecycle. · `lib/providers/timer_provider.dart`
- [Settings state](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/settings_provider.dart): provider · Exposes persisted user preferences to the UI. · `lib/providers/settings_provider.dart`
- [History state](https://github.com/klisard/pomodoro_timer/blob/master/lib/providers/history_provider.dart): provider · Manages session history read/write flow. · `lib/providers/history_provider.dart`
- [App settings](https://github.com/klisard/pomodoro_timer/blob/master/lib/models/app_settings.dart): model · Persisted configuration model. · `lib/models/app_settings.dart`
- [Session record](https://github.com/klisard/pomodoro_timer/blob/master/lib/models/session_record.dart): model · Single completed Pomodoro session entry. · `lib/models/session_record.dart`
- [Storage](https://github.com/klisard/pomodoro_timer/blob/master/lib/services/storage_service.dart): persistence · Local long-term storage for settings and session data. · `lib/services/storage_service.dart`
- [Background timer](https://github.com/klisard/pomodoro_timer/blob/master/lib/services/background_timer_service.dart): timer service · Runs countdown behavior outside the visible screen lifecycle. · `lib/services/background_timer_service.dart`
- [Notifications](https://github.com/klisard/pomodoro_timer/blob/master/lib/services/notification_service.dart): service · Emits user-facing alerts when timer milestones occur. · `lib/services/notification_service.dart`
- [Audio cues](https://github.com/klisard/pomodoro_timer/blob/master/lib/services/audio_service.dart): service · Plays sound feedback for timer events. · `lib/services/audio_service.dart`
- [Now bar](https://github.com/klisard/pomodoro_timer/blob/master/lib/services/now_bar_service.dart): service · Maintains live ongoing-timer display behavior. · `lib/services/now_bar_service.dart`

### Android Native

Platform-specific timer and notification integration.

- [MainActivity](https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/MainActivity.kt): android host · Android Flutter entry activity. · `android/app/src/main/kotlin/com/example/pomodoro_timer/MainActivity.kt`
- [Timer display](https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/TimerDisplayService.kt): android service · Native Android persistent timer and notification service. · `android/app/src/main/kotlin/com/example/pomodoro_timer/TimerDisplayService.kt`
- [Now bar mgr](https://github.com/klisard/pomodoro_timer/blob/master/android/app/src/main/kotlin/com/example/pomodoro_timer/NowBarManager.kt): android coordinator · Builds and updates Android now-bar and notification presentation. · `android/app/src/main/kotlin/com/example/pomodoro_timer/NowBarManager.kt`

### Platform Shells

Thin Flutter host projects for desktop, mobile, and web.

- **Other hosts**: flutter hosts · Standard iOS, macOS, Linux, Windows, and Web shell projects.

## Connections

- App entry → Home: launches · Bootstraps the UI around the main timer screen.
- Home → Timer state: reads/writes · Timer screen drives and observes timer state.
- Home → History state: reads · Home may surface recent session context.
- Home → Settings state: reads · Uses settings for timer behavior and display.
- History → History state: reads · History screen consumes session history.
- Settings → Settings state: reads/writes · Settings screen edits persisted preferences.
- Timer state → Background timer: delegates · Provider offloads countdown execution.
- Timer state → Storage: persists · Timer state changes may update local storage.
- Timer state → Notifications: alerts · Triggers notifications on timer events.
- Timer state → Audio cues: sounds · Plays cues when phases change.
- Timer state → Now bar: updates · Keeps the live now-bar presentation in sync.
- Settings state → App settings: uses · Maps provider state to persisted settings model.
- Settings state → Storage: loads/saves · Reads and writes app settings locally.
- History state → Session record: uses · History provider manages session entries.
- History state → Storage: loads/saves · Persists session history locally.
- Background timer → Storage: syncs · Can reload or checkpoint timer-related state.
- Now bar → Now bar mgr: bridges · Shared now-bar logic connects to Android implementation.
- Notifications → Timer display: integrates · Timer flow can route into Android foreground/display service.
- Other hosts → MainActivity: hosts · Represents the thin native shells around the shared app.