How enforcerhuman/health_sync_dashboard works
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: steps_remote_data_source.dart Health Source · injection_container.dart DI Setup · steps_bloc.dart Steps Bloc · steps_repository_impl.dart Repo Impl
Components 20
App Shell
Bootstrap and platform entrypoints.
Shared Core
Cross-cutting services, storage, and UI primitives.
- Theme · Shared app styling and visual theme definitions.
lib/common/theme/app_theme.dart - Shared Widgets · Reusable app chrome and text primitives.
lib/common/widgets - Constants · Colors, gradients, strings, and progress palettes.
lib/core/constants - Errors · Application exceptions and failure models.
lib/core/error - Health Service · Abstraction over device health APIs.
lib/core/services/health_services.dart - Hive Init · Initializes local persistence and Hive access.
lib/core/storage/hive_init.dart - Hive Box · Box helpers and persistence access point.
lib/core/storage/hive_box.dart - Permissions · 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 · Dashboard shell that composes the feature UI.
lib/features/health_dashboard/presentation/screens/home_screen.dart - Steps Bloc · Coordinates cached reads, live polling, and UI state.
lib/features/health_dashboard/presentation/bloc/steps_bloc/steps_bloc.dart - Use Cases · Application actions for cached fetch, live stream, and updates.
lib/features/health_dashboard/domain/usecases - Steps Repo · Domain interface for step data access.
lib/features/health_dashboard/domain/repositories/steps_repository.dart - Repo Impl · Connects local cache and remote health sources.
lib/features/health_dashboard/data/repositories/steps_repository_impl.dart - Local Cache · Reads and writes cached step history in Hive.
lib/features/health_dashboard/data/datasources/steps_local_data_source.dart - Health Source · Fetches live step data from platform health APIs.
lib/features/health_dashboard/data/datasources/steps_remote_data_source.dart - Step 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 · Android platform project and manifests.
android/app/src/main/AndroidManifest.xml - iOS Host · iOS platform project, entitlements, and app delegate.
ios/Runner/AppDelegate.swift
Connections 23
- 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.