# steven4383/better architecture

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

- Interactive diagram: https://gitdiagram.com/steven4383/better
- Repository: https://github.com/steven4383/better

## Overview

#### Purpose and Entry Points
“better” is a cross-platform Flutter habit, wellness, and social-challenge application. The Flutter runtime starts at `lib/main.dart`; platform hosts bootstrap it through `android/app/src/main/kotlin/com/example/better/MainActivity.kt` and `ios/Runner/AppDelegate.swift`. It targets Android, iOS, web, desktop Linux/macOS/Windows.

#### Application Composition and Navigation
The app is organized as GetX-style presentation, controller, and binding layers. Bindings construct and scope dependencies for app areas, while screens render authentication, onboarding, home, exploration, profile, and settings experiences. Core wiring is in `lib/Binding/app_binding.dart`, `lib/Binding/auth_binding.dart`, and `lib/Binding/home_binding.dart`; major user-facing routes/screens include `lib/Pages/home_screen.dart`, `lib/Pages/onboarding_screen.dart`, and `lib/Pages/profile_screen.dart`.

#### Authentication and User Lifecycle
Authentication is a primary control boundary: unauthenticated users move through login/recovery and onboarding/interest selection; authenticated users receive the main app experience. `lib/controller/auth_controller.dart` coordinates this state, using Firebase Authentication through `lib/services/firebase_auth_service.dart`. User identity, profile, interests, and preferences are represented by `lib/model/user_model.dart`, `lib/model/interest_model.dart`, and `lib/model/user_preferences_model.dart`.

#### Habit and Progress Domain
Habit creation, logs, daily completion, consistency, and momentum are the central product data flow. UI initiates changes from `lib/Pages/habit_creation_dialog.dart` and home surfaces; `lib/controller/home_controller.dart` manages display/state; models define persisted domain records in `lib/model/habit_model.dart` and `lib/model/habit_log_model.dart`. Progress-oriented UI components such as `lib/Pages/habit_progress_card.dart` and `lib/widgets/consistency.dart` consume this state.

#### Community, Discovery, and Challenges
Exploration and “for you” flows expose posts, challenges, and recommended/discoverable content. `lib/controller/explore_controller.dart` governs this area, surfaced by `lib/Pages/exploration_screen_tabbed.dart` and `lib/Pages/for_you_screen.dart`. Its principal entities are `lib/model/post_model.dart` and `lib/model/challenge_model.dart`, separating community content from personal habit data.

#### Firebase Persistence, Security, and Notifications
Firebase is the material backend boundary: Firebase Auth handles identity; Firestore stores application records via `lib/services/firestore_service.dart`; generated project configuration is `lib/firebase_options.dart`. Firestore authorization is enforced server-side in `firestore.rules`, with collection intent documented in `FIRESTORE_COLLECTIONS_GUIDE.md`. Push delivery and device-token lifecycle are handled by `lib/services/fcm_service.dart` and `lib/services/enhanced_notification_service.dart`; Android Firebase credentials are present at `android/app/google-services.json`.

#### Device and Platform Integration
The client integrates local/device capabilities for scheduled notifications and activity measurement through `lib/services/notification_service.dart` and `lib/services/step_counter_service.dart`. Native build/runtime configuration lives under `android/app/build.gradle.kts`, `ios/Runner/Info.plist`, and Flutter package dependencies are declared in `pubspec.yaml`. These adapters isolate platform services from controllers and UI.

