# enforcerhuman/health_sync_dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/enforcerhuman/health_sync_dashboard
- Repository: https://github.com/enforcerhuman/health_sync_dashboard

## Overview

This repository is a Flutter cross-platform app built around a single major feature: a health dashboard that shows step activity and refreshes it from platform health APIs. The codebase uses a layered, feature-first architecture with clear separation between UI, business logic, persistence, and platform integration.

Main architectural boundaries

1. App bootstrap and composition root
- `lib/main.dart` is the app entry point.
- `lib/injection_container.dart` wires dependencies through `get_it`.
- Startup is responsible for initializing local storage (`Hive`) and registering the objects needed by the steps feature before the UI is built.

2. Shared infrastructure
- `lib/core/` contains cross-cutting concerns used by the app:
  - constants for colors, gradients, and strings
  - error/exceptions types
  - health service abstraction
  - Hive initialization and box access
  - utility helpers such as date formatting and permission handling
- `lib/common/` contains reusable UI pieces and theme definitions:
  - app theme
  - shared widgets like the app bar, text component, and bottom navigation bar

3. Feature module: health dashboard
- `lib/features/health_dashboard/` is the main functional module.
- It follows a clean layering model:
  - `presentation/` for screens, widgets, and state management
  - `domain/` for use cases and repository contracts
  - `data/` for concrete data sources, models, and repository implementation

Primary runtime flow for steps

The step data flow is the core architecture of the app:

1. App starts.
2. Hive is initialized and dependency injection is configured.
3. `StepsBloc` is created by the presentation layer.
4. The bloc triggers a cached-data path first.
5. Cached step history is read from Hive through the local data source.
6. The UI renders immediately with cached values if available.
7. After that, live step polling begins through the health platform integration.
8. Fresh step values are emitted back to the UI.
9. New values are persisted again into Hive for next launch.

Layer-by-layer responsibilities

Presentation layer
- Located under `lib/features/health_dashboard/presentation/`.
- Contains:
  - `screens/home_screen.dart`
  - `bloc/steps_bloc/` with events, states, and bloc logic
  - widgets grouped by dashboard sections: steps, activity, heart rate, sleep, quick log
- `flutter_bloc` drives the state updates and rebuilds.
- This layer is purely about rendering and responding to state changes.

Domain layer
- Located under `lib/features/health_dashboard/domain/`.
- Contains:
  - repository interface for steps
  - use cases such as:
    - fetch latest steps
    - get cached steps
    - start live step stream
    - stop live updates
- This layer defines the application logic and the contract for data access without knowing where the data comes from.

Data layer
- Located under `lib/features/health_dashboard/data/`.
- Contains:
  - remote data source for real device health data
  - local data source for cached step history
  - repository implementation that connects both
  - Hive model for persisted step history, including generated adapter code
- This layer is where the app integrates with the actual persistence and health APIs.

External/system dependencies that shape the architecture

- Health data on Android comes from `Health Connect`.
- Health data on iOS comes from `HealthKit`.
- The Flutter `health` package is the bridge to those platform APIs.
- `Hive` and `hive_flutter` are used for local persistence of step history.
- `syncfusion_flutter_gauges` and `syncfusion_flutter_charts` appear to support the dashboard visualization layer.
- `bloc` and `flutter_bloc` provide state management.
- `get_it` provides service location / dependency injection.

Important platform boundaries

- The Flutter app itself is cross-platform, but real health data is platform-specific.
- Android and iOS each have native project folders and manifests/plists to support permissions and platform integration.
- Health access is expected on real devices, especially on iOS where HealthKit is not reliably testable in a simulator.
- The native folders (`android/`, `ios/`, etc.) are mostly platform shells and configuration around the Flutter app; the app’s actual business architecture lives in `lib/`.

UI composition

The dashboard UI is assembled from reusable widgets:
- steps display widget
- activity card / section
- heart rate card
- sleep card / item
- quick log
- shared app bar and bottom navigation

This means the visible screen is a composition of multiple dashboard sections, but the dynamic data path is centered on the steps subsystem.

Key architectural takeaway

The repository is organized as a clean, feature-based Flutter app with a single important data pipeline:
presentation UI -> bloc -> use cases -> repository interface -> repository implementation -> local Hive cache and remote health data source -> platform health services.

That pipeline is the main thing to show in an architecture diagram, because it explains both how the UI gets its data and how the app persists and refreshes health information across launches.

