# xpavle00/habo architecture

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

- Interactive diagram: https://gitdiagram.com/xpavle00/habo
- Repository: https://github.com/xpavle00/habo

## Overview

1. **Product shape**
   Habo is a **Flutter 3.x mobile app** for iOS and Android, with desktop shells present for Linux and macOS but the core product is clearly mobile-first. The app is **offline-first** and centers on local habit tracking, with optional cloud sync and encrypted backups.

2. **Top-level architecture**
   The Dart app is organized in a fairly clean layered split:
   - `lib/screens`, `lib/habits`, `lib/statistics`, `lib/settings`, `lib/onboarding`, `lib/widgets` for UI
   - `lib/services` for cross-cutting capabilities
   - `lib/repositories` for persistence and sync data access
   - `lib/model` for domain/data objects
   - `lib/navigation` for app flow
   This makes the repo diagram easier to draw as **UI → managers/services → repositories → storage/sync**.

3. **Core domain: habits**
   The main domain objects live in `lib/model` and `lib/habits`. The habit area includes the list screen, edit screen, calendar visualization, day selectors, empty states, and a `HabitsManager` that likely coordinates business rules such as completion updates, ordering, archiving, and reminder behavior. This is the heart of the app.

4. **Local persistence boundary**
   Persistence is abstracted behind repositories:
   - `habit_repository`
   - `category_repository`
   - `event_repository`
   - `backup_repository`
   with SQLite-backed implementations in the `sqlite_*` files.
   The architecture suggests **repositories as the boundary** between domain/UI code and the local database, allowing sync and backup layers to work on the same model without coupling to UI.

5. **Sync and backup subsystem**
   The app has a separate sync stack in `lib/services` and `lib/screens/sync_*`:
   - `SyncManager` coordinates sync state and orchestration
   - `SyncService` handles remote operations
   - `BackupService` / `BackupResult` handle encrypted backup creation and restore
   - `SyncError` captures failures
   The README clarifies that sync is **end-to-end encrypted**: data is encrypted locally with a master password before leaving the device. That means the cloud boundary only sees ciphertext.

6. **Backend dependency: Supabase**
   The cloud side lives under `supabase/` and is not a generic web backend; it’s specifically **Supabase**:
   - SQL migrations define the remote schema
   - an Edge Function `delete-account` handles account deletion
   - `supabase/config.toml` and README indicate self-hosting support
   So the mobile app talks to a Supabase project configured by the user, rather than a fixed proprietary backend.

7. **Encryption and authentication flow**
   Security-sensitive features are split into services:
   - `encryption_service`
   - `biometric_auth_service`
   - sync/password-related screens and widgets
   - master password views in the sync flow
   The intended boundary is: **user authenticates locally, data is encrypted locally, then synchronized**. Biometrics appear to gate access, while the master password protects sync material and backups.

8. **Device integrations**
   Several services bridge the app to native platform features:
   - `notification_service` for reminders
   - `home_widget_service` plus Android/iOS widget code for home screen widgets
   - `ui_feedback_service` for haptics/sounds/UX feedback
   - `subscription_service` for monetization or entitlement checks
   These are the main places where Flutter crosses into native capabilities.

9. **Platform-specific UI extensions**
   The repo includes full native project trees for **Android, iOS, macOS, and Linux**, but the notable app-specific platform work is Android/iOS widgets:
   - Android `HaboWidget.kt`, `WidgetUpdateWorker.kt`, and widget layout/resources
   - iOS `HaboWidget` Swift extension and widget bundle
   This indicates the app pushes habit status to platform home screen widgets via platform-native extensions, likely fed by shared widget data from Flutter.

10. **Navigation and app flow**
    Navigation is custom rather than purely declarative screen-to-screen calls. The `navigation` folder contains:
    - `app_router`
    - `route_information_parser`
    - `app_state_manager`
    - route definitions
    This suggests a centralized routing/state model, probably supporting onboarding, auth/sync setup, settings, and deep links.

