# miguelae9/habit_control architecture

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

- Interactive diagram: https://gitdiagram.com/miguelae9/habit_control
- Repository: https://github.com/miguelae9/habit_control

## Overview

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: [`lib/app.dart`](https://github.com/miguelae9/habit_control/blob/main/lib/app.dart) (app.dart), [`lib/features/analytics/viewmodels/analytics_view_model.dart`](https://github.com/miguelae9/habit_control/blob/main/lib/features/analytics/viewmodels/analytics_view_model.dart) (Analytics VM), [`lib/features/dashboard/viewmodels/dashboard_view_model.dart`](https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/viewmodels/dashboard_view_model.dart) (Dashboard VM), [`lib/core/router/app_routes.dart`](https://github.com/miguelae9/habit_control/blob/main/lib/core/router/app_routes.dart) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App Shell"]
  node_main_dart["main.dart<br/>entrypoint<br/>[main.dart]"]
  node_bootstrap_dart["bootstrap.dart<br/>startup<br/>[bootstrap.dart]"]
  node_app_dart["app.dart<br/>composition<br/>[app.dart]"]
end

subgraph group_core["Core"]
  node_app_routes["Routes<br/>navigation<br/>[app_routes.dart]"]
  node_app_local_db[("Local DB<br/>persistence<br/>[app_local_db.dart]")]
  node_selected_day_vm(("Selected Day<br/>state"))
  node_app_theme["Theme<br/>design-system<br/>[app_theme.dart]"]
  node_date_utils["Date Utils<br/>[date_range.dart]"]
end

subgraph group_shared["Shared UI"]
  node_shared_ui["Shared UI<br/>components"]
  node_lateral_menu["Menu<br/>navigation-ui<br/>[lateral_menu.dart]"]
end

subgraph group_features["Features"]
  node_splash_view["Splash<br/>screen<br/>[splash_view.dart]"]
  node_splash_vm["Splash VM<br/>viewmodel"]
  node_auth_views["Auth<br/>screen-group<br/>[login_view.dart]"]
  node_auth_vm["Auth VM<br/>viewmodel"]
  node_dashboard_view["Dashboard<br/>screen"]
  node_dashboard_vm["Dashboard VM<br/>viewmodel"]
  node_context_services["Context Data<br/>service-layer"]
  node_habits_view["Habits<br/>screen<br/>[habits_view.dart]"]
  node_habit_vm["Habit VM<br/>viewmodel"]
  node_habit_db[("Habit DB<br/>persistence")]
  node_input_log_view["Input Log<br/>screen"]
  node_metrics_vm["Metrics VM<br/>viewmodel"]
  node_metric_db[("Metric DB<br/>persistence")]
  node_analytics_view["Analytics<br/>screen"]
  node_analytics_vm["Analytics VM<br/>viewmodel"]
  node_settings_view["Settings<br/>screen<br/>[settings_view.dart]"]
  node_settings_vm["Settings VM<br/>viewmodel"]
end

subgraph group_platform["Platform"]
  node_platform_shells["Platform Shells<br/>native-runners"]
end

node_main_dart -->|"starts"| node_bootstrap_dart
node_bootstrap_dart -->|"builds"| node_app_dart
node_app_dart -->|"uses"| node_app_routes
node_app_dart -->|"uses"| node_app_theme
node_app_dart -->|"provides"| node_selected_day_vm
node_app_dart -->|"composes"| node_shared_ui
node_app_dart -->|"navigates"| node_lateral_menu
node_app_dart -->|"routes to"| node_splash_view
node_splash_view -->|"binds"| node_splash_vm
node_splash_vm -->|"advances via"| node_app_routes
node_auth_views -->|"binds"| node_auth_vm
node_auth_vm -->|"redirects via"| node_app_routes
node_dashboard_view -->|"binds"| node_dashboard_vm
node_dashboard_vm -->|"reads"| node_selected_day_vm
node_dashboard_vm -->|"enriches with"| node_context_services
node_dashboard_view -->|"uses"| node_shared_ui
node_habits_view -->|"binds"| node_habit_vm
node_habit_vm -->|"persists to"| node_habit_db
node_habit_vm -->|"reads"| node_selected_day_vm
node_input_log_view -->|"binds"| node_metrics_vm
node_metrics_vm -->|"persists to"| node_metric_db
node_metrics_vm -->|"reads"| node_selected_day_vm
node_analytics_view -->|"binds"| node_analytics_vm
node_analytics_vm -->|"reads"| node_habit_db
node_analytics_vm -->|"reads"| node_metric_db
node_analytics_vm -->|"enriches with"| node_context_services
node_settings_view -->|"binds"| node_settings_vm
node_settings_vm -->|"navigates"| node_app_routes
node_app_local_db -->|"backs"| node_habit_db
node_app_local_db -->|"backs"| node_metric_db
node_app_local_db -->|"sources"| node_dashboard_vm
node_platform_shells -->|"launches"| node_main_dart

click node_main_dart "https://github.com/miguelae9/habit_control/blob/main/lib/main.dart"
click node_bootstrap_dart "https://github.com/miguelae9/habit_control/blob/main/lib/bootstrap.dart"
click node_app_dart "https://github.com/miguelae9/habit_control/blob/main/lib/app.dart"
click node_app_routes "https://github.com/miguelae9/habit_control/blob/main/lib/core/router/app_routes.dart"
click node_app_local_db "https://github.com/miguelae9/habit_control/blob/main/lib/core/database/app_local_db.dart"
click node_selected_day_vm "https://github.com/miguelae9/habit_control/blob/main/lib/core/state/selected_day_view_model.dart"
click node_app_theme "https://github.com/miguelae9/habit_control/blob/main/lib/core/theme/app_theme.dart"
click node_date_utils "https://github.com/miguelae9/habit_control/blob/main/lib/core/utils/date_range.dart"
click node_shared_ui "https://github.com/miguelae9/habit_control/tree/main/lib/shared"
click node_lateral_menu "https://github.com/miguelae9/habit_control/blob/main/lib/shared/lateral_menu/lateral_menu.dart"
click node_splash_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/splash/views/splash_view.dart"
click node_splash_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/splash/viewmodels/splash_view_model.dart"
click node_auth_views "https://github.com/miguelae9/habit_control/blob/main/lib/features/auth/views/login_view.dart"
click node_auth_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/auth/viewmodels/login_view_model.dart"
click node_dashboard_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/views/dashboard_view.dart"
click node_dashboard_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/viewmodels/dashboard_view_model.dart"
click node_context_services "https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/data/weather_service.dart"
click node_habits_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/views/habits_view.dart"
click node_habit_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/viewmodels/habit_day_view_model.dart"
click node_habit_db "https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/data/habit_catalog_db.dart"
click node_input_log_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/views/input_log_view.dart"
click node_metrics_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/viewmodels/metrics_view_model.dart"
click node_metric_db "https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/data/metric_definition_db.dart"
click node_analytics_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/analytics/views/analytics_view.dart"
click node_analytics_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/analytics/viewmodels/analytics_view_model.dart"
click node_settings_view "https://github.com/miguelae9/habit_control/blob/main/lib/features/settings/views/settings_view.dart"
click node_settings_vm "https://github.com/miguelae9/habit_control/blob/main/lib/features/settings/viewmodels/settings_view_model.dart"
click node_platform_shells "https://github.com/miguelae9/habit_control/tree/main/android"

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_main_dart,node_bootstrap_dart,node_app_dart toneBlue
class node_app_routes,node_app_local_db,node_selected_day_vm,node_app_theme,node_date_utils toneAmber
class node_shared_ui,node_lateral_menu toneMint
class node_splash_view,node_splash_vm,node_auth_views,node_auth_vm,node_dashboard_view,node_dashboard_vm,node_context_services,node_habits_view,node_habit_vm,node_habit_db,node_input_log_view,node_metrics_vm,node_metric_db,node_analytics_view,node_analytics_vm,node_settings_view,node_settings_vm toneRose
class node_platform_shells toneIndigo
```

## Components

### App Shell

Entry points and startup composition

- [main.dart](https://github.com/miguelae9/habit_control/blob/main/lib/main.dart): entrypoint · Flutter entrypoint · `lib/main.dart`
- [bootstrap.dart](https://github.com/miguelae9/habit_control/blob/main/lib/bootstrap.dart): startup · App initialization and dependency setup · `lib/bootstrap.dart`
- [app.dart](https://github.com/miguelae9/habit_control/blob/main/lib/app.dart): composition · Top-level app widget and routing composition · `lib/app.dart`

### Core

Cross-cutting app infrastructure

- [Routes](https://github.com/miguelae9/habit_control/blob/main/lib/core/router/app_routes.dart): navigation · Route definitions and screen navigation · `lib/core/router/app_routes.dart`
- [Local DB](https://github.com/miguelae9/habit_control/blob/main/lib/core/database/app_local_db.dart): persistence · Shared local database foundation · `lib/core/database/app_local_db.dart`
- [Selected Day](https://github.com/miguelae9/habit_control/blob/main/lib/core/state/selected_day_view_model.dart): state · App-wide selected-day state · `lib/core/state/selected_day_view_model.dart`
- [Theme](https://github.com/miguelae9/habit_control/blob/main/lib/core/theme/app_theme.dart): design-system · Global visual style and theme tokens · `lib/core/theme/app_theme.dart`
- [Date Utils](https://github.com/miguelae9/habit_control/blob/main/lib/core/utils/date_range.dart): utility · Date range and day key helpers · `lib/core/utils/date_range.dart`

### Shared UI

Reusable presentation components

- [Shared UI](https://github.com/miguelae9/habit_control/tree/main/lib/shared): components · Common cards, buttons, headers, and logo · `lib/shared`
- [Menu](https://github.com/miguelae9/habit_control/blob/main/lib/shared/lateral_menu/lateral_menu.dart): navigation-ui · Cross-feature navigation drawer · `lib/shared/lateral_menu/lateral_menu.dart`

### Features

User-facing feature modules

- [Splash](https://github.com/miguelae9/habit_control/blob/main/lib/features/splash/views/splash_view.dart): screen · Initial loading and transition screen · `lib/features/splash/views/splash_view.dart`
- [Splash VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/splash/viewmodels/splash_view_model.dart): viewmodel · Startup loading logic · `lib/features/splash/viewmodels/splash_view_model.dart`
- [Auth](https://github.com/miguelae9/habit_control/blob/main/lib/features/auth/views/login_view.dart): screen-group · Login and registration screens · `lib/features/auth/views/login_view.dart`
- [Auth VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/auth/viewmodels/login_view_model.dart): viewmodel · Login and registration state · `lib/features/auth/viewmodels/login_view_model.dart`
- [Dashboard](https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/views/dashboard_view.dart): screen · Main operational panel · `lib/features/dashboard/views/dashboard_view.dart`
- [Dashboard VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/viewmodels/dashboard_view_model.dart): viewmodel · Dashboard aggregation and coordination · `lib/features/dashboard/viewmodels/dashboard_view_model.dart`
- [Context Data](https://github.com/miguelae9/habit_control/blob/main/lib/features/dashboard/data/weather_service.dart): service-layer · Weather, daily insights, and quote providers · `lib/features/dashboard/data/weather_service.dart`
- [Habits](https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/views/habits_view.dart): screen · Habit catalog and daily tracking · `lib/features/habits/views/habits_view.dart`
- [Habit VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/viewmodels/habit_day_view_model.dart): viewmodel · Habit catalog and per-day habit state · `lib/features/habits/viewmodels/habit_day_view_model.dart`
- [Habit DB](https://github.com/miguelae9/habit_control/blob/main/lib/features/habits/data/habit_catalog_db.dart): persistence · Habit catalog and habit-day storage · `lib/features/habits/data/habit_catalog_db.dart`
- [Input Log](https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/views/input_log_view.dart): screen · Daily metric entry and management · `lib/features/input_log/views/input_log_view.dart`
- [Metrics VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/viewmodels/metrics_view_model.dart): viewmodel · Metric definitions and entries state · `lib/features/input_log/viewmodels/metrics_view_model.dart`
- [Metric DB](https://github.com/miguelae9/habit_control/blob/main/lib/features/input_log/data/metric_definition_db.dart): persistence · Metric definition and entry storage · `lib/features/input_log/data/metric_definition_db.dart`
- [Analytics](https://github.com/miguelae9/habit_control/blob/main/lib/features/analytics/views/analytics_view.dart): screen · Historical charts and insights · `lib/features/analytics/views/analytics_view.dart`
- [Analytics VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/analytics/viewmodels/analytics_view_model.dart): viewmodel · Trend and summary calculations · `lib/features/analytics/viewmodels/analytics_view_model.dart`
- [Settings](https://github.com/miguelae9/habit_control/blob/main/lib/features/settings/views/settings_view.dart): screen · App and account settings · `lib/features/settings/views/settings_view.dart`
- [Settings VM](https://github.com/miguelae9/habit_control/blob/main/lib/features/settings/viewmodels/settings_view_model.dart): viewmodel · Settings and account actions · `lib/features/settings/viewmodels/settings_view_model.dart`

### Platform

Native and web runner layers

- [Platform Shells](https://github.com/miguelae9/habit_control/tree/main/android): native-runners · Android, iOS, desktop, and web launch layers · `android`

## Connections

- 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