Main entry points: [`lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart`](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart) (Health Source), [`lib/injection_container.dart`](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/injection_container.dart) (DI Setup), [`lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart`](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart) (Steps Bloc), [`lib/features/health_dashboard/data/repositories/steps_repository_impl.dart`](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/repositories/steps_repository_impl.dart) (Repo Impl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "App Shell"
  main["Main<br/>flutter entrypoint<br/>[main.dart]"]
  di["DI Setup<br/>service locator"]
end

subgraph "Shared Core"
  theme["Theme<br/>[app_theme.dart]"]
  widgets["Shared Widgets<br/>ui kit"]
  constants["Constants"]
  errors["Errors<br/>error types"]
  health_service["Health Service<br/>platform abstraction"]
  hive_init["Hive Init<br/>storage bootstrap<br/>[hive_init.dart]"]
  hive_box["Hive Box<br/>storage access<br/>[hive_box.dart]"]
  permission["Permissions"]
end

subgraph "Health Dashboard"
  home_screen["Home Screen<br/>presentation screen<br/>[home_screen.dart]"]
  steps_bloc["Steps Bloc<br/>state management<br/>[steps_bloc.dart]"]
  usecases["Use Cases<br/>domain logic"]
  steps_repo["Steps Repo<br/>repository contract"]
  steps_impl["Repo Impl<br/>data repository"]
  local_ds["Local Cache<br/>local datasource"]
  remote_ds["Health Source<br/>remote datasource"]
  steps_model["Step Model<br/>persistence model"]
end

subgraph "Platform Hosts"
  android["Android Host<br/>native shell"]
  ios["iOS Host<br/>native shell<br/>[AppDelegate.swift]"]
end

main -->|"bootstraps"| di
main -->|"initializes"| hive_init
di -->|"registers"| steps_repo
di -->|"binds"| steps_impl
di -->|"provides"| health_service
di -->|"provides"| hive_box
home_screen -->|"observes"| steps_bloc
steps_bloc -->|"invokes"| usecases
usecases -->|"depends on"| steps_repo
steps_impl -->|"reads/writes"| local_ds
steps_impl -->|"fetches"| remote_ds
local_ds -->|"uses"| hive_box
local_ds -->|"persists"| steps_model
remote_ds -->|"uses"| health_service
remote_ds -->|"checks"| permission
steps_impl -->|"stores"| steps_model
steps_bloc -->|"loads cache"| local_ds
steps_bloc -->|"starts live"| remote_ds
steps_bloc -->|"refreshes"| steps_impl
android -.->|"supports"| remote_ds
ios -.->|"supports"| remote_ds
theme -.->|"styles"| widgets
constants -.->|"feeds"| widgets

click main "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/main.dart"
click di "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/injection_container.dart"
click theme "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/common/theme/app_theme.dart"
click widgets "https://github.com/enforcerhuman/health_sync_dashboard/tree/main/lib/common/widgets"
click constants "https://github.com/enforcerhuman/health_sync_dashboard/tree/main/lib/core/constants"
click errors "https://github.com/enforcerhuman/health_sync_dashboard/tree/main/lib/core/error"
click health_service "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/core/services/health_services.dart"
click hive_init "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/core/storage/hive_init.dart"
click hive_box "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/core/storage/hive_box.dart"
click permission "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/core/utils/permission_helper.dart"
click home_screen "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/presentation/screens/home_screen.dart"
click steps_bloc "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart"
click usecases "https://github.com/enforcerhuman/health_sync_dashboard/tree/main/lib/features/health_dashboard/domain/usecases"
click steps_repo "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/domain/repositories/steps_repository.dart"
click steps_impl "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/data/repositories/steps_repository_impl.dart"
click local_ds "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/data/datasources/steps_local_data_source.dart"
click remote_ds "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart"
click steps_model "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/lib/features/health_dashboard/data/models/steps_history_model.dart"
click android "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/android/app/src/main/AndroidManifest.xml"
click ios "https://github.com/enforcerhuman/health_sync_dashboard/blob/main/ios/Runner/AppDelegate.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 main,di toneBlue
class theme,widgets,constants,errors,health_service,hive_init,hive_box,permission toneAmber
class home_screen,steps_bloc,usecases,steps_repo,steps_impl,local_ds,remote_ds,steps_model toneMint
class android,ios toneRose
```

## Components

### App Shell

Bootstrap and platform entrypoints.

- [Main](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/main.dart): flutter entrypoint · App startup and composition root entry. · `lib/main.dart`
- [DI Setup](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/injection_container.dart): service locator · Registers app dependencies and feature wiring. · `lib/injection_container.dart`

### Shared Core

Cross-cutting services, storage, and UI primitives.

- [Theme](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/common/theme/app_theme.dart): ui theme · Shared app styling and visual theme definitions. · `lib/common/theme/app_theme.dart`
- [Shared Widgets](https://github.com/enforcerhuman/health_sync_dashboard/tree/HEAD/lib/common/widgets): ui kit · Reusable app chrome and text primitives. · `lib/common/widgets`
- [Constants](https://github.com/enforcerhuman/health_sync_dashboard/tree/HEAD/lib/core/constants): ui constants · Colors, gradients, strings, and progress palettes. · `lib/core/constants`
- [Errors](https://github.com/enforcerhuman/health_sync_dashboard/tree/HEAD/lib/core/error): error types · Application exceptions and failure models. · `lib/core/error`
- [Health Service](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/core/services/health_services.dart): platform abstraction · Abstraction over device health APIs. · `lib/core/services/health_services.dart`
- [Hive Init](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/core/storage/hive_init.dart): storage bootstrap · Initializes local persistence and Hive access. · `lib/core/storage/hive_init.dart`
- [Hive Box](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/core/storage/hive_box.dart): storage access · Box helpers and persistence access point. · `lib/core/storage/hive_box.dart`
- [Permissions](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/core/utils/permission_helper.dart): utility · Permission handling helpers for device access. · `lib/core/utils/permission_helper.dart`

### Health Dashboard

Main feature implemented with presentation, domain, and data layers.

- [Home Screen](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/presentation/screens/home_screen.dart): presentation screen · Dashboard shell that composes the feature UI. · `lib/features/health_dashboard/presentation/screens/home_screen.dart`
- [Steps Bloc](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart): state management · Coordinates cached reads, live polling, and UI state. · `lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart`
- [Use Cases](https://github.com/enforcerhuman/health_sync_dashboard/tree/HEAD/lib/features/health_dashboard/domain/usecases): domain logic · Application actions for cached fetch, live stream, and updates. · `lib/features/health_dashboard/domain/usecases`
- [Steps Repo](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/domain/repositories/steps_repository.dart): repository contract · Domain interface for step data access. · `lib/features/health_dashboard/domain/repositories/steps_repository.dart`
- [Repo Impl](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/repositories/steps_repository_impl.dart): data repository · Connects local cache and remote health sources. · `lib/features/health_dashboard/data/repositories/steps_repository_impl.dart`
- [Local Cache](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/datasources/steps_local_data_source.dart): local datasource · Reads and writes cached step history in Hive. · `lib/features/health_dashboard/data/datasources/steps_local_data_source.dart`
- [Health Source](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart): remote datasource · Fetches live step data from platform health APIs. · `lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart`
- [Step Model](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/lib/features/health_dashboard/data/models/steps_history_model.dart): persistence model · Hive-backed persisted step history model. · `lib/features/health_dashboard/data/models/steps_history_model.dart`

### Platform Hosts

Native shells and platform-specific project entrypoints.

- [Android Host](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/android/app/src/main/AndroidManifest.xml): native shell · Android platform project and manifests. · `android/app/src/main/AndroidManifest.xml`
- [iOS Host](https://github.com/enforcerhuman/health_sync_dashboard/blob/HEAD/ios/Runner/AppDelegate.swift): native shell · iOS platform project, entitlements, and app delegate. · `ios/Runner/AppDelegate.swift`

## Connections

- Main → DI Setup: bootstraps · Startup configures dependency injection before the UI loads.
- Main → Hive Init: initializes · App startup prepares local storage.
- DI Setup → Steps Repo: registers · DI wires the domain contract to its implementation.
- DI Setup → Repo Impl: binds · Registers the repository implementation and its collaborators.
- DI Setup → Health Service: provides · Makes the health abstraction available for injection.
- DI Setup → Hive Box: provides · Makes Hive access available for persistence wiring.
- Home Screen → Steps Bloc: observes · The dashboard screen reacts to bloc state.
- Steps Bloc → Use Cases: invokes · Bloc delegates business actions to domain use cases.
- Use Cases → Steps Repo: depends on · Use cases rely on the repository contract.
- Repo Impl → Local Cache: reads/writes · Repository uses local storage for cache-first behavior.
- Repo Impl → Health Source: fetches · Repository pulls live step data from health APIs.
- Local Cache → Hive Box: uses · Local datasource accesses the Hive store.
- Local Cache → Step Model: persists · Cached step history is stored via the Hive model.
- Health Source → Health Service: uses · Remote datasource calls the platform health bridge.
- Health Source → Permissions: checks · Health access flows through permission handling.
- Repo Impl → Step Model: stores · Fresh values are written back for later launches.
- Steps Bloc → Local Cache: loads cache · Bloc shows cached step data immediately when available.
- Steps Bloc → Health Source: starts live · Bloc can trigger live step updates after cache load.
- Steps Bloc → Repo Impl: refreshes · Bloc ultimately drives the end-to-end steps pipeline.
- Android Host → Health Source: supports · Android host enables device health integration.
- iOS Host → Health Source: supports · iOS host enables device health integration.
- Theme → Shared Widgets: styles · Shared widgets consume common theme styling.
- Constants → Shared Widgets: feeds · UI components use shared colors and strings.
