How miguelae9/habit_control works
1. Project shape
- This is a Flutter/Dart cross-platform app with mobile-first UI, but it is scaffolded for Android, iOS, web, Linux, macOS, and Windows.
- The runtime entry points are lib/main.dart, lib/app.dart, and lib/bootstrap.dart, which are the central composition/init layer.
2. Overall architecture
- The codebase is organized as a feature-sliced app with a small shared/core layer:
- lib/core for app-wide infrastructure
- lib/features/* for business modules
- lib/shared for reusable UI components
- Inside each feature, the split is consistent: data → viewmodels → views → widgets.
3. Core infrastructure
- lib/core/database/app_local_db.dart is the persistence foundation; multiple feature DB classes sit on top of it.
- lib/core/router/app_routes.dart handles route definitions and screen navigation.
- lib/core/state/selected_day_view_model.dart holds app-wide date selection state, which is important because several screens operate on “the selected day” rather than only “today”.
- lib/core/theme/app_theme.dart centralizes the dark/dashboard visual style.
- lib/core/utils/date_range.dart and day_key.dart support date-based aggregation and indexing.
4. Feature modules
- The main user-facing modules are:
- Splash: initial loading/transition
- Auth: login/register screens
- Dashboard: the main operational panel
- Input Log: daily metric entry and management
- Habits: habit catalog and per-day habit tracking
- Analytics: historical charts and insights
- Settings: app/user settings and credits
- This suggests a product centered on daily tracking, aggregation, and insight generation rather than simple CRUD.
5. Data layer boundaries
- Several feature-specific data sources are present, and they appear to map cleanly to local storage or service adapters:
- habit_catalog_db.dart, habit_day_db.dart
- metric_definition_db.dart, metric_entry_db.dart
- These DB classes likely isolate persistence per domain object and feed their corresponding viewmodels.
6. External/auxiliary services
- weather_service.dart, daily_insight_service.dart, and stoic_quote_service.dart represent non-local data providers or generated contextual content.
- Architecturally, these services enrich the dashboard and analytics experience with contextual signals such as weather, daily insights, and motivational quotes.
- The presence of android/app/google-services.json and firebase.json indicates Firebase configuration exists in the repo, though the visible feature structure is still primarily local/data-driven.
7. Presentation/state layer
- Each feature has a viewmodels directory, which is the main state-management boundary.
- Viewmodels such as dashboard_view_model.dart, metrics_view_model.dart, habit_day_view_model.dart, and analytics_view_model.dart sit between data services/DBs and the UI.
- This makes the app diagram easy to model as: UI → viewmodel → data/service.
8. Dashboard as the hub
- dashboard_view.dart is the primary landing surface after splash/auth.
- It assembles:
- daily_progress_card.dart
- dashboard_date_selector_card.dart
- insight_card.dart
- metrics_summary_card.dart
- weather_card.dart
- Functionally, the dashboard aggregates the user’s selected day, habit completion, metrics, and contextual data into a single control panel.
9. Habits and daily tracking
- The Habits module is centered on two model concepts: habit.dart and habit_category.dart.
- The UI includes habit_form_dialog.dart and habit_tile.dart, implying users can create/edit habits and mark them per day.
- This module likely drives consistency/streak calculations consumed by analytics and dashboard summaries.
10. Input logging
- The Input Log feature manages arbitrary daily metrics via metric_definition.dart and metric_entry.dart.
- The dialogs create_metric_dialog.dart and edit_metric_dialog.dart show that users can define the tracked metrics themselves, not just use fixed fields.
- This makes the system extensible: the app can track different personal variables over time.
11. Analytics subsystem
- Analytics is a read/summary layer over the stored habit and metric history.
- weekly_bar_chart.dart and stat_card.dart indicate visual reporting, while quote_view_model.dart and stoic_quote_service.dart add a motivational layer.
- The analytics module is where raw daily records become trend views, streaks, and performance summaries.
12. Settings and supporting UI
- Settings includes account/app actions such as password changes and informational screens like credits.
- lib/shared contains reusable components such as top bars, buttons, cards, logos, and the lateral menu.
- The lateral menu is the main cross-feature navigation boundary, linking Dashboard, Input Log, Analytics, and app info screens.
13. Platform layer
- The Flutter app is wrapped by standard native shells:
- Android: MainActivity.kt, Gradle config, manifests, Firebase config
- iOS/macOS: Xcode projects, AppDelegate.swift
- Desktop/web: generated runners and web manifest/index
- These platform folders are mostly thin launch/config layers; the app logic remains in lib/.
14. Primary data flow
- User actions enter through feature views and dialogs.
- Viewmodels transform those actions into DB writes or service calls.
- Data is persisted in local DB abstractions or fetched from auxiliary services.
- Dashboard and Analytics then read the stored state back to render progress, trends, and contextual cards.
- The shared selected-day state ties the system together across modules.
15. What to emphasize in a diagram
- Draw the app around a central Dashboard + shared selected day state.
- Show separate domains for Habits, Input Log, and Analytics feeding from a common local persistence layer.
- Place Auth and Settings as peripheral flows.
- Put shared UI widgets and routing/theme/core utils as cross-cutting infrastructure rather than business features.
Main entry points: app.dart app.dart · analytics_view_model.dart Analytics VM · dashboard_view_model.dart Dashboard VM · app_routes.dart Routes
Components 28
App Shell
Entry points and startup composition
- main.dart · Flutter entrypoint
lib/main.dart - bootstrap.dart · App initialization and dependency setup
lib/bootstrap.dart - app.dart · Top-level app widget and routing composition
lib/app.dart
Core
Cross-cutting app infrastructure
- Routes · Route definitions and screen navigation
lib/core/router/app_routes.dart - Local DB · Shared local database foundation
lib/core/database/app_local_db.dart - Selected Day · App-wide selected-day state
lib/core/state/selected_day_view_model.dart - Theme · Global visual style and theme tokens
lib/core/theme/app_theme.dart - Date Utils · Date range and day key helpers
lib/core/utils/date_range.dart
Shared UI
Reusable presentation components
Features
User-facing feature modules
- Splash · Initial loading and transition screen
lib/features/splash/views/splash_view.dart - Splash VM · Startup loading logic
lib/features/splash/viewmodels/splash_view_model.dart - Auth · Login and registration screens
lib/features/auth/views/login_view.dart - Auth VM · Login and registration state
lib/features/auth/viewmodels/login_view_model.dart - Dashboard · Main operational panel
lib/features/dashboard/views/dashboard_view.dart - Dashboard VM · Dashboard aggregation and coordination
lib/features/dashboard/viewmodels/dashboard_view_model.dart - Context Data · Weather, daily insights, and quote providers
lib/features/dashboard/data/weather_service.dart - Habits · Habit catalog and daily tracking
lib/features/habits/views/habits_view.dart - Habit VM · Habit catalog and per-day habit state
lib/features/habits/viewmodels/habit_day_view_model.dart - Habit DB · Habit catalog and habit-day storage
lib/features/habits/data/habit_catalog_db.dart - Input Log · Daily metric entry and management
lib/features/input_log/views/input_log_view.dart - Metrics VM · Metric definitions and entries state
lib/features/input_log/viewmodels/metrics_view_model.dart - Metric DB · Metric definition and entry storage
lib/features/input_log/data/metric_definition_db.dart - Analytics · Historical charts and insights
lib/features/analytics/views/analytics_view.dart - Analytics VM · Trend and summary calculations
lib/features/analytics/viewmodels/analytics_view_model.dart - Settings · App and account settings
lib/features/settings/views/settings_view.dart - Settings VM · Settings and account actions
lib/features/settings/viewmodels/settings_view_model.dart
Platform
Native and web runner layers
- Platform Shells · Android, iOS, desktop, and web launch layers
android
Connections 32
- main.dart → bootstrap.dart: starts · Entrypoint initializes the app
- bootstrap.dart → app.dart: builds · Bootstrap hands off to top-level app composition
- app.dart → Routes: uses · App wiring depends on route definitions
- app.dart → Theme: uses · Global theme is applied at the app root
- app.dart → Selected Day: provides · Shared selected-day state is exposed to screens
- app.dart → Shared UI: composes · Common widgets are assembled into the shell
- app.dart → Menu: navigates · Primary cross-feature navigation
- app.dart → Splash: routes to · Startup flow begins at splash
- Splash → Splash VM: binds · Splash screen drives loading state
- Splash VM → Routes: advances via · Splash decides next route
- Auth → Auth VM: binds · Login/register UI is powered by auth state
- Auth VM → Routes: redirects via · Auth flow transitions through navigation
- Dashboard → Dashboard VM: binds · Dashboard UI is driven by aggregation state
- Dashboard VM → Selected Day: reads · Dashboard centers on the selected day
- Dashboard VM → Context Data: enriches with · Dashboard pulls contextual data
- Dashboard → Shared UI: uses · Cards and headers are reused in the dashboard
- Habits → Habit VM: binds · Habit UI is driven by habit state
- Habit VM → Habit DB: persists to · Habit changes are stored locally
- Habit VM → Selected Day: reads · Per-day habit tracking follows the selected day
- Input Log → Metrics VM: binds · Metric entry UI is driven by metrics state
- Metrics VM → Metric DB: persists to · Definitions and entries are stored locally
- Metrics VM → Selected Day: reads · Metric entries are organized by selected day
- Analytics → Analytics VM: binds · Charts and summaries are computed by analytics state
- Analytics VM → Habit DB: reads · Analytics summarizes habit history
- Analytics VM → Metric DB: reads · Analytics summarizes metric history
- Analytics VM → Context Data: enriches with · Quotes and other context support insights
- Settings → Settings VM: binds · Settings screen is driven by settings state
- Settings VM → Routes: navigates · Settings links to secondary app screens
- Local DB → Habit DB: backs · Feature databases sit on the shared local DB foundation
- Local DB → Metric DB: backs · Feature databases sit on the shared local DB foundation
- Local DB → Dashboard VM: sources · Dashboard aggregation depends on persisted records
- Platform Shells → main.dart: launches · Native and web shells launch the Flutter app