# adhilkrishnag/focusflow architecture

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

- Interactive diagram: https://gitdiagram.com/adhilkrishnag/focusflow
- Repository: https://github.com/adhilkrishnag/focusflow

## Overview

**FocusFlow** is a **Flutter cross-platform client application** (Android/iOS/Web/Desktop) that provides:
- Task CRUD + categorization + priority
- **Pomodoro timer**
- **Stats dashboard**
- **Theming (light/dark)**
- **Local notifications**
- **Local persistent storage using Hive** (works on mobile + web)

There is **no backend service** in this repo. Architecturally it’s a **single deployable client** with clean internal layering: **UI → State (Riverpod) → Repository → Local DB (Hive) + platform services (notifications)**.

- The **app’s internal layers and data flow**
- The **platform boundary** (Flutter/Dart vs native host)
- **External dependencies** (Hive storage engine, local notifications plugin, OS notification scheduler)
- **Cross-platform build targets** (Android/iOS/Web/Windows/macOS/Linux) as deployment nodes

From the tree + README, the meaningful architecture lives under `lib/`:

- `lib/main.dart`
App entrypoint: app bootstrap, provider scope, routing to screens, initialization (likely Hive + notifications setup).

- `lib/models/task.dart`, `lib/models/task.g.dart`

- `lib/repositories/task_repository.dart`

- `lib/providers/*`
Riverpod providers for tasks, theme, timer. This is the **State Management / Application Layer**.
- `task_providers.dart` (task list state, CRUD orchestration)
- `timer_provider.dart` (Pomodoro state machine/ticks)
- `theme_provider.dart` (theme mode state)

- `lib/services/notifications.dart`

- `lib/screens/*` + `lib/widgets/*`
Presentation layer: pages and reusable widgets.
- Screens: `home_screen.dart`, `add_task_screen.dart`, `stats_screen.dart`
- Widgets: `pomodoro_timer.dart`, `task_card.dart`

##### State / Application Layer (Riverpod)
- Task Providers (list, filters, CRUD triggers)
- Timer Provider (Pomodoro state, ticking)
- Theme Provider

##### Domain Layer
- `Task` model (+ Hive adapter codegen)

##### Platform/Integration Services
- Notifications service (wraps `flutter_local_notifications`)
- (Implicit) device clock/timers used by Pomodoro provider

##### Hive
- On **mobile/desktop**: file-based storage
- On **web**: browser storage backend (Hive’s web support)

##### Notification System (OS)
- Android NotificationManager, iOS UNUserNotificationCenter, etc.
- Web notifications may differ; if unsupported, note “platform dependent”.

##### Android / iOS / Web / Desktop shells
- Them as “hosts” containing the same Flutter app bundle.

##### Task CRUD flow
**UI (Screens/Widgets)**
→ reads/watches **Task Providers (Riverpod)**
→ providers call **TaskRepository**
→ Hive persists to **Local Storage (File system / Browser storage)**
→ provider updates state
→ UI re-renders

##### Pomodoro timer flow
**PomodoroTimer widget / Home screen**
→ watches **Timer Provider**
→ timer provider uses **Dart timers/clock** (or similar scheduling)
→ on timer completion triggers:
- UI updates
- optionally calls **Notifications service** to schedule/show a local notification

##### Notifications flow
**UI/Providers**
→ `notifications.dart` service
→ `flutter_local_notifications` plugin
→ **Native OS notification APIs**
→ user sees notification; tapping it may reopen the app (platform-dependent routing; annotate if not implemented explicitly)

##### Theme flow
**UI**
→ watches **Theme Provider**
→ MaterialApp themeMode changes
→ UI re-renders

From structure, it closely matches:
- **Layered architecture / Clean-ish separation**
- Presentation (screens/widgets)
- Application state (providers)
- Data access (repository)
- Persistence (Hive)
- **Unidirectional data flow**
- UI observes provider state; user events invoke provider/repository writes; state changes propagate back to UI.
- **Adapter pattern** for platform services
- Notifications service wrapping plugin APIs
- **Code generation boundary**
- `task.g.dart` (Hive adapter) generated via `build_runner`

