klisard/pomodoro_timer

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.