# friesi23/mhabit architecture

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

- Interactive diagram: https://gitdiagram.com/friesi23/mhabit
- Repository: https://github.com/friesi23/mhabit

## Overview

Table Habit is a cross-platform Flutter application for habit tracking with local-first data storage, optional device sync, reminders, and analytics. The architecture is split into a reusable Dart app core plus thin platform shells for Android, iOS, macOS, Windows, and Linux.

1. **Top-level app structure**
   - `lib/main.dart` boots the Flutter app.
   - `lib/entries/*` defines the app entry composition and top-level root view.
   - The app is built around feature pages rather than a server/client split; almost all business logic lives in the Flutter package itself.

2. **Presentation layer**
   - `lib/pages/*` contains the screen-level UI for habits list/today view, habit detail, habit edit, status change, app settings, sync setup, about/debug, and error states.
   - `lib/widgets/*` holds reusable UI building blocks shared across pages: calendars, charts, pickers, dialogs, progress indicators, navigation chrome, etc.
   - The UI is strongly componentized, with feature pages assembling many small widgets.

3. **State management and feature orchestration**
   - `lib/providers/*` is the main application state layer.
   - These providers coordinate UI state, user preferences, habit forms, sorting/filtering, summary calculations, sync status, reminders, theme/language, and file import/export.
   - The usual flow is: page widget → provider/state change → storage or service call → provider notifies UI.

4. **Domain model**
   - `lib/models/*` defines the app’s core entities: habits, records, summaries, scores, reminders, sync options, app settings, and export/import payloads.
   - Many models are generated/serialized (`*.g.dart`), indicating JSON-friendly data structures used both for persistence and interchange.
   - Scoring and progress logic is separated from the UI in model/helper code, which supports charts and habit analysis.

5. **Local persistence**
   - `lib/storage/db/*` is the SQLite/database layer for persistent habit, record, and sync tables.
   - `lib/storage/profile/*` stores user preferences and app configuration separately from the main habit database.
   - This split suggests a two-store design: one for user/content data, one for settings and UI preferences.

6. **Sync subsystem**
   - `lib/models/_app_sync_tasks/*`, `lib/providers/app_sync.dart`, and `lib/utils/app_sync.dart` form the sync workflow.
   - Sync is centered on **WebDAV** servers (`lib/models/app_sync_server*`, `lib/extensions/webdav_extensions.dart`), with server connection forms and task/status tracking.
   - The app can queue and summarize sync operations, likely pushing/pulling habit data between local storage and remote WebDAV endpoints.

7. **Reminders and notifications**
   - `lib/reminders/*` encapsulates notification channels, payloads, IDs, tap handling, and service logic.
   - `lib/providers/app_reminder.dart` and `lib/providers/app_notify_config.dart` connect reminder configuration to the rest of the app.
   - Platform notifications are used as an infrastructure feature rather than embedded in feature pages.

8. **Charts, summaries, and habit analytics**
   - Habit scores and growth curves are represented in `lib/models/_score/*`, `lib/providers/habit_detail*_chart.dart`, and chart widgets.
   - The app’s main differentiator is its analytical layer: daily status, summary tiles, heatmaps, frequency charts, and score charts are computed from persisted habit/record data.

9. **Internationalization and theme system**
   - Localization is generated from `assets/l10n/*.arb` into `lib/l10n/*`, with platform-specific translated resource files under Android/iOS/macOS.
   - Theme and color customization live in `lib/theme/*` and `lib/providers/app_theme.dart`, including Material 3 and dynamic color support.
   - These are first-class architectural concerns because they affect nearly every screen.

10. **Platform integration**
   - Each platform folder contains the native shell required by Flutter plus store-specific packaging: Android flavors, iOS/macOS schemes, Windows/Linux runners, and Flatpak/DMG/MSIX assets.
   - Android has multiple build flavors (`f_dev`, `f_generic`, `f_store`) and store metadata/fastlane integration.
   - iOS and macOS have matching flavor-specific plist/localization setups, showing that release behavior is environment-dependent.

11. **Build, generation, and release pipeline**
   - `build.yaml`, `scripts/*`, and `.github/workflows/*` automate code generation, asset generation, tests, packaging, and releases.
   - Generated assets/icons/localizations are part of the architecture, not just build trivia, because the app relies on them for UI, translations, and platform branding.
   - Release automation targets multiple distribution channels: GitHub releases, app stores, F-Droid/Flathub, MS Store, TestFlight, and custom package formats.

12. **Testing and external validation**
   - `test/*` covers models, utilities, reminders, storage helpers, and view models, indicating the logic is testable outside the UI.
   - Several tests spin up or target WebDAV server containers, so sync behavior is validated against realistic remote backends.
   - Documentation in `docs/wiki/*` doubles as product and developer architecture reference, especially for sync and scoring behavior.

