# zuhak5/homepilot architecture

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

- Interactive diagram: https://gitdiagram.com/zuhak5/homepilot
- Repository: https://github.com/zuhak5/homepilot

## Overview

#### Purpose and Entry Points
HomePilot is an Android-focused Flutter app for home-asset tracking and recurring maintenance. Supabase is authoritative; Drift/SQLite is an authenticated cache and offline mutation queue. Flutter starts at `lib/main.dart`, with splash handling in `lib/homepilot_animated_splash_screen.dart`. Android hosts Flutter through `android/app/src/main/kotlin/com/homepilot/app/MainActivity.kt`.

#### App Composition and Domain
Core domain contracts, models, selectors, and feature models establish the application’s data vocabulary and repository boundaries. UI foundations provide theme and shared composition; localization supports English and Arabic.
- `lib/src/core/domain/contracts.dart`
- `lib/src/core/domain/models.dart`
- `lib/src/core/data/repositories.dart`
- `lib/src/ui/app_theme.dart`
- `lib/l10n/app_en.arb`

#### Authentication and Account Boundary
Production access is gated by Google sign-in and Supabase Auth; unsupported local/guest flows are excluded. Authentication state determines whether the app shell is reachable, and account cleanup handles user-local data lifecycle.
- `lib/src/features/auth/presentation/authentication_gate.dart`
- `lib/src/features/auth/data/native_google_sign_in.dart`
- `lib/src/features/auth/data/supabase_auth_repository.dart`
- `lib/src/features/auth/data/local_account_data_cleaner.dart`

#### Local Persistence, Offline Work, and Sync
Drift provides local snapshots plus queued mutations. The sync coordinator orchestrates session/connectivity recovery, outgoing changes, remote refreshes, conflict preservation, and background/foreground scheduling. Supabase Realtime triggers cache invalidation across devices rather than treating local data as canonical.
- `lib/src/core/database/app_database.dart`
- `lib/src/core/sync/sync_coordinator.dart`
- `lib/src/core/sync/supabase_sync_gateway.dart`
- `lib/src/core/sync/local_sync_store.dart`
- `lib/src/core/sync/background_sync_scheduler.dart`

#### Supabase Cloud Platform
Supabase supplies Auth, Postgres with RLS, Realtime, private Storage, and server-side RPC/schema behavior. Versioned migrations define cloud schema evolution, synchronization protocol, maintenance completion, account deletion, notifications, and points monetization. Edge Functions isolate privileged account deletion and AdMob server-side-verification processing.
- `supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql`
- `supabase/migrations/20260629150852_enable_realtime_sync.sql`
- `supabase/migrations/20260728042000_enable_maintenance_completion_rpc.sql`
- `supabase/functions/delete-account/index.ts`
- `supabase/functions/admob-ssv-handler/index.ts`

#### Device Services and Monetization
Services translate domain changes into local notifications/reminder reconciliation, permissions, feedback, backup/diagnostic export, weather, and health scoring. Monetization is represented as a feature and backed by Supabase points/reward schema plus native Android ad presentation.
- `lib/src/core/services/reminder_schedule_reconciler.dart`
- `lib/src/core/services/notification_service.dart`
- `lib/src/features/monetization/monetization.dart`
- `android/app/src/main/kotlin/com/homepilot/app/HomePilotNativeAdFactory.kt`
- `supabase/migrations/20260801124625_create_points_rpc_and_reward_claims.sql`

#### Configuration, Observability, and Delivery
Runtime configuration injects public Supabase, Google OAuth, and Sentry settings by environment; secure storage protects Supabase session material. Sentry is privacy-restricted through explicit bootstrap, event scrubbing, and tracing boundaries. GitHub Actions is the only supported signed production-build path; a separate static download site publishes releases.
- `lib/src/core/config/app_config.dart`
- `lib/src/core/supabase/supabase_bootstrap.dart`
- `lib/src/core/observability/sentry_bootstrap.dart`
- `lib/src/core/observability/sentry_event_scrubber.dart`
- `.github/workflows/build-production-android.yml`
- `download-site/index.html`

