# rjv-yf/rituals architecture

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

- Interactive diagram: https://gitdiagram.com/rjv-yf/rituals
- Repository: https://github.com/rjv-yf/rituals

## Overview

Rituals is a local-first Flutter habit tracker. Users maintain a daily task list, mark tasks complete, and can attach repeat/alarm details; tracked history then powers a yearly consistency heatmap, at-a-glance statistics, and monthly summaries. The README describes Cubit state management, a task repository and local Isar storage, with heatmaps reading through the task repository. Android exposes a native alarm bridge. Dart implementation details were not sampled, so unverified wiring is shown as dashed rather than asserted.

Main entry points: [`lib/features/heatmaps/presentation/pages/heatmap_page.dart`](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/pages/heatmap_page.dart) (Heatmap screen), [`lib/features/tasks/presentation/pages/tasks_page.dart`](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/pages/tasks_page.dart) (Task list), [`lib/features/tasks/data/task_repository.dart`](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/task_repository.dart) (Task repository), [`lib/features/tasks/presentation/cubit/tasks_cubit.dart`](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/cubit/tasks_cubit.dart) (Task state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_task_flow["Daily tasks"]
  node_task_screen["Task list<br/>[tasks_page.dart]"]
  node_task_form["Task editor"]
  node_task_tile["Task row<br/>[task_tile.dart]"]
  node_task_state["Task state<br/>[tasks_cubit.dart]"]
  node_task_repo["Task repository"]
  node_task_model["Task model<br/>[task.dart]"]
  node_task_draft["Task draft<br/>[task_draft.dart]"]
end

subgraph group_history["History insights"]
  node_insight_screen["Heatmap screen<br/>[heatmap_page.dart]"]
  node_insight_state["Heatmap state<br/>[heatmap_cubit.dart]"]
  node_analytics_repo["Analytics repository"]
  node_heatmap_view["Year heatmap<br/>[heatmap_card.dart]"]
  node_analytics_cards["Statistics cards"]
  node_month_summary["Monthly summaries"]
end

subgraph group_alarm["Alarm integration"]
  node_alarm_service["Alarm service<br/>[alarm_service.dart]"]
  node_android_activity["Flutter activity<br/>[MainActivity.kt]"]
  node_alarm_bridge["Alarm bridge<br/>[AlarmBridge.kt]"]
  node_clock_app["Device clock"]
end

subgraph group_app_core["App foundation"]
  node_app_entry["App entry<br/>[main.dart]"]
  node_app_shell["App shell<br/>[app.dart]"]
  node_local_store[("Local database<br/>[app_database.dart]")]
end

node_user(("User"))

node_user -->|"opens app"| node_app_entry
node_app_entry -.->|"starts app"| node_app_shell
node_user -->|"manages tasks"| node_task_screen
node_task_screen -.->|"updates state"| node_task_state
node_task_screen -->|"edits tasks"| node_task_form
node_task_screen -.->|"shows tasks"| node_task_tile
node_task_state -.->|"requests task data"| node_task_repo
node_task_repo -.->|"persists tasks"| node_local_store
node_task_repo -.->|"uses task records"| node_task_model
node_task_form -.->|"prepares task"| node_task_draft
node_user -->|"reviews history"| node_insight_screen
node_insight_screen -.->|"loads insights"| node_insight_state
node_insight_state -.->|"requests summaries"| node_analytics_repo
node_analytics_repo -->|"reads task history"| node_task_repo
node_insight_screen -->|"shows consistency"| node_heatmap_view
node_insight_screen -->|"shows statistics"| node_analytics_cards
node_insight_screen -->|"shows monthly breakdown"| node_month_summary
node_task_state -.->|"sets task alarms"| node_alarm_service
node_alarm_service -.->|"invokes alarm channel"| node_android_activity
node_android_activity -->|"dispatches method calls"| node_alarm_bridge
node_alarm_bridge -->|"requests alarm"| node_clock_app

click node_app_entry "https://github.com/rjv-yf/rituals/blob/master/lib/main.dart"
click node_app_shell "https://github.com/rjv-yf/rituals/blob/master/lib/app.dart"
click node_task_screen "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/pages/tasks_page.dart"
click node_task_form "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/pages/task_form_sheet.dart"
click node_task_tile "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/widgets/task_tile.dart"
click node_task_state "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/cubit/tasks_cubit.dart"
click node_task_repo "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/task_repository.dart"
click node_task_model "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/models/task.dart"
click node_task_draft "https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/models/task_draft.dart"
click node_local_store "https://github.com/rjv-yf/rituals/blob/master/lib/core/database/app_database.dart"
click node_alarm_service "https://github.com/rjv-yf/rituals/blob/master/lib/core/services/alarm_service.dart"
click node_android_activity "https://github.com/rjv-yf/rituals/blob/master/android/app/src/main/kotlin/dev/rajeever/rituals/MainActivity.kt"
click node_alarm_bridge "https://github.com/rjv-yf/rituals/blob/master/android/app/src/main/kotlin/dev/rajeever/rituals/AlarmBridge.kt"
click node_insight_screen "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/pages/heatmap_page.dart"
click node_insight_state "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/cubit/heatmap_cubit.dart"
click node_analytics_repo "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/data/analytics_repository.dart"
click node_heatmap_view "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/heatmap_card.dart"
click node_analytics_cards "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/analytics_card.dart"
click node_month_summary "https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/month_summary_tile.dart"

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_task_screen,node_task_form,node_task_tile,node_task_state,node_task_repo,node_task_model,node_task_draft,node_user toneBlue
class node_insight_screen,node_insight_state,node_analytics_repo,node_heatmap_view,node_analytics_cards,node_month_summary toneAmber
class node_alarm_service,node_android_activity,node_alarm_bridge,node_clock_app toneMint
class node_app_entry,node_app_shell,node_local_store toneRose
```

## Components

### Daily tasks

- [Task list](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/pages/tasks_page.dart): `lib/features/tasks/presentation/pages/tasks_page.dart`
- [Task editor](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/pages/task_form_sheet.dart): `lib/features/tasks/presentation/pages/task_form_sheet.dart`
- [Task row](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/widgets/task_tile.dart): `lib/features/tasks/presentation/widgets/task_tile.dart`
- [Task state](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/presentation/cubit/tasks_cubit.dart): `lib/features/tasks/presentation/cubit/tasks_cubit.dart`
- [Task repository](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/task_repository.dart): `lib/features/tasks/data/task_repository.dart`
- [Task model](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/models/task.dart): `lib/features/tasks/data/models/task.dart`
- [Task draft](https://github.com/rjv-yf/rituals/blob/master/lib/features/tasks/data/models/task_draft.dart): `lib/features/tasks/data/models/task_draft.dart`

### History insights

- [Heatmap screen](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/pages/heatmap_page.dart): `lib/features/heatmaps/presentation/pages/heatmap_page.dart`
- [Heatmap state](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/cubit/heatmap_cubit.dart): `lib/features/heatmaps/presentation/cubit/heatmap_cubit.dart`
- [Analytics repository](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/data/analytics_repository.dart): `lib/features/heatmaps/data/analytics_repository.dart`
- [Year heatmap](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/heatmap_card.dart): `lib/features/heatmaps/presentation/widgets/heatmap_card.dart`
- [Statistics cards](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/analytics_card.dart): `lib/features/heatmaps/presentation/widgets/analytics_card.dart`
- [Monthly summaries](https://github.com/rjv-yf/rituals/blob/master/lib/features/heatmaps/presentation/widgets/month_summary_tile.dart): `lib/features/heatmaps/presentation/widgets/month_summary_tile.dart`

### Alarm integration

- [Alarm service](https://github.com/rjv-yf/rituals/blob/master/lib/core/services/alarm_service.dart): `lib/core/services/alarm_service.dart`
- [Flutter activity](https://github.com/rjv-yf/rituals/blob/master/android/app/src/main/kotlin/dev/rajeever/rituals/MainActivity.kt): `android/app/src/main/kotlin/dev/rajeever/rituals/MainActivity.kt`
- [Alarm bridge](https://github.com/rjv-yf/rituals/blob/master/android/app/src/main/kotlin/dev/rajeever/rituals/AlarmBridge.kt): `android/app/src/main/kotlin/dev/rajeever/rituals/AlarmBridge.kt`
- **Device clock**

### App foundation

- [App entry](https://github.com/rjv-yf/rituals/blob/master/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/rjv-yf/rituals/blob/master/lib/app.dart): `lib/app.dart`
- [Local database](https://github.com/rjv-yf/rituals/blob/master/lib/core/database/app_database.dart): `lib/core/database/app_database.dart`

### Other components

- **User**

## Connections

- User → App entry: opens app (evidence: `README.md`)
- App entry → App shell: starts app
- User → Task list: manages tasks (evidence: `README.md`)
- Task list → Task state: updates state
- Task list → Task editor: edits tasks (evidence: `README.md`)
- Task list → Task row: shows tasks
- Task state → Task repository: requests task data
- Task repository → Local database: persists tasks
- Task repository → Task model: uses task records
- Task editor → Task draft: prepares task
- User → Heatmap screen: reviews history (evidence: `README.md`)
- Heatmap screen → Heatmap state: loads insights
- Heatmap state → Analytics repository: requests summaries
- Analytics repository → Task repository: reads task history (evidence: `README.md`)
- Heatmap screen → Year heatmap: shows consistency (evidence: `README.md`)
- Heatmap screen → Statistics cards: shows statistics (evidence: `README.md`)
- Heatmap screen → Monthly summaries: shows monthly breakdown (evidence: `README.md`)
- Task state → Alarm service: sets task alarms
- Alarm service → Flutter activity: invokes alarm channel
- Flutter activity → Alarm bridge: dispatches method calls (evidence: `android/app/src/main/kotlin/dev/rajeever/rituals/MainActivity.kt`)
- Alarm bridge → Device clock: requests alarm (evidence: `android/app/src/main/kotlin/dev/rajeever/rituals/AlarmBridge.kt`)