Overall data flow: user interaction starts in feature pages, moves through providers/state objects, hits either local storage/profile settings or the WebDAV sync/reminder infrastructure, and then feeds back into charts, summaries, and list/detail views. The app is intentionally local-first, with sync and notifications layered on top rather than driving the core model.

Main entry points: [`lib/providers`](https://github.com/friesi23/mhabit/tree/main/lib/providers) (State layer), [`lib/l10n/localizations.dart`](https://github.com/friesi23/mhabit/blob/main/lib/l10n/localizations.dart) (Localization), [`lib/providers/app_sync.dart`](https://github.com/friesi23/mhabit/blob/main/lib/providers/app_sync.dart) (Sync orchestration), [`lib/entries/app/entry.dart`](https://github.com/friesi23/mhabit/blob/main/lib/entries/app/entry.dart) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Flutter app"]
  node_n_main["Main<br/>flutter entry<br/>[main.dart]"]
  node_n_entry["App shell<br/>entry composition<br/>[entry.dart]"]
  node_n_pages["Feature pages<br/>screen UI"]
  node_n_widgets["Shared widgets<br/>ui components"]
  node_n_providers["State layer<br/>providers"]
  node_n_theme{{"Theme system<br/>ui theme<br/>[color.dart]"}}
  node_n_l10n["Localization<br/>generated i18n<br/>[localizations.dart]"]
end

subgraph group_grp_data["Data layer"]
  node_n_models[("Domain models<br/>entities")]
  node_n_score{{"Scoring<br/>analytics logic<br/>[calculator.dart]"}}
  node_n_db[("Habit DB<br/>sqlite storage<br/>[db_helper.dart]")]
  node_n_profile[("Profile store<br/>prefs storage")]
end

subgraph group_grp_sync["Sync and reminders"]
  node_n_syncprov["Sync orchestration<br/>sync provider<br/>[app_sync.dart]"]
  node_n_synctasks{{"Sync tasks<br/>sync workflow"}}
  node_n_webdav[("WebDAV server<br/>remote endpoint")]
  node_n_reminders["Reminders<br/>notifications"]
end

subgraph group_grp_platform["Platform shells"]
  node_n_android["Android shell<br/>native runner"]
  node_n_ios["iOS shell<br/>native runner<br/>[AppDelegate.swift]"]
  node_n_macos["macOS shell<br/>native runner"]
  node_n_windows["Windows shell<br/>native runner<br/>[main.cpp]"]
  node_n_linux["Linux shell<br/>native runner<br/>[main.cc]"]
end

subgraph group_grp_tooling["Tooling"]
  node_n_build["Build scripts<br/>automation"]
  node_n_ci["CI workflows<br/>automation<br/>[workflows]"]
  node_n_tests["Validation<br/>tests"]
end

node_n_main -->|"boots"| node_n_entry
node_n_entry -->|"composes"| node_n_pages
node_n_entry -->|"injects"| node_n_providers
node_n_pages -->|"assembles"| node_n_widgets
node_n_pages -->|"reads state"| node_n_providers
node_n_providers -->|"uses"| node_n_models
node_n_models -->|"derives"| node_n_score
node_n_providers -->|"persists"| node_n_db
node_n_providers -->|"persists"| node_n_profile
node_n_providers -->|"configures"| node_n_theme
node_n_providers -->|"localizes"| node_n_l10n
node_n_providers -->|"coordinates"| node_n_syncprov
node_n_syncprov -->|"queues"| node_n_synctasks
node_n_syncprov -->|"connects"| node_n_webdav
node_n_providers -->|"schedules"| node_n_reminders
node_n_reminders -->|"reads config"| node_n_profile
node_n_widgets -->|"visualizes"| node_n_score
node_n_widgets -->|"labels"| node_n_l10n
node_n_android -.->|"packages"| node_n_l10n
node_n_ios -.->|"packages"| node_n_l10n
node_n_macos -.->|"packages"| node_n_l10n
node_n_build -.->|"generates"| node_n_l10n
node_n_build -.->|"drives"| node_n_ci
node_n_tests -.->|"validates"| node_n_models
node_n_tests -.->|"validates"| node_n_syncprov

click node_n_main "https://github.com/friesi23/mhabit/blob/main/lib/main.dart"
click node_n_entry "https://github.com/friesi23/mhabit/blob/main/lib/entries/app/entry.dart"
click node_n_pages "https://github.com/friesi23/mhabit/tree/main/lib/pages"
click node_n_widgets "https://github.com/friesi23/mhabit/tree/main/lib/widgets"
click node_n_providers "https://github.com/friesi23/mhabit/tree/main/lib/providers"
click node_n_models "https://github.com/friesi23/mhabit/tree/main/lib/models"
click node_n_score "https://github.com/friesi23/mhabit/blob/main/lib/models/_score/calculator.dart"
click node_n_db "https://github.com/friesi23/mhabit/blob/main/lib/storage/db/db_helper.dart"
click node_n_profile "https://github.com/friesi23/mhabit/blob/main/lib/storage/profile/profile_helper.dart"
click node_n_syncprov "https://github.com/friesi23/mhabit/blob/main/lib/providers/app_sync.dart"
click node_n_synctasks "https://github.com/friesi23/mhabit/blob/main/lib/models/_app_sync_tasks/webdav_app_sync_task.dart"
click node_n_webdav "https://github.com/friesi23/mhabit/blob/main/lib/models/app_sync_server.dart"
click node_n_reminders "https://github.com/friesi23/mhabit/blob/main/lib/reminders/notification_service.dart"
click node_n_theme "https://github.com/friesi23/mhabit/blob/main/lib/theme/color.dart"
click node_n_l10n "https://github.com/friesi23/mhabit/blob/main/lib/l10n/localizations.dart"
click node_n_android "https://github.com/friesi23/mhabit/blob/main/android/app/src/main/AndroidManifest.xml"
click node_n_ios "https://github.com/friesi23/mhabit/blob/main/ios/Runner/AppDelegate.swift"
click node_n_macos "https://github.com/friesi23/mhabit/blob/main/macos/Runner/MainFlutterWindow.swift"
click node_n_windows "https://github.com/friesi23/mhabit/blob/main/windows/runner/main.cpp"
click node_n_linux "https://github.com/friesi23/mhabit/blob/main/linux/main.cc"
click node_n_build "https://github.com/friesi23/mhabit/tree/main/scripts"
click node_n_ci "https://github.com/friesi23/mhabit/blob/main/.github/workflows"
click node_n_tests "https://github.com/friesi23/mhabit/tree/main/test"

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_n_main,node_n_entry,node_n_pages,node_n_widgets,node_n_providers,node_n_theme,node_n_l10n toneBlue
class node_n_models,node_n_score,node_n_db,node_n_profile toneAmber
class node_n_syncprov,node_n_synctasks,node_n_webdav,node_n_reminders toneMint
class node_n_android,node_n_ios,node_n_macos,node_n_windows,node_n_linux toneRose
class node_n_build,node_n_ci,node_n_tests toneIndigo
```

## Components

### Flutter app

Reusable Dart application core: bootstrap, routing, UI, state, and domain logic.

- [Main](https://github.com/friesi23/mhabit/blob/main/lib/main.dart): flutter entry · App bootstrap into Flutter runtime. · `lib/main.dart`
- [App shell](https://github.com/friesi23/mhabit/blob/main/lib/entries/app/entry.dart): entry composition · Top-level app composition and root view wiring. · `lib/entries/app/entry.dart`
- [Feature pages](https://github.com/friesi23/mhabit/tree/main/lib/pages): screen UI · Habit lists, detail, edit, settings, sync, about, debugger, and error screens. · `lib/pages`
- [Shared widgets](https://github.com/friesi23/mhabit/tree/main/lib/widgets): ui components · Reusable calendars, charts, dialogs, navigation chrome, and form controls. · `lib/widgets`
- [State layer](https://github.com/friesi23/mhabit/tree/main/lib/providers): providers · Application state and feature orchestration across pages and services. · `lib/providers`
- [Theme system](https://github.com/friesi23/mhabit/blob/main/lib/theme/color.dart): ui theme · Theme colors, Material 3 styling, and dynamic color support. · `lib/theme/color.dart`
- [Localization](https://github.com/friesi23/mhabit/blob/main/lib/l10n/localizations.dart): generated i18n · Generated localizations and language resources used across the UI. · `lib/l10n/localizations.dart`

### Data layer

Local persistence, profile storage, models, and scoring utilities.

- [Domain models](https://github.com/friesi23/mhabit/tree/main/lib/models): entities · Habit, record, summary, reminder, sync, settings, export/import, and score models. · `lib/models`
- [Scoring](https://github.com/friesi23/mhabit/blob/main/lib/models/_score/calculator.dart): analytics logic · Habit scoring and progress calculations used by charts and summaries. · `lib/models/_score/calculator.dart`
- [Habit DB](https://github.com/friesi23/mhabit/blob/main/lib/storage/db/db_helper.dart): sqlite storage · Main persistent store for habits, records, and sync tables. · `lib/storage/db/db_helper.dart`
- [Profile store](https://github.com/friesi23/mhabit/blob/main/lib/storage/profile/profile_helper.dart): prefs storage · Separate persistence for app settings, UI preferences, and launch state. · `lib/storage/profile/profile_helper.dart`

### Sync and reminders

Optional remote sync and notification infrastructure layered on top of local-first data.

- [Sync orchestration](https://github.com/friesi23/mhabit/blob/main/lib/providers/app_sync.dart): sync provider · Coordinates sync status, queueing, and app-level sync workflows. · `lib/providers/app_sync.dart`
- [Sync tasks](https://github.com/friesi23/mhabit/blob/main/lib/models/_app_sync_tasks/webdav_app_sync_task.dart): sync workflow · Task and subtask models for local/remote sync operations. · `lib/models/_app_sync_tasks/webdav_app_sync_task.dart`
- [WebDAV server](https://github.com/friesi23/mhabit/blob/main/lib/models/app_sync_server.dart): remote endpoint · WebDAV connection models, forms, and helpers for remote sync. · `lib/models/app_sync_server.dart`
- [Reminders](https://github.com/friesi23/mhabit/blob/main/lib/reminders/notification_service.dart): notifications · Notification service, payloads, IDs, and tap handling. · `lib/reminders/notification_service.dart`

### Platform shells

Native runners, packaging, localization, and store-specific release assets.

- [Android shell](https://github.com/friesi23/mhabit/blob/main/android/app/src/main/AndroidManifest.xml): native runner · Android app shell, flavors, and store packaging assets. · `android/app/src/main/AndroidManifest.xml`
- [iOS shell](https://github.com/friesi23/mhabit/blob/main/ios/Runner/AppDelegate.swift): native runner · iOS runner, schemes, and flavor-specific plist/localization setup. · `ios/Runner/AppDelegate.swift`
- [macOS shell](https://github.com/friesi23/mhabit/blob/main/macos/Runner/MainFlutterWindow.swift): native runner · macOS runner, schemes, entitlements, and store packaging assets. · `macos/Runner/MainFlutterWindow.swift`
- [Windows shell](https://github.com/friesi23/mhabit/blob/main/windows/runner/main.cpp): native runner · Windows runner and packaging support for desktop builds. · `windows/runner/main.cpp`
- [Linux shell](https://github.com/friesi23/mhabit/blob/main/linux/main.cc): native runner · Linux runner and desktop build integration. · `linux/main.cc`

### Tooling

Build, generation, release automation, and validation support.

- [Build scripts](https://github.com/friesi23/mhabit/tree/main/scripts): automation · Code generation, icon/asset generation, packaging, and release scripts. · `scripts`
- [CI workflows](https://github.com/friesi23/mhabit/blob/main/.github/workflows): automation · GitHub Actions workflows for checks, tests, builds, and releases. · `.github/workflows`
- [Validation](https://github.com/friesi23/mhabit/tree/main/test): tests · Repository tests covering models, reminders, storage, utilities, and sync behavior. · `test`

## Connections

- Main → App shell: boots · Main entry initializes the Flutter app shell.
- App shell → Feature pages: composes · Root composition wires feature pages into navigation.
- App shell → State layer: injects · App shell installs the global providers/state tree.
- Feature pages → Shared widgets: assembles · Pages are built from shared reusable widgets.
- Feature pages → State layer: reads state · Screens react to provider updates and dispatch actions.
- State layer → Domain models: uses · Providers coordinate domain objects and view state.
- Domain models → Scoring: derives · Scores and progress are computed from persisted habit data.
- State layer → Habit DB: persists · Core app state writes to the local habit database.
- State layer → Profile store: persists · Preferences and UI settings go to the profile store.
- State layer → Theme system: configures · Theme state drives color and appearance across the app.
- State layer → Localization: localizes · Provider-driven language changes feed generated localizations.
- State layer → Sync orchestration: coordinates · App providers delegate sync orchestration.
- Sync orchestration → Sync tasks: queues · Sync provider manages task and status models.
- Sync orchestration → WebDAV server: connects · Sync flow targets WebDAV server configuration and endpoints.
- State layer → Reminders: schedules · Reminder configuration is translated into notifications.
- Reminders → Profile store: reads config · Reminder settings are stored in profile preferences.
- Shared widgets → Scoring: visualizes · Charts and summaries render score/progress calculations.
- Shared widgets → Localization: labels · Shared UI consumes generated localized strings.
- Android shell → Localization: packages · Android flavors include translated resources and store assets.
- iOS shell → Localization: packages · iOS runner includes localized InfoPlist resources.
- macOS shell → Localization: packages · macOS runner includes localized InfoPlist resources.
- Build scripts → Localization: generates · Scripts and build config generate localization artifacts.
- Build scripts → CI workflows: drives · Automation scripts are executed by CI workflows.
- Validation → Domain models: validates · Tests exercise models, scoring, and sync tasks.
- Validation → Sync orchestration: validates · Tests cover sync and WebDAV behavior with realistic backends.