Main entry points: [`lib/main.dart`](https://github.com/zuhak5/homepilot/blob/main/lib/main.dart) (Flutter entry), [`supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql`](https://github.com/zuhak5/homepilot/blob/main/supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql) (Supabase cloud), [`lib/src/core/sync/sync_coordinator.dart`](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/sync_coordinator.dart) (Sync coordinator), [`lib/src/features/auth/presentation/authentication_gate.dart`](https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/presentation/authentication_gate.dart) (Authentication gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flutter App"]
  node_flutter_entry["Flutter entry<br/>application entry<br/>[main.dart]"]
  node_splash["Animated splash<br/>startup UI"]
  node_domain["Domain contracts<br/>domain boundary<br/>[contracts.dart]"]
  node_ui_foundation["UI foundation<br/>theme and localization<br/>[app_theme.dart]"]
  node_auth_gate["Authentication gate<br/>session boundary"]
  node_auth_repositories["Google + Supabase Auth<br/>auth adapters"]
  node_account_cleanup["Local account cleanup<br/>account lifecycle"]
  node_device_services["Device services<br/>reminders and diagnostics"]
  node_monetization["Monetization feature<br/>rewards<br/>[monetization.dart]"]
end

subgraph group_local["Local Data &amp; Sync"]
  node_drift_db[("Drift cache + queue<br/>SQLite database<br/>[app_database.dart]")]
  node_sync_coordinator["Sync coordinator<br/>sync orchestration"]
  node_sync_gateway["Supabase sync gateway<br/>remote sync adapter"]
  node_background_sync["Background sync scheduler<br/>lifecycle scheduler"]
end

subgraph group_cloud["Supabase Platform"]
  node_supabase_bootstrap["Supabase bootstrap<br/>runtime integration"]
  node_supabase_platform[("Supabase cloud<br/>Auth, Postgres, Realtime, Storage")]
  node_edge_functions{{"Privileged Edge Functions<br/>server functions<br/>[index.ts]"}}
end

subgraph group_device["Android &amp; Device"]
  node_android_host["Android host + ads<br/>native integration<br/>[MainActivity.kt]"]
end

subgraph group_delivery["Delivery"]
  node_observability["Sentry bootstrap<br/>privacy-restricted telemetry"]
  node_production_build["Signed Android build<br/>GitHub Actions pipeline"]
  node_download_site["Release download site<br/>static publishing<br/>[index.html]"]
end

node_android_host -->|"hosts"| node_flutter_entry
node_flutter_entry -->|"starts with"| node_splash
node_flutter_entry -->|"routes through"| node_auth_gate
node_flutter_entry -->|"uses"| node_ui_foundation
node_flutter_entry -->|"initializes"| node_supabase_bootstrap
node_auth_gate -->|"authenticates via"| node_auth_repositories
node_auth_repositories -->|"uses Auth"| node_supabase_platform
node_auth_gate -->|"cleans local account data"| node_account_cleanup
node_domain -.->|"defines local data boundary"| node_drift_db
node_domain -.->|"defines sync contracts"| node_sync_coordinator
node_sync_coordinator -->|"reads snapshots and queue"| node_drift_db
node_sync_coordinator -->|"pushes and refreshes"| node_sync_gateway
node_background_sync -->|"schedules"| node_sync_coordinator
node_sync_gateway -->|"syncs and subscribes to Realtime"| node_supabase_platform
node_supabase_bootstrap -->|"configures client"| node_supabase_platform
node_device_services -->|"reconciles reminders from"| node_drift_db
node_monetization -->|"uses points and reward RPCs"| node_supabase_platform
node_monetization -->|"uses native ad presentation"| node_android_host
node_supabase_platform -->|"invokes privileged operations"| node_edge_functions
node_flutter_entry -->|"reports through"| node_observability
node_production_build -->|"builds signed app"| node_android_host
node_production_build -->|"publishes releases to"| node_download_site

click node_flutter_entry "https://github.com/zuhak5/homepilot/blob/main/lib/main.dart"
click node_splash "https://github.com/zuhak5/homepilot/blob/main/lib/homepilot_animated_splash_screen.dart"
click node_domain "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/domain/contracts.dart"
click node_ui_foundation "https://github.com/zuhak5/homepilot/blob/main/lib/src/ui/app_theme.dart"
click node_auth_gate "https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/presentation/authentication_gate.dart"
click node_auth_repositories "https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/data/supabase_auth_repository.dart"
click node_account_cleanup "https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/data/local_account_data_cleaner.dart"
click node_device_services "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/services/reminder_schedule_reconciler.dart"
click node_monetization "https://github.com/zuhak5/homepilot/blob/main/lib/src/features/monetization/monetization.dart"
click node_drift_db "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/database/app_database.dart"
click node_sync_coordinator "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/sync_coordinator.dart"
click node_sync_gateway "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/supabase_sync_gateway.dart"
click node_background_sync "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/background_sync_scheduler.dart"
click node_supabase_bootstrap "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/supabase/supabase_bootstrap.dart"
click node_supabase_platform "https://github.com/zuhak5/homepilot/blob/main/supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql"
click node_edge_functions "https://github.com/zuhak5/homepilot/blob/main/supabase/functions/delete-account/index.ts"
click node_android_host "https://github.com/zuhak5/homepilot/blob/main/android/app/src/main/kotlin/com/homepilot/app/MainActivity.kt"
click node_observability "https://github.com/zuhak5/homepilot/blob/main/lib/src/core/observability/sentry_bootstrap.dart"
click node_production_build "https://github.com/zuhak5/homepilot/blob/main/.github/workflows/build-production-android.yml"
click node_download_site "https://github.com/zuhak5/homepilot/blob/main/download-site/index.html"

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_flutter_entry,node_splash,node_domain,node_ui_foundation,node_auth_gate,node_auth_repositories,node_account_cleanup,node_device_services,node_monetization toneBlue
class node_drift_db,node_sync_coordinator,node_sync_gateway,node_background_sync toneAmber
class node_supabase_bootstrap,node_supabase_platform,node_edge_functions toneMint
class node_android_host toneRose
class node_observability,node_production_build,node_download_site toneIndigo
```

## Components

### Flutter App

- [Flutter entry](https://github.com/zuhak5/homepilot/blob/main/lib/main.dart): application entry · `lib/main.dart`
- [Animated splash](https://github.com/zuhak5/homepilot/blob/main/lib/homepilot_animated_splash_screen.dart): startup UI · `lib/homepilot_animated_splash_screen.dart`
- [Domain contracts](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/domain/contracts.dart): domain boundary · Models and repository contracts define the app vocabulary. · `lib/src/core/domain/contracts.dart`
- [UI foundation](https://github.com/zuhak5/homepilot/blob/main/lib/src/ui/app_theme.dart): theme and localization · `lib/src/ui/app_theme.dart`
- [Authentication gate](https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/presentation/authentication_gate.dart): session boundary · Controls access to the authenticated app shell. · `lib/src/features/auth/presentation/authentication_gate.dart`
- [Google + Supabase Auth](https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/data/supabase_auth_repository.dart): auth adapters · `lib/src/features/auth/data/supabase_auth_repository.dart`
- [Local account cleanup](https://github.com/zuhak5/homepilot/blob/main/lib/src/features/auth/data/local_account_data_cleaner.dart): account lifecycle · `lib/src/features/auth/data/local_account_data_cleaner.dart`
- [Device services](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/services/reminder_schedule_reconciler.dart): reminders and diagnostics · Reconciles notifications and provides device-facing utilities. · `lib/src/core/services/reminder_schedule_reconciler.dart`
- [Monetization feature](https://github.com/zuhak5/homepilot/blob/main/lib/src/features/monetization/monetization.dart): rewards · `lib/src/features/monetization/monetization.dart`

### Local Data & Sync

- [Drift cache + queue](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/database/app_database.dart): SQLite database · Authenticated snapshots and offline mutations. · `lib/src/core/database/app_database.dart`
- [Sync coordinator](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/sync_coordinator.dart): sync orchestration · Recovers sessions/connectivity and coordinates push, refresh, and conflicts. · `lib/src/core/sync/sync_coordinator.dart`
- [Supabase sync gateway](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/supabase_sync_gateway.dart): remote sync adapter · `lib/src/core/sync/supabase_sync_gateway.dart`
- [Background sync scheduler](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/sync/background_sync_scheduler.dart): lifecycle scheduler · `lib/src/core/sync/background_sync_scheduler.dart`

### Supabase Platform

- [Supabase bootstrap](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/supabase/supabase_bootstrap.dart): runtime integration · Initializes configured Supabase client and secure session handling. · `lib/src/core/supabase/supabase_bootstrap.dart`
- [Supabase cloud](https://github.com/zuhak5/homepilot/blob/main/supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql): Auth, Postgres, Realtime, Storage · Authoritative data platform with RLS and RPCs. · `supabase/migrations/20260628000100_create_homepilot_cloud_schema.sql`
- [Privileged Edge Functions](https://github.com/zuhak5/homepilot/blob/main/supabase/functions/delete-account/index.ts): server functions · Handles account deletion and AdMob server-side verification. · `supabase/functions/delete-account/index.ts`

### Android & Device

- [Android host + ads](https://github.com/zuhak5/homepilot/blob/main/android/app/src/main/kotlin/com/homepilot/app/MainActivity.kt): native integration · Hosts Flutter and presents native ads. · `android/app/src/main/kotlin/com/homepilot/app/MainActivity.kt`

### Delivery

- [Sentry bootstrap](https://github.com/zuhak5/homepilot/blob/main/lib/src/core/observability/sentry_bootstrap.dart): privacy-restricted telemetry · `lib/src/core/observability/sentry_bootstrap.dart`
- [Signed Android build](https://github.com/zuhak5/homepilot/blob/main/.github/workflows/build-production-android.yml): GitHub Actions pipeline · Only supported production build path. · `.github/workflows/build-production-android.yml`
- [Release download site](https://github.com/zuhak5/homepilot/blob/main/download-site/index.html): static publishing · `download-site/index.html`

## Connections

- Android host + ads → Flutter entry: hosts
- Flutter entry → Animated splash: starts with
- Flutter entry → Authentication gate: routes through
- Flutter entry → UI foundation: uses
- Flutter entry → Supabase bootstrap: initializes
- Authentication gate → Google + Supabase Auth: authenticates via
- Google + Supabase Auth → Supabase cloud: uses Auth
- Authentication gate → Local account cleanup: cleans local account data
- Domain contracts → Drift cache + queue: defines local data boundary
- Domain contracts → Sync coordinator: defines sync contracts
- Sync coordinator → Drift cache + queue: reads snapshots and queue
- Sync coordinator → Supabase sync gateway: pushes and refreshes
- Background sync scheduler → Sync coordinator: schedules
- Supabase sync gateway → Supabase cloud: syncs and subscribes to Realtime
- Supabase bootstrap → Supabase cloud: configures client
- Device services → Drift cache + queue: reconciles reminders from
- Monetization feature → Supabase cloud: uses points and reward RPCs
- Monetization feature → Android host + ads: uses native ad presentation
- Supabase cloud → Privileged Edge Functions: invokes privileged operations
- Flutter entry → Sentry bootstrap: reports through
- Signed Android build → Android host + ads: builds signed app
- Signed Android build → Release download site: publishes releases to