Main entry points: [`lib/controller/home_controller.dart`](https://github.com/steven4383/better/blob/main/lib/controller/home_controller.dart) (Home controller), [`lib/controller/auth_controller.dart`](https://github.com/steven4383/better/blob/main/lib/controller/auth_controller.dart) (Auth controller), [`lib/services/firestore_service.dart`](https://github.com/steven4383/better/blob/main/lib/services/firestore_service.dart) (Firestore service), [`lib/Binding/app_binding.dart`](https://github.com/steven4383/better/blob/main/lib/Binding/app_binding.dart) (GetX bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_entry(("Flutter entry<br/>runtime entry<br/>[main.dart]"))
  node_bindings["GetX bindings<br/>dependency wiring<br/>[app_binding.dart]"]
  node_auth_binding["Auth binding<br/>dependency wiring<br/>[auth_binding.dart]"]
  node_home_binding["Home binding<br/>dependency wiring<br/>[home_binding.dart]"]
  node_auth_controller["Auth controller<br/>auth state"]
  node_home_controller["Home controller<br/>habit state"]
  node_explore_controller["Explore controller<br/>discovery state"]
  node_app_screens["App screens<br/>presentation<br/>[home_screen.dart]"]
  node_habit_creation["Habit creation<br/>presentation"]
  node_explore_screens["Explore screens<br/>presentation"]
  node_user_models["User models<br/>domain models<br/>[user_model.dart]"]
  node_habit_models["Habit models<br/>domain models<br/>[habit_model.dart]"]
  node_community_models["Community models<br/>domain models<br/>[post_model.dart]"]
end

subgraph group_backend["Firebase backend"]
  node_firebase_auth["Firebase Auth service<br/>identity adapter"]
  node_firestore[("Firestore service<br/>persistence adapter")]
  node_firestore_rules{{"Firestore rules<br/>server authorization<br/>[firestore.rules]"}}
end

subgraph group_platform["Platform integration"]
  node_notifications["Notification services<br/>push and local adapter<br/>[fcm_service.dart]"]
  node_step_counter["Step counter service<br/>device activity adapter"]
  node_android_host["Android host<br/>native runtime host<br/>[MainActivity.kt]"]
  node_ios_host["iOS host<br/>native runtime host<br/>[AppDelegate.swift]"]
end

node_android_host -->|"boots"| node_entry
node_ios_host -->|"boots"| node_entry
node_entry -->|"initializes"| node_bindings
node_bindings -->|"includes"| node_auth_binding
node_bindings -->|"includes"| node_home_binding
node_auth_binding -->|"provides"| node_auth_controller
node_home_binding -->|"provides"| node_home_controller
node_bindings -->|"provides"| node_explore_controller
node_app_screens -->|"drives auth flow"| node_auth_controller
node_app_screens -->|"renders state"| node_home_controller
node_habit_creation -->|"creates habits"| node_home_controller
node_explore_screens -->|"renders state"| node_explore_controller
node_auth_controller -->|"authenticates via"| node_firebase_auth
node_auth_controller -->|"manages"| node_user_models
node_home_controller -->|"manages"| node_habit_models
node_explore_controller -->|"manages"| node_community_models
node_auth_controller -->|"persists profile"| node_firestore
node_home_controller -->|"persists habits and logs"| node_firestore
node_explore_controller -->|"loads content"| node_firestore
node_firestore_rules -.->|"authorizes"| node_firestore
node_notifications -->|"stores device tokens"| node_firestore
node_home_controller -->|"reads activity"| node_step_counter

click node_entry "https://github.com/steven4383/better/blob/main/lib/main.dart"
click node_bindings "https://github.com/steven4383/better/blob/main/lib/Binding/app_binding.dart"
click node_auth_binding "https://github.com/steven4383/better/blob/main/lib/Binding/auth_binding.dart"
click node_home_binding "https://github.com/steven4383/better/blob/main/lib/Binding/home_binding.dart"
click node_auth_controller "https://github.com/steven4383/better/blob/main/lib/controller/auth_controller.dart"
click node_home_controller "https://github.com/steven4383/better/blob/main/lib/controller/home_controller.dart"
click node_explore_controller "https://github.com/steven4383/better/blob/main/lib/controller/explore_controller.dart"
click node_app_screens "https://github.com/steven4383/better/blob/main/lib/Pages/home_screen.dart"
click node_habit_creation "https://github.com/steven4383/better/blob/main/lib/Pages/habit_creation_dialog.dart"
click node_explore_screens "https://github.com/steven4383/better/blob/main/lib/Pages/exploration_screen_tabbed.dart"
click node_user_models "https://github.com/steven4383/better/blob/main/lib/model/user_model.dart"
click node_habit_models "https://github.com/steven4383/better/blob/main/lib/model/habit_model.dart"
click node_community_models "https://github.com/steven4383/better/blob/main/lib/model/post_model.dart"
click node_firebase_auth "https://github.com/steven4383/better/blob/main/lib/services/firebase_auth_service.dart"
click node_firestore "https://github.com/steven4383/better/blob/main/lib/services/firestore_service.dart"
click node_firestore_rules "https://github.com/steven4383/better/blob/main/firestore.rules"
click node_notifications "https://github.com/steven4383/better/blob/main/lib/services/fcm_service.dart"
click node_step_counter "https://github.com/steven4383/better/blob/main/lib/services/step_counter_service.dart"
click node_android_host "https://github.com/steven4383/better/blob/main/android/app/src/main/kotlin/com/example/better/MainActivity.kt"
click node_ios_host "https://github.com/steven4383/better/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 node_entry,node_bindings,node_auth_binding,node_home_binding,node_auth_controller,node_home_controller,node_explore_controller,node_app_screens,node_habit_creation,node_explore_screens,node_user_models,node_habit_models,node_community_models toneBlue
class node_firebase_auth,node_firestore,node_firestore_rules toneAmber
class node_notifications,node_step_counter,node_android_host,node_ios_host toneMint
```

## Components

### Flutter app

- [Flutter entry](https://github.com/steven4383/better/blob/main/lib/main.dart): runtime entry · `lib/main.dart`
- [GetX bindings](https://github.com/steven4383/better/blob/main/lib/Binding/app_binding.dart): dependency wiring · Scopes controllers and services by app area. · `lib/Binding/app_binding.dart`
- [Auth binding](https://github.com/steven4383/better/blob/main/lib/Binding/auth_binding.dart): dependency wiring · `lib/Binding/auth_binding.dart`
- [Home binding](https://github.com/steven4383/better/blob/main/lib/Binding/home_binding.dart): dependency wiring · `lib/Binding/home_binding.dart`
- [Auth controller](https://github.com/steven4383/better/blob/main/lib/controller/auth_controller.dart): auth state · Controls login, recovery, onboarding, and authenticated access. · `lib/controller/auth_controller.dart`
- [Home controller](https://github.com/steven4383/better/blob/main/lib/controller/home_controller.dart): habit state · Manages habit display, completion, and progress state. · `lib/controller/home_controller.dart`
- [Explore controller](https://github.com/steven4383/better/blob/main/lib/controller/explore_controller.dart): discovery state · `lib/controller/explore_controller.dart`
- [App screens](https://github.com/steven4383/better/blob/main/lib/Pages/home_screen.dart): presentation · Home, onboarding, and profile user experiences. · `lib/Pages/home_screen.dart`
- [Habit creation](https://github.com/steven4383/better/blob/main/lib/Pages/habit_creation_dialog.dart): presentation · `lib/Pages/habit_creation_dialog.dart`
- [Explore screens](https://github.com/steven4383/better/blob/main/lib/Pages/exploration_screen_tabbed.dart): presentation · Discovery and personalized content surfaces. · `lib/Pages/exploration_screen_tabbed.dart`
- [User models](https://github.com/steven4383/better/blob/main/lib/model/user_model.dart): domain models · Identity, interests, and preferences. · `lib/model/user_model.dart`
- [Habit models](https://github.com/steven4383/better/blob/main/lib/model/habit_model.dart): domain models · Habit definitions and completion logs. · `lib/model/habit_model.dart`
- [Community models](https://github.com/steven4383/better/blob/main/lib/model/post_model.dart): domain models · Posts and challenges. · `lib/model/post_model.dart`

### Firebase backend

- [Firebase Auth service](https://github.com/steven4383/better/blob/main/lib/services/firebase_auth_service.dart): identity adapter · `lib/services/firebase_auth_service.dart`
- [Firestore service](https://github.com/steven4383/better/blob/main/lib/services/firestore_service.dart): persistence adapter · `lib/services/firestore_service.dart`
- [Firestore rules](https://github.com/steven4383/better/blob/main/firestore.rules): server authorization · `firestore.rules`

### Platform integration

- [Notification services](https://github.com/steven4383/better/blob/main/lib/services/fcm_service.dart): push and local adapter · Manages FCM tokens, push delivery, and scheduled notifications. · `lib/services/fcm_service.dart`
- [Step counter service](https://github.com/steven4383/better/blob/main/lib/services/step_counter_service.dart): device activity adapter · `lib/services/step_counter_service.dart`
- [Android host](https://github.com/steven4383/better/blob/main/android/app/src/main/kotlin/com/example/better/MainActivity.kt): native runtime host · `android/app/src/main/kotlin/com/example/better/MainActivity.kt`
- [iOS host](https://github.com/steven4383/better/blob/main/ios/Runner/AppDelegate.swift): native runtime host · `ios/Runner/AppDelegate.swift`

## Connections

- Android host → Flutter entry: boots
- iOS host → Flutter entry: boots
- Flutter entry → GetX bindings: initializes
- GetX bindings → Auth binding: includes
- GetX bindings → Home binding: includes
- Auth binding → Auth controller: provides
- Home binding → Home controller: provides
- GetX bindings → Explore controller: provides
- App screens → Auth controller: drives auth flow
- App screens → Home controller: renders state
- Habit creation → Home controller: creates habits
- Explore screens → Explore controller: renders state
- Auth controller → Firebase Auth service: authenticates via
- Auth controller → User models: manages
- Home controller → Habit models: manages
- Explore controller → Community models: manages
- Auth controller → Firestore service: persists profile
- Home controller → Firestore service: persists habits and logs
- Explore controller → Firestore service: loads content
- Firestore rules → Firestore service: authorizes
- Notification services → Firestore service: stores device tokens
- Home controller → Step counter service: reads activity