# hosikiti/pomowor architecture

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

- Interactive diagram: https://gitdiagram.com/hosikiti/pomowor
- Repository: https://github.com/hosikiti/pomowor

## Overview

##### Project Type and Purpose
- Type: Cross-platform mobile application built with Flutter/Dart.
- Purpose: A Pomodoro-style work-timer that tracks elapsed time, shows progress, and sends local notifications.

##### File Structure
- Top-level platform folders:
– android/ (native Android project)
– ios/ (native iOS project)
– web/ (Web deployment assets)
- Core application code under lib/:
– lib/common/ : shared widgets, styles, providers, utilities
– lib/feature/timer/ : feature module containing UI pages, widgets, state providers, and domain types
– lib/main.dart : application entry point
- Assets: asset/alarm.mp3
- Configuration: pubspec.yaml (dependencies), build.yaml, Codemagic CI config

##### README.md
- Confirms it’s a simple work-timer app (Pomodoro technique).
- Mentions TODOs: persist state on crash, volume setting, crash fixes.
- Build badge indicates CI/CD via Codemagic.

##### Main Components
a. Client Platforms
– Android (APK)
– iOS (IPA) scaffolding
– Web (static assets)
b. Flutter Layer
– Flutter Engine (Dart VM + Skia)
– Flutter Framework (widgets, rendering)
c. Application Code
– UI Layer
- Feature-based screens (TimerPage, TimerCircle, TimerLabel)
– State Management Layer
- Provider instances for TimerState, Progress, TestMode, AppForegroundState
- Freezed-generated state classes
– Services / Data Layer
- Storage (shared_preferences via local_storage module)
- LocalNotifications (flutter_local_notifications plugin wrappers)
– Common Module
- Theme, Styling, Dialog utilities, CircleButton widget
d. Native Platform Services
– Android/iOS Local Notification APIs
– File/Shared Preferences storage
– App lifecycle callbacks
e. CI/CD Pipeline (external)
– Codemagic build & deploy

##### Relationships & Data Flow
- User taps UI → UI component (e.g., CircleButton) → calls TimerProvider
- TimerProvider changes state → notifies listeners → UI rebuilds TimerCircle & TimerLabel
- On timer completion or interval → LocalNotification service API → Native Notification
- Providers persist state via Storage service → Shared Preferences → file system
- AppForegroundState monitors lifecycle → pause/resume timer as app goes background/foreground

##### Architectural Patterns & Design Principles
- Feature-based modularization: “common” vs “feature/timer”
- Unidirectional data flow via Provider → notifyListeners() → UI rebuild
- Separation of concerns: UI widgets vs business logic vs data access
- Dependency injection via Provider tree in main.dart
- Freezed for immutable state representations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD
    CI["Codemagic CI/CD"]:::cicd

    %% User
    User["User"]:::user

    %% Platform Layer
    subgraph "Platform Layer"
        AndroidPlat["Android Platform"]:::platform
        iOSPlat["iOS Platform"]:::platform
        WebPlat["Web Platform"]:::platform
    end

    %% Flutter Layer
    subgraph "Flutter Layer"
        Engine["Flutter Engine<br/>(Dart VM + Skia)"]:::core
        Framework["Flutter Framework"]:::core
    end

    %% Application Code
    subgraph "Application Code"
        Main["Application Entry Point<br/>(main.dart)"]:::common
        subgraph "UI Layer"
            TimerPage["TimerPage Screen"]:::ui
            TimerCircle["TimerCircle Widget"]:::ui
            TimerLabel["TimerLabel Widget"]:::ui
        end
        subgraph "State Management"
            TimerProv["TimerProvider"]:::provider
            ProgressProv["TimerProgressProvider"]:::provider
            TimerState["TimerState<br/>(Freezed)"]:::provider
            TestModeProv["TestModeProvider"]:::provider
            TestModeState["TestModeState<br/>(Freezed)"]:::provider
            AppFgProv["AppForegroundStateProvider"]:::provider
        end
        subgraph "Services"
            StorageProv["Storage Provider"]:::service
            NotifProv["LocalNotification Provider"]:::service
        end
        subgraph "Common Module"
            Theme["Theme Definitions"]:::common
            Dialogs["Dialog Utilities"]:::common
            CircleBtn["CircleButton Widget"]:::common
        end
    end

    %% External Native Services
    subgraph "Native Services"
        SharedPrefs["Shared Preferences"]:::external
        NativeNotif["Native Notification API"]:::external
        AlarmAsset["Alarm Sound (asset)"]:::external
    end

    %% Relationships
    CI -->|build| AndroidPlat
    CI -->|build| iOSPlat
    CI -->|assets| WebPlat

    User --> AndroidPlat
    User --> iOSPlat
    User --> WebPlat

    AndroidPlat --> Engine
    iOSPlat --> Engine
    WebPlat --> Engine

    Engine --> Framework
    Framework --> Main

    Main --> TimerPage
    Main --> TimerProv
    Main --> ProgressProv
    Main --> TestModeProv
    Main --> AppFgProv

    TimerPage -->|uses| TimerCircle
    TimerPage -->|uses| TimerLabel
    TimerPage -->|listens to| TimerProv

    TimerCircle -->|listens to| TimerProv
    TimerLabel -->|listens to| TimerProv

    TimerProv -->|updates state| TimerState
    TestModeProv -->|updates state| TestModeState
    ProgressProv -->|updates state| TimerState
    AppFgProv -->|monitors| AndroidPlat
    AppFgProv -->|monitors| iOSPlat

    TimerProv -->|persists via| StorageProv
    ProgressProv -->|persists via| StorageProv
    NotifProv -->|triggers| NativeNotif
    TimerProv -->|sends notification via| NotifProv

    StorageProv --> SharedPrefs
    NotifProv --> AlarmAsset

    %% Click Events
    click AndroidPlat "https://github.com/hosikiti/pomowor/tree/main/android/"
    click iOSPlat "https://github.com/hosikiti/pomowor/tree/main/ios/"
    click WebPlat "https://github.com/hosikiti/pomowor/tree/main/web/"
    click Main "https://github.com/hosikiti/pomowor/blob/main/lib/main.dart"
    click TimerPage "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/timer_page.dart"
    click TimerCircle "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/widget/timer_circle.dart"
    click TimerLabel "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/widget/timer_label.dart"
    click TimerProv "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/timer.dart"
    click ProgressProv "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/timer_progress.dart"
    click TimerState "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/timer_state.dart"
    click TimerState "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/timer_state.freezed.dart"
    click TestModeProv "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/test_mode.dart"
    click TestModeState "https://github.com/hosikiti/pomowor/blob/main/lib/feature/timer/provider/test_mode_state.freezed.dart"
    click AppFgProv "https://github.com/hosikiti/pomowor/blob/main/lib/common/provider/app_foreground_state.dart"
    click StorageProv "https://github.com/hosikiti/pomowor/blob/main/lib/common/provider/storage.dart"
    click NotifProv "https://github.com/hosikiti/pomowor/blob/main/lib/common/provider/local_notification.dart"
    click Theme "https://github.com/hosikiti/pomowor/blob/main/lib/common/style/theme.dart"
    click Dialogs "https://github.com/hosikiti/pomowor/blob/main/lib/common/util/dialogs.dart"
    click CircleBtn "https://github.com/hosikiti/pomowor/blob/main/lib/common/widget/circle_button.dart"
    click AlarmAsset "https://github.com/hosikiti/pomowor/blob/main/asset/alarm.mp3"
    click CI "https://github.com/hosikiti/pomowor/blob/main/codemagic.yaml"
    click Pubspec "https://github.com/hosikiti/pomowor/blob/main/pubspec.yaml"

    %% Styles
    classDef platform fill:#D6EAF8,stroke:#3498DB,color:#1F618D
    classDef core fill:#D5F5E3,stroke:#27AE60,color:#196F3D
    classDef ui fill:#FCF3CF,stroke:#F1C40F,color:#B9770E
    classDef provider fill:#FADBD8,stroke:#E74C3C,color:#922B21
    classDef service fill:#D2B4DE,stroke:#8E44AD,color:#512E5F
    classDef common fill:#FDEBD0,stroke:#DC7633,color:#7E5109
    classDef external fill:#E5E7E9,stroke:#95A5A6,color:#566573
    classDef cicd fill:#F9E79F,stroke:#F4D03F,color:#B7950B
    classDef user fill:#D6DBDF,stroke:#7B7D7D,color:#2C3E50
```