11. **Onboarding and sync setup**
    The `onboarding` and `screens/sync_*` areas indicate multiple entry flows:
    - initial app onboarding
    - sync onboarding
    - server configuration
    - login/master password/profile flows
    That means the app has a distinct **setup path for sync-enabled users** separate from normal local usage.

12. **Statistics and visualization**
    `lib/statistics` contains monthly graphs, summary cards, and empty states. This is a read-only analytics slice built on top of habit/event data. It likely reads from repositories rather than mutating state, which is a clean separation from the core habit editing flow.

13. **Localization and asset pipeline**
    The app is heavily internationalized:
    - ARB source files in `lib/l10n`
    - generated Dart localization in `lib/generated/intl`
    - many translated storefront metadata files under `fastlane/metadata`
    Assets include onboarding images and UI sounds. This means the diagram should show **localized UI and static assets as shared input** across multiple screens, not as separate subsystems.

14. **Quality, build, and release infrastructure**
    The repo includes:
    - GitHub Actions CI
    - Flutter tests covering models, repositories, services, widgets, and integration flows
    - Fastlane metadata for app-store distribution
    - Android/iOS platform build scaffolding
    This indicates a mature mobile release pipeline, with test coverage focused especially on sync, backup, encryption, and repository behavior.

15. **Key architectural summary**
    The simplest accurate diagram is:
    **Flutter UI and navigation** drive **habit, settings, onboarding, and sync flows**; those call into **services and managers**; services use **SQLite repositories** for local state and **Supabase sync services** for remote encrypted sync; platform services handle **notifications, biometrics, widgets, and feedback**; everything is wrapped by **local-first, end-to-end encrypted data handling**.