Call these out as small annotations so readers understand why boundaries exist.

##### Riverpod Providers
- TaskProviders
- TimerProvider
- ThemeProvider

##### Domain + Data
- Task model (+ task.g.dart adapter)
- TaskRepository

##### Persistence & Platform
- Local Storage backend (File/Browser)
- Notifications Service → flutter_local_notifications → OS Notification System

A small side panel: **Build/Targets**
- Android shell (`android/…`)
- iOS shell (`ios/…`)
- Web (`web/…`)
- Desktop (`windows/`, `macos/`, `linux/`)

This makes it obvious it’s the same app deployed to multiple hosts.

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% =========================
  %% Deployment / Host Targets
  %% =========================
  subgraph "Deployment Targets (Host Shells)"
    direction TB
    ANDROID["Android Host Shell"]:::host
    ANDROID_ENTRY["Android MainActivity (Flutter host entry)"]:::host
    IOS["iOS Host Shell"]:::host
    IOS_ENTRY["iOS AppDelegate (Flutter host entry)"]:::host
    WEB["Web Host Shell"]:::host
    WINDOWS["Windows Host Shell"]:::host
    MACOS["macOS Host Shell"]:::host
    LINUX["Linux Host Shell"]:::host

    ANDROID -->|"starts"| ANDROID_ENTRY
    IOS -->|"starts"| IOS_ENTRY
  end

  %% =========================
  %% Flutter / Dart Boundary
  %% =========================
  subgraph "FocusFlow Flutter App (Dart/Flutter layer)"
    direction TB

    MAIN["App Entrypoint & Bootstrap (ProviderScope, init, routing)"]:::core

    %% -------------------------
    %% Presentation Layer
    %% -------------------------
    subgraph "Presentation Layer (Screens & Widgets)"
      direction TB

      subgraph "Screens"
        direction TB
        HOME["Home Screen (Tasks + Pomodoro entry)"]:::ui
        ADD["Add Task Screen (Task creation UI)"]:::ui
        STATS["Stats Dashboard Screen"]:::ui
      end

      subgraph "Reusable Widgets"
        direction TB
        TASKCARD["Task Card Widget"]:::ui
        POMOW["Pomodoro Timer Widget"]:::ui
      end
    end

    %% -------------------------
    %% State / Application Layer
    %% -------------------------
    subgraph "State / Application Layer (Riverpod)"
      direction TB
      TASKP["Task Providers (task list state + CRUD orchestration)"]:::state
      TIMERP["Timer Provider (Pomodoro state/ticks)"]:::state
      THEMEP["Theme Provider (light/dark theme state)"]:::state
    end

    %% -------------------------
    %% Domain Layer
    %% -------------------------
    subgraph "Domain Layer"
      direction TB
      TASK["Task Model"]:::domain
      TASKG["Generated Hive Adapter (codegen)"]:::generated
      GENNOTE["Note: task.g.dart is generated via build_runner"]:::note
    end

    %% -------------------------
    %% Data Layer
    %% -------------------------
    subgraph "Data Layer"
      direction TB
      REPO["TaskRepository (Hive box CRUD abstraction)"]:::data
    end

    %% -------------------------
    %% Platform/Integration Services
    %% -------------------------
    subgraph "Platform/Integration Services"
      direction TB
      NOTIFSVC["Notifications Service (adapter)"]:::service
      FLNP["flutter_local_notifications (plugin)"]:::plugin
      CLOCK["Dart timers / device clock"]:::service
    end
  end

  %% =========================
  %% Local Persistence
  %% =========================
  subgraph "Local Persistence (Hive)"
    direction TB
    HIVE["Hive (Storage Engine)"]:::db
    BOX["Hive Box: tasks"]:::db
    STORAGE["Local Storage Backend (File system or Browser storage)"]:::storage
  end

  %% =========================
  %% Native Platform Layer
  %% =========================
  subgraph "Native Platform Layer (OS subsystems)"
    direction TB
    OSNOTIF["OS Notification System (NotificationManager / UNUserNotificationCenter / platform dependent)"]:::os
    USER["User"]:::external
  end

  %% =========================
  %% Wiring: deployment -> app
  %% =========================
  ANDROID_ENTRY -->|"runs"| MAIN
  IOS_ENTRY -->|"runs"| MAIN
  WEB -->|"runs"| MAIN
  WINDOWS -->|"runs"| MAIN
  MACOS -->|"runs"| MAIN
  LINUX -->|"runs"| MAIN

  %% =========================
  %% Wiring: Bootstrap
  %% =========================
  MAIN -->|"routes_to"| HOME
  MAIN -->|"routes_to"| ADD
  MAIN -->|"routes_to"| STATS
  MAIN -->|"initializes"| HIVE
  MAIN -->|"initializes"| NOTIFSVC

  %% =========================
  %% UI -> Providers (Unidirectional flow)
  %% =========================
  HOME -->|"watch(state) / user_events"| TASKP
  HOME -->|"watch(state) / user_events"| TIMERP
  HOME -->|"watch(themeMode)"| THEMEP

  ADD -->|"submit_task(form)"| TASKP
  STATS -->|"watch(state)"| TASKP

  TASKCARD -->|"render(Task) / user_events"| TASKP
  POMOW -->|"watch(state) / user_events"| TIMERP

  %% =========================
  %% Providers -> Domain/Data
  %% =========================
  TASKP -->|"createTask() / updateTask() / deleteTask()"| REPO
  TASKP -->|"uses(Task)"| TASK
  STATS -->|"reads(derived_stats)"| TASKP

  TIMERP -->|"tick() / schedule_next_tick"| CLOCK
  TIMERP -->|"onComplete()"| NOTIFSVC

  THEMEP -->|"themeMode_change"| HOME
  THEMEP -->|"themeMode_change"| ADD
  THEMEP -->|"themeMode_change"| STATS

  %% =========================
  %% Repository -> Hive -> Storage
  %% =========================
  REPO -->|"box.get() / box.put() / box.delete()"| BOX
  HIVE -->|"manages"| BOX
  BOX -->|"persist/read"| STORAGE

  %% =========================
  %% Hive Adapter / Codegen boundary
  %% =========================
  TASKG -->|"Hive TypeAdapter for Task"| HIVE
  TASKG -->|"serializes/deserializes"| TASK
  GENNOTE -.-> TASKG

  %% =========================
  %% Notifications flow
  %% =========================
  TASKP -->|"scheduleDueDateNotification(task) (optional)"| NOTIFSVC
  NOTIFSVC -->|"calls"| FLNP
  FLNP -->|"local_notification_request"| OSNOTIF
  OSNOTIF -->|"shows_notification"| USER
  USER -->|"tap_notification (platform dependent)"| MAIN

  %% =========================
  %% Annotations (patterns)
  %% =========================
  PATTERN1["Layered: UI → Providers → Repository → Hive"]:::note
  PATTERN2["Unidirectional data flow: UI watches provider state; writes via providers"]:::note
  PATTERN3["Adapter pattern: Notifications service wraps plugin & OS APIs"]:::note

  PATTERN1 -.-> HOME
  PATTERN1 -.-> TASKP
  PATTERN1 -.-> REPO
  PATTERN1 -.-> HIVE

  PATTERN2 -.-> TASKP
  PATTERN2 -.-> TIMERP
  PATTERN2 -.-> THEMEP

  PATTERN3 -.-> NOTIFSVC
  PATTERN3 -.-> FLNP
  PATTERN3 -.-> OSNOTIF

  %% =========================
  %% Click events (mapped paths)
  %% =========================
  click MAIN "https://github.com/adhilkrishnag/focusflow/blob/main/lib/main.dart"
  click HOME "https://github.com/adhilkrishnag/focusflow/blob/main/lib/screens/home_screen.dart"
  click ADD "https://github.com/adhilkrishnag/focusflow/blob/main/lib/screens/add_task_screen.dart"
  click STATS "https://github.com/adhilkrishnag/focusflow/blob/main/lib/screens/stats_screen.dart"
  click TASKCARD "https://github.com/adhilkrishnag/focusflow/blob/main/lib/widgets/task_card.dart"
  click POMOW "https://github.com/adhilkrishnag/focusflow/blob/main/lib/widgets/pomodoro_timer.dart"
  click TASKP "https://github.com/adhilkrishnag/focusflow/blob/main/lib/providers/task_providers.dart"
  click TIMERP "https://github.com/adhilkrishnag/focusflow/blob/main/lib/providers/timer_provider.dart"
  click THEMEP "https://github.com/adhilkrishnag/focusflow/blob/main/lib/providers/theme_provider.dart"
  click TASK "https://github.com/adhilkrishnag/focusflow/blob/main/lib/models/task.dart"
  click TASKG "https://github.com/adhilkrishnag/focusflow/blob/main/lib/models/task.g.dart"
  click REPO "https://github.com/adhilkrishnag/focusflow/blob/main/lib/repositories/task_repository.dart"
  click NOTIFSVC "https://github.com/adhilkrishnag/focusflow/blob/main/lib/services/notifications.dart"
  click ANDROID "https://github.com/adhilkrishnag/focusflow/tree/main/android/"
  click ANDROID_ENTRY "https://github.com/adhilkrishnag/focusflow/blob/main/android/app/src/main/kotlin/com/example/focus_flow/MainActivity.kt"
  click IOS "https://github.com/adhilkrishnag/focusflow/tree/main/ios/"
  click IOS_ENTRY "https://github.com/adhilkrishnag/focusflow/blob/main/ios/Runner/AppDelegate.swift"
  click WEB "https://github.com/adhilkrishnag/focusflow/tree/main/web/"
  click WINDOWS "https://github.com/adhilkrishnag/focusflow/tree/main/windows/"
  click MACOS "https://github.com/adhilkrishnag/focusflow/tree/main/macos/"
  click LINUX "https://github.com/adhilkrishnag/focusflow/tree/main/linux/"
  click PATTERN1 "https://github.com/adhilkrishnag/focusflow/tree/main/lib/"
  click PATTERN2 "https://github.com/adhilkrishnag/focusflow/tree/main/lib/providers/"
  click PATTERN3 "https://github.com/adhilkrishnag/focusflow/tree/main/lib/services/"
  click BOX "https://github.com/adhilkrishnag/focusflow/blob/main/lib/repositories/task_repository.dart"

  %% =========================
  %% Styles
  %% =========================
  classDef host fill:#2B2B2B,stroke:#111,stroke-width:1.5px,color:#F5F5F5
  classDef core fill:#1565C0,stroke:#0D47A1,stroke-width:2px,color:#FFFFFF
  classDef ui fill:#1E88E5,stroke:#0D47A1,stroke-width:1.5px,color:#FFFFFF
  classDef state fill:#7E57C2,stroke:#4A148C,stroke-width:1.5px,color:#FFFFFF
  classDef domain fill:#43A047,stroke:#1B5E20,stroke-width:1.5px,color:#FFFFFF
  classDef generated fill:#2E7D32,stroke:#1B5E20,stroke-width:1.5px,color:#E8F5E9
  classDef data fill:#FB8C00,stroke:#E65100,stroke-width:1.5px,color:#FFFFFF
  classDef service fill:#FDD835,stroke:#F9A825,stroke-width:1.5px,color:#212121
  classDef plugin fill:#FFEE58,stroke:#F9A825,stroke-width:1.5px,color:#212121
  classDef db fill:#90A4AE,stroke:#455A64,stroke-width:1.5px,color:#102027
  classDef storage fill:#B0BEC5,stroke:#546E7A,stroke-width:1.5px,color:#102027
  classDef os fill:#424242,stroke:#212121,stroke-width:1.5px,color:#FAFAFA
  classDef external fill:#263238,stroke:#000000,stroke-width:1.5px,color:#FFFFFF
  classDef note fill:#FFF3E0,stroke:#FFB74D,stroke-width:1px,color:#4E342E,stroke-dasharray: 4 3
```
