# sufiyan-sabeel/flow-tracker architecture

> Architecture diagram of the GitHub repository sufiyan-sabeel/flow-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sufiyan-sabeel/flow-tracker
- Repository: https://github.com/sufiyan-sabeel/flow-tracker

## Overview

Flow-tracker is a private, offline habit-tracking app. The main user workflow is to record habits and tasks, then review today’s completion, streaks, statistics, and history. The README describes the Flutter feature and storage layers, but those source files are absent from the supplied tree; their links below reflect documented architecture rather than inspected implementation. The sampled native code shows Android host bridges and widget action/rendering paths, plus iOS widget payload handling. Other platform-specific app behavior is not mapped where the evidence is insufficient.

Main entry points: [`lib/app`](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/app) (App shell), [`lib/core`](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/core) (Local storage), [`android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt`](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt) (Widget action receiver), [`android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt`](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt) (Widget action worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_app["App shell"]
end

subgraph group_domain["Tracking and progress"]
  node_tracking["Habit tracking"]
  node_todos["To-do tracking"]
  node_focus["Focus sessions"]
  node_progress["Progress views"]
  node_settings["Settings and themes"]
end

subgraph group_data["Local data services"]
  node_storage[("Local storage")]
  node_data_services["Backup and import"]
  node_widget_service["Widget payload service"]
end

subgraph group_android["Android integration"]
  node_android_host["Android Flutter host<br/>[MainActivity.kt]"]
  node_android_focus["Focus service<br/>[FocusService.kt]"]
  node_android_widgets["Android home widgets<br/>[GlanceWidgets.kt]"]
  node_android_heatmap["Heatmap renderer<br/>[HeatmapRenderer.kt]"]
  node_android_actions["Widget action receiver"]
  node_android_worker["Widget action worker"]
  node_android_queue["Widget action queue"]
end

subgraph group_ios["iOS widgets"]
  node_ios_payload["Shared widget payload<br/>[Payload.swift]"]
  node_ios_widgets["iOS widgets"]
end

node_user(("Phone user"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_tracking
node_app -->|"routes to"| node_todos
node_app -->|"routes to"| node_focus
node_app -->|"shows"| node_progress
node_app -->|"configures"| node_settings
node_tracking -->|"persists locally"| node_storage
node_todos -->|"persists locally"| node_storage
node_focus -->|"persists locally"| node_storage
node_progress -->|"reads history"| node_storage
node_data_services -->|"backs up"| node_storage
node_widget_service -->|"feeds payload"| node_android_widgets
node_android_host -->|"bridges focus"| node_android_focus
node_android_host -->|"registers bridge"| node_android_actions
node_android_widgets -->|"refreshes heatmap"| node_android_heatmap
node_android_actions -->|"enqueues actions"| node_android_queue
node_android_actions -->|"schedules work"| node_android_worker
node_android_worker -->|"reads actions"| node_android_queue
node_android_worker -->|"refreshes content"| node_android_heatmap
node_ios_payload -->|"supplies data"| node_ios_widgets

click node_app "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/app"
click node_tracking "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features"
click node_todos "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features"
click node_focus "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features"
click node_progress "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features"
click node_settings "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features"
click node_storage "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/core"
click node_data_services "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/services"
click node_widget_service "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/services"
click node_android_host "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/MainActivity.kt"
click node_android_focus "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/FocusService.kt"
click node_android_widgets "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/GlanceWidgets.kt"
click node_android_heatmap "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/HeatmapRenderer.kt"
click node_android_actions "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt"
click node_android_worker "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt"
click node_android_queue "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionQueue.kt"
click node_ios_payload "https://github.com/sufiyan-sabeel/flow-tracker/blob/main/ios/FlowTrackerWidgets/Payload.swift"
click node_ios_widgets "https://github.com/sufiyan-sabeel/flow-tracker/tree/main/ios/FlowTrackerWidgets"

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_user toneBlue
class node_tracking,node_todos,node_focus,node_progress,node_settings toneAmber
class node_storage,node_data_services,node_widget_service toneMint
class node_android_host,node_android_focus,node_android_widgets,node_android_heatmap,node_android_actions,node_android_worker,node_android_queue toneRose
class node_ios_payload,node_ios_widgets toneIndigo
```

## Components

### Flutter app

- [App shell](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/app): `lib/app`

### Tracking and progress

- [Habit tracking](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features): `lib/features`
- [To-do tracking](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features): `lib/features`
- [Focus sessions](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features): `lib/features`
- [Progress views](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features): `lib/features`
- [Settings and themes](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/features): `lib/features`

### Local data services

- [Local storage](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/core): `lib/core`
- [Backup and import](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/services): `lib/services`
- [Widget payload service](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/lib/services): `lib/services`

### Android integration

- [Android Flutter host](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/MainActivity.kt): `android/app/src/main/kotlin/com/flowtracker/app/MainActivity.kt`
- [Focus service](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/FocusService.kt): `android/app/src/main/kotlin/com/flowtracker/app/FocusService.kt`
- [Android home widgets](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/GlanceWidgets.kt): `android/app/src/main/kotlin/com/flowtracker/app/GlanceWidgets.kt`
- [Heatmap renderer](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/HeatmapRenderer.kt): `android/app/src/main/kotlin/com/flowtracker/app/HeatmapRenderer.kt`
- [Widget action receiver](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt): `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt`
- [Widget action worker](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt): `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt`
- [Widget action queue](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/android/app/src/main/kotlin/com/flowtracker/app/WidgetActionQueue.kt): `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionQueue.kt`

### iOS widgets

- [Shared widget payload](https://github.com/sufiyan-sabeel/flow-tracker/blob/main/ios/FlowTrackerWidgets/Payload.swift): `ios/FlowTrackerWidgets/Payload.swift`
- [iOS widgets](https://github.com/sufiyan-sabeel/flow-tracker/tree/main/ios/FlowTrackerWidgets): `ios/FlowTrackerWidgets`

### Other components

- **Phone user**

## Connections

- Phone user → App shell: uses
- App shell → Habit tracking: routes to
- App shell → To-do tracking: routes to
- App shell → Focus sessions: routes to
- App shell → Progress views: shows
- App shell → Settings and themes: configures
- Habit tracking → Local storage: persists locally
- To-do tracking → Local storage: persists locally
- Focus sessions → Local storage: persists locally
- Progress views → Local storage: reads history
- Backup and import → Local storage: backs up
- Widget payload service → Android home widgets: feeds payload
- Android Flutter host → Focus service: bridges focus (evidence: `android/app/src/main/kotlin/com/flowtracker/app/MainActivity.kt`)
- Android Flutter host → Widget action receiver: registers bridge (evidence: `android/app/src/main/kotlin/com/flowtracker/app/MainActivity.kt`)
- Android home widgets → Heatmap renderer: refreshes heatmap (evidence: `android/app/src/main/kotlin/com/flowtracker/app/GlanceWidgets.kt`)
- Widget action receiver → Widget action queue: enqueues actions
- Widget action receiver → Widget action worker: schedules work (evidence: `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionReceiver.kt`)
- Widget action worker → Widget action queue: reads actions (evidence: `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt`)
- Widget action worker → Heatmap renderer: refreshes content (evidence: `android/app/src/main/kotlin/com/flowtracker/app/WidgetActionWorker.kt`)
- Shared widget payload → iOS widgets: supplies data (evidence: `ios/FlowTrackerWidgets/Payload.swift`)