Main entry points: [`lib/navigation/app_router.dart`](https://github.com/xpavle00/habo/blob/master/lib/navigation/app_router.dart) (App router), [`lib/repositories/repository_factory.dart`](https://github.com/xpavle00/habo/blob/master/lib/repositories/repository_factory.dart) (Repo factory), [`lib/habits/habits_manager.dart`](https://github.com/xpavle00/habo/blob/master/lib/habits/habits_manager.dart) (Habits manager), [`lib/services/service_locator.dart`](https://github.com/xpavle00/habo/blob/master/lib/services/service_locator.dart) (Service locator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_lib_main["Main app<br/>Flutter entry<br/>[main.dart]"]
  node_lib_navigation_app_router["App router<br/>Navigation<br/>[app_router.dart]"]
  node_lib_navigation_app_state_manager["App state<br/>Navigation state"]
end

subgraph group_feature_ui["Feature UI"]
  node_lib_onboarding_onboarding_screen["Onboarding<br/>First-run UI"]
  node_lib_habits_habits_screen["Habits UI<br/>Habit screen<br/>[habits_screen.dart]"]
  node_lib_statistics_statistics_screen["Statistics<br/>Analytics UI"]
  node_lib_settings_settings_screen["Settings"]
  node_lib_screens_sync_screen["Sync setup<br/>Sync UI<br/>[sync_screen.dart]"]
end

subgraph group_core_services["Core services"]
  node_lib_habits_habits_manager["Habits manager<br/>Habit logic"]
  node_lib_widgets_biometric_auth_wrapper["Biometric gate<br/>Auth widget"]
  node_lib_services_service_locator["Service locator<br/>Wiring"]
  node_lib_services_encryption_service["Encryption<br/>Crypto service"]
  node_lib_services_sync_manager["Sync manager<br/>Sync orchestrator<br/>[sync_manager.dart]"]
  node_lib_services_sync_service["Sync service<br/>Remote sync<br/>[sync_service.dart]"]
  node_lib_services_backup_service["Backup service<br/>Encrypted backup"]
  node_lib_services_notification_service["Notifications<br/>Reminder service"]
  node_lib_services_home_widget_service["Widget bridge<br/>Platform bridge"]
  node_lib_widgets_home_widget_data["Widget data<br/>Shared payload"]
  node_android_widget["Android widget<br/>Native widget<br/>[HaboWidget.kt]"]
  node_ios_widget["iOS widget<br/>Native widget<br/>[HaboWidget.swift]"]
end

subgraph group_data_backend["Data & backend"]
  node_lib_repositories_repository_factory["Repo factory<br/>Repository wiring"]
  node_lib_repositories_sqlite_repositories[("SQLite repos<br/>Local storage")]
  node_lib_model_habo_model["Domain model<br/>Data model<br/>[habo_model.dart]"]
  node_supabase_migrations_remote_schema["Remote schema<br/>Supabase SQL"]
  node_supabase_functions_delete_account_index["Delete account<br/>Edge function<br/>[index.ts]"]
end

node_lib_main -->|"starts"| node_lib_navigation_app_router
node_lib_main -->|"initializes"| node_lib_services_service_locator
node_lib_navigation_app_router -->|"uses"| node_lib_navigation_app_state_manager
node_lib_navigation_app_router -->|"routes to"| node_lib_onboarding_onboarding_screen
node_lib_navigation_app_router -->|"routes to"| node_lib_habits_habits_screen
node_lib_navigation_app_router -->|"routes to"| node_lib_statistics_statistics_screen
node_lib_navigation_app_router -->|"routes to"| node_lib_settings_settings_screen
node_lib_navigation_app_router -->|"routes to"| node_lib_screens_sync_screen
node_lib_habits_habits_screen -->|"reads/writes"| node_lib_habits_habits_manager
node_lib_habits_habits_manager -->|"uses"| node_lib_repositories_repository_factory
node_lib_habits_habits_manager -->|"updates"| node_lib_services_notification_service
node_lib_habits_habits_manager -->|"publishes"| node_lib_services_home_widget_service
node_lib_habits_habits_manager -.->|"protects data"| node_lib_services_encryption_service
node_lib_statistics_statistics_screen -->|"reads"| node_lib_repositories_repository_factory
node_lib_screens_sync_screen -->|"orchestrates"| node_lib_services_sync_manager
node_lib_screens_sync_screen -->|"uses"| node_lib_services_backup_service
node_lib_screens_sync_screen -->|"gates"| node_lib_widgets_biometric_auth_wrapper
node_lib_services_sync_manager -->|"coordinates"| node_lib_services_sync_service
node_lib_services_sync_manager -->|"encrypts"| node_lib_services_encryption_service
node_lib_services_sync_manager -->|"syncs from"| node_lib_repositories_repository_factory
node_lib_services_backup_service -->|"encrypts"| node_lib_services_encryption_service
node_lib_services_backup_service -->|"reads/writes"| node_lib_repositories_repository_factory
node_lib_services_service_locator -->|"provides"| node_lib_repositories_repository_factory
node_lib_services_service_locator -->|"provides"| node_lib_services_sync_manager
node_lib_services_service_locator -->|"provides"| node_lib_services_backup_service
node_lib_services_service_locator -->|"provides"| node_lib_services_notification_service
node_lib_repositories_repository_factory -->|"selects"| node_lib_repositories_sqlite_repositories
node_lib_repositories_sqlite_repositories -->|"persists"| node_lib_model_habo_model
node_lib_services_sync_service -->|"targets"| node_supabase_migrations_remote_schema
node_lib_services_sync_service -->|"calls"| node_supabase_functions_delete_account_index
node_lib_services_home_widget_service -->|"formats"| node_lib_widgets_home_widget_data
node_lib_services_home_widget_service -->|"updates"| node_android_widget
node_lib_services_home_widget_service -->|"updates"| node_ios_widget
node_lib_widgets_biometric_auth_wrapper -.->|"protects access"| node_lib_services_encryption_service

click node_lib_main "https://github.com/xpavle00/habo/blob/master/lib/main.dart"
click node_lib_navigation_app_router "https://github.com/xpavle00/habo/blob/master/lib/navigation/app_router.dart"
click node_lib_navigation_app_state_manager "https://github.com/xpavle00/habo/blob/master/lib/navigation/app_state_manager.dart"
click node_lib_onboarding_onboarding_screen "https://github.com/xpavle00/habo/blob/master/lib/onboarding/onboarding_screen.dart"
click node_lib_habits_habits_screen "https://github.com/xpavle00/habo/blob/master/lib/habits/habits_screen.dart"
click node_lib_habits_habits_manager "https://github.com/xpavle00/habo/blob/master/lib/habits/habits_manager.dart"
click node_lib_statistics_statistics_screen "https://github.com/xpavle00/habo/blob/master/lib/statistics/statistics_screen.dart"
click node_lib_settings_settings_screen "https://github.com/xpavle00/habo/blob/master/lib/settings/settings_screen.dart"
click node_lib_screens_sync_screen "https://github.com/xpavle00/habo/blob/master/lib/screens/sync_screen.dart"
click node_lib_widgets_biometric_auth_wrapper "https://github.com/xpavle00/habo/blob/master/lib/widgets/biometric_auth_wrapper.dart"
click node_lib_services_service_locator "https://github.com/xpavle00/habo/blob/master/lib/services/service_locator.dart"
click node_lib_services_encryption_service "https://github.com/xpavle00/habo/blob/master/lib/services/encryption_service.dart"
click node_lib_services_sync_manager "https://github.com/xpavle00/habo/blob/master/lib/services/sync_manager.dart"
click node_lib_services_sync_service "https://github.com/xpavle00/habo/blob/master/lib/services/sync_service.dart"
click node_lib_services_backup_service "https://github.com/xpavle00/habo/blob/master/lib/services/backup_service.dart"
click node_lib_services_notification_service "https://github.com/xpavle00/habo/blob/master/lib/services/notification_service.dart"
click node_lib_services_home_widget_service "https://github.com/xpavle00/habo/blob/master/lib/services/home_widget_service.dart"
click node_lib_widgets_home_widget_data "https://github.com/xpavle00/habo/blob/master/lib/widgets/home_widget_data.dart"
click node_lib_repositories_repository_factory "https://github.com/xpavle00/habo/blob/master/lib/repositories/repository_factory.dart"
click node_lib_repositories_sqlite_repositories "https://github.com/xpavle00/habo/blob/master/lib/repositories/sqlite_repositories.dart"
click node_lib_model_habo_model "https://github.com/xpavle00/habo/blob/master/lib/model/habo_model.dart"
click node_supabase_migrations_remote_schema "https://github.com/xpavle00/habo/blob/master/supabase/migrations/20260313191900_remote_schema.sql"
click node_supabase_functions_delete_account_index "https://github.com/xpavle00/habo/blob/master/supabase/functions/delete-account/index.ts"
click node_android_widget "https://github.com/xpavle00/habo/blob/master/android/app/src/main/java/com/pavlenko/Habo/HaboWidget.kt"
click node_ios_widget "https://github.com/xpavle00/habo/blob/master/ios/HaboWidget/HaboWidget.swift"

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_lib_main,node_lib_navigation_app_router,node_lib_navigation_app_state_manager toneBlue
class node_lib_onboarding_onboarding_screen,node_lib_habits_habits_screen,node_lib_statistics_statistics_screen,node_lib_settings_settings_screen,node_lib_screens_sync_screen toneAmber
class node_lib_habits_habits_manager,node_lib_widgets_biometric_auth_wrapper,node_lib_services_service_locator,node_lib_services_encryption_service,node_lib_services_sync_manager,node_lib_services_sync_service,node_lib_services_backup_service,node_lib_services_notification_service,node_lib_services_home_widget_service,node_lib_widgets_home_widget_data,node_android_widget,node_ios_widget toneMint
class node_lib_repositories_repository_factory,node_lib_repositories_sqlite_repositories,node_lib_model_habo_model,node_supabase_migrations_remote_schema,node_supabase_functions_delete_account_index toneRose
```

## Components

### App shell

Entry point, routing, onboarding, and shared app flow.

- [Main app](https://github.com/xpavle00/habo/blob/master/lib/main.dart): Flutter entry · Bootstraps the mobile app and initializes shared services. · `lib/main.dart`
- [App router](https://github.com/xpavle00/habo/blob/master/lib/navigation/app_router.dart): Navigation · Centralized route and flow coordination for the app. · `lib/navigation/app_router.dart`
- [App state](https://github.com/xpavle00/habo/blob/master/lib/navigation/app_state_manager.dart): Navigation state · Holds routing state and app-level navigation decisions. · `lib/navigation/app_state_manager.dart`

### Feature UI

Primary user-facing screens for habits, statistics, settings, and sync.

- [Onboarding](https://github.com/xpavle00/habo/blob/master/lib/onboarding/onboarding_screen.dart): First-run UI · Initial setup flow for new users. · `lib/onboarding/onboarding_screen.dart`
- [Habits UI](https://github.com/xpavle00/habo/blob/master/lib/habits/habits_screen.dart): Habit screen · Primary habit list and editing entry point. · `lib/habits/habits_screen.dart`
- [Statistics](https://github.com/xpavle00/habo/blob/master/lib/statistics/statistics_screen.dart): Analytics UI · Read-only habit analytics and summaries. · `lib/statistics/statistics_screen.dart`
- [Settings](https://github.com/xpavle00/habo/blob/master/lib/settings/settings_screen.dart): Settings UI · Configuration, account, and app preferences screens. · `lib/settings/settings_screen.dart`
- [Sync setup](https://github.com/xpavle00/habo/blob/master/lib/screens/sync_screen.dart): Sync UI · User-facing sync onboarding, login, and account setup flow. · `lib/screens/sync_screen.dart`

### Core services

Managers and cross-cutting services for sync, encryption, backups, notifications, and platform integrations.

- [Habits manager](https://github.com/xpavle00/habo/blob/master/lib/habits/habits_manager.dart): Habit logic · Coordinates habit state, ordering, completion, and reminders. · `lib/habits/habits_manager.dart`
- [Biometric gate](https://github.com/xpavle00/habo/blob/master/lib/widgets/biometric_auth_wrapper.dart): Auth widget · Wraps protected flows with local biometric authentication. · `lib/widgets/biometric_auth_wrapper.dart`
- [Service locator](https://github.com/xpavle00/habo/blob/master/lib/services/service_locator.dart): Wiring · Builds and shares app services and repositories. · `lib/services/service_locator.dart`
- [Encryption](https://github.com/xpavle00/habo/blob/master/lib/services/encryption_service.dart): Crypto service · Encrypts and decrypts local backup and sync payloads. · `lib/services/encryption_service.dart`
- [Sync manager](https://github.com/xpavle00/habo/blob/master/lib/services/sync_manager.dart): Sync orchestrator · Coordinates sync state, orchestration, and error handling. · `lib/services/sync_manager.dart`
- [Sync service](https://github.com/xpavle00/habo/blob/master/lib/services/sync_service.dart): Remote sync · Performs remote operations against the cloud backend. · `lib/services/sync_service.dart`
- [Backup service](https://github.com/xpavle00/habo/blob/master/lib/services/backup_service.dart): Encrypted backup · Creates and restores encrypted local backups. · `lib/services/backup_service.dart`
- [Notifications](https://github.com/xpavle00/habo/blob/master/lib/services/notification_service.dart): Reminder service · Schedules and manages habit reminder notifications. · `lib/services/notification_service.dart`
- [Widget bridge](https://github.com/xpavle00/habo/blob/master/lib/services/home_widget_service.dart): Platform bridge · Feeds shared data to native home screen widgets. · `lib/services/home_widget_service.dart`
- [Widget data](https://github.com/xpavle00/habo/blob/master/lib/widgets/home_widget_data.dart): Shared payload · Data model for syncing app state to widgets. · `lib/widgets/home_widget_data.dart`
- [Android widget](https://github.com/xpavle00/habo/blob/master/android/app/src/main/java/com/pavlenko/Habo/HaboWidget.kt): Native widget · Android app widget extension and update worker. · `android/app/src/main/java/com/pavlenko/Habo/HaboWidget.kt`
- [iOS widget](https://github.com/xpavle00/habo/blob/master/ios/HaboWidget/HaboWidget.swift): Native widget · iOS widget extension used to render habit status. · `ios/HaboWidget/HaboWidget.swift`

### Data & backend

Domain model, repositories, local SQLite persistence, and Supabase backend contract.

- [Repo factory](https://github.com/xpavle00/habo/blob/master/lib/repositories/repository_factory.dart): Repository wiring · Selects and assembles repository implementations. · `lib/repositories/repository_factory.dart`
- [SQLite repos](https://github.com/xpavle00/habo/blob/master/lib/repositories/sqlite_repositories.dart): Local storage · Concrete SQLite-backed repositories for habits, categories, events, and backups. · `lib/repositories/sqlite_repositories.dart`
- [Domain model](https://github.com/xpavle00/habo/blob/master/lib/model/habo_model.dart): Data model · Shared habit, category, settings, and backup data structures. · `lib/model/habo_model.dart`
- [Remote schema](https://github.com/xpavle00/habo/blob/master/supabase/migrations/20260313191900_remote_schema.sql): Supabase SQL · Defines the server-side schema used by sync. · `supabase/migrations/20260313191900_remote_schema.sql`
- [Delete account](https://github.com/xpavle00/habo/blob/master/supabase/functions/delete-account/index.ts): Edge function · Supabase function for remote account deletion. · `supabase/functions/delete-account/index.ts`

## Connections

- Main app → App router: starts · App entry hands control to centralized navigation.
- Main app → Service locator: initializes · Bootstraps shared services and repositories.
- App router → App state: uses · Router depends on app state for flow decisions.
- App router → Onboarding: routes to · Onboarding is one of the major app flows.
- App router → Habits UI: routes to · Main habit workflow entry.
- App router → Statistics: routes to · Statistics flow.
- App router → Settings: routes to · Settings flow.
- App router → Sync setup: routes to · Sync setup and account flow.
- Habits UI → Habits manager: reads/writes · Habit UI delegates business logic to the manager.
- Habits manager → Repo factory: uses · Habit logic accesses persistence through repositories.
- Habits manager → Notifications: updates · Habit changes drive reminder scheduling.
- Habits manager → Widget bridge: publishes · Habit state is exposed to widgets.
- Habits manager → Encryption: protects data · Encrypted data handling is shared across sensitive flows.
- Statistics → Repo factory: reads · Statistics are derived from stored habit/event data.
- Sync setup → Sync manager: orchestrates · Sync UI is driven by the sync manager.
- Sync setup → Backup service: uses · Backup and restore are part of sync setup.
- Sync setup → Biometric gate: gates · Sensitive sync steps require local biometric auth.
- Sync manager → Sync service: coordinates · Manager delegates remote sync operations.
- Sync manager → Encryption: encrypts · Sync payloads are encrypted locally before upload.
- Sync manager → Repo factory: syncs from · Sync reads and writes through repositories.
- Backup service → Encryption: encrypts · Backups are protected before export.
- Backup service → Repo factory: reads/writes · Backup restore and creation use repository data.
- Service locator → Repo factory: provides · Central wiring constructs repository instances.
- Service locator → Sync manager: provides · Shares sync orchestration service.
- Service locator → Backup service: provides · Shares backup service.
- Service locator → Notifications: provides · Shares reminder service.
- Repo factory → SQLite repos: selects · Factory points to SQLite-backed implementations for offline storage.
- SQLite repos → Domain model: persists · Local storage serializes the shared domain model.
- Sync service → Remote schema: targets · Remote sync follows the Supabase schema contract.
- Sync service → Delete account: calls · Remote account lifecycle uses the Supabase edge function.
- Widget bridge → Widget data: formats · Builds the payload consumed by widgets.
- Widget bridge → Android widget: updates · Pushes widget state to the Android extension.
- Widget bridge → iOS widget: updates · Pushes widget state to the iOS extension.
- Biometric gate → Encryption: protects access · Biometric gating guards encrypted flows.