How friesi23/mhabit works
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: providers State layer · localizations.dart Localization · app_sync.dart Sync orchestration · entry.dart App shell
Components 23
Flutter app
Reusable Dart application core: bootstrap, routing, UI, state, and domain logic.
- Main · App bootstrap into Flutter runtime.
lib/main.dart - App shell · Top-level app composition and root view wiring.
lib/entries/app/entry.dart - Feature pages · Habit lists, detail, edit, settings, sync, about, debugger, and error screens.
lib/pages - Shared widgets · Reusable calendars, charts, dialogs, navigation chrome, and form controls.
lib/widgets - State layer · Application state and feature orchestration across pages and services.
lib/providers - Theme system · Theme colors, Material 3 styling, and dynamic color support.
lib/theme/color.dart - Localization · 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 · Habit, record, summary, reminder, sync, settings, export/import, and score models.
lib/models - Scoring · Habit scoring and progress calculations used by charts and summaries.
lib/models/_score/calculator.dart - Habit DB · Main persistent store for habits, records, and sync tables.
lib/storage/db/db_helper.dart - Profile store · 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 · Coordinates sync status, queueing, and app-level sync workflows.
lib/providers/app_sync.dart - Sync tasks · Task and subtask models for local/remote sync operations.
lib/models/_app_sync_tasks/webdav_app_sync_task.dart - WebDAV server · WebDAV connection models, forms, and helpers for remote sync.
lib/models/app_sync_server.dart - Reminders · 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 · Android app shell, flavors, and store packaging assets.
android/app/src/main/AndroidManifest.xml - iOS shell · iOS runner, schemes, and flavor-specific plist/localization setup.
ios/Runner/AppDelegate.swift - macOS shell · macOS runner, schemes, entitlements, and store packaging assets.
macos/Runner/MainFlutterWindow.swift - Windows shell · Windows runner and packaging support for desktop builds.
windows/runner/main.cpp - Linux shell · Linux runner and desktop build integration.
linux/main.cc
Tooling
Build, generation, release automation, and validation support.
- Build scripts · Code generation, icon/asset generation, packaging, and release scripts.
scripts - CI workflows · GitHub Actions workflows for checks, tests, builds, and releases.
.github/workflows - Validation · Repository tests covering models, reminders, storage, utilities, and sync behavior.
test
Connections 25
- 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.