# vochicuongg/glance architecture

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

- Interactive diagram: https://gitdiagram.com/vochicuongg/glance
- Repository: https://github.com/vochicuongg/glance

## Overview

1. **Overall shape**
   - This is an **Android-first Flutter app**: most UI and state live in `lib/`, while Android-specific runtime integrations live in `android/app/src/main/kotlin/...`.
   - The app appears centered on **display/overlay control and privacy-related shielding**, based on the presence of overlay services, accessibility config, and architecture docs.

2. **App bootstrap**
   - `lib/main.dart` is the entry point for the Flutter side.
   - The app likely initializes core providers for **theme**, **locale**, and the **platform/channel bridge** before routing users into onboarding or the dashboard.

3. **Core application infrastructure**
   - `lib/core/localization/` contains app string access and locale state (`app_strings.dart`, `locale_provider.dart`), so text is centrally managed and language switching is a first-class concern.
   - `lib/core/theme/` holds the design system (`app_colors.dart`, `app_theme.dart`, `theme_provider.dart`), which suggests theme state is also globally shared.
   - `lib/core/services/glance_channel_service.dart` is the key boundary between Flutter and native Android code.

4. **Primary user experience layer**
   - `lib/features/dashboard/screens/` contains the main operational screens:
     - `dashboard_screen.dart` for the main control surface,
     - `settings_screen.dart` for configuration,
     - `targeted_area_editor.dart` for defining a specific protected area.
   - The dashboard widgets in `lib/features/dashboard/widgets/` break the UI into card-like controls for mode, sensitivity, tolerance, shield status, calibration, language, and app info.

5. **Onboarding and permission flow**
   - `lib/features/onboarding/screens/mode_selection_screen.dart` suggests the app starts by asking the user to choose an operating mode.
   - `lib/features/permissions/screens/permission_screen.dart` indicates a dedicated step for granting Android permissions before the app can function fully.
   - This implies a gated flow: **launch → onboarding → permissions → dashboard**.

6. **Native Android subsystem**
   - The Android implementation under `android/app/src/main/kotlin/com/glanceapp/glance/` contains four main entry points:
     - `MainActivity.kt`
     - `GlanceQuickTileService.kt`
     - `MaxOverlayService.kt`
     - `StandardOverlayService.kt`
   - This is the runtime boundary where Flutter delegates device-specific work to Android.

7. **Overlay and shielding services**
   - The existence of both `MaxOverlayService` and `StandardOverlayService` suggests two operational modes with different overlay intensity or behavior.
   - These services likely handle the actual on-device display protection/shielding behavior, while Flutter only configures them.
   - `android/app/src/main/res/xml/accessibility_config.xml` implies that accessibility capabilities are part of the native integration, likely to support screen-state monitoring or overlay interaction.

8. **Quick access control**
   - `GlanceQuickTileService.kt` indicates an Android Quick Settings tile.
   - This is a separate control surface outside the app UI, giving users a system-level shortcut to toggle or manage the app’s main protection mode.

9. **Configuration, assets, and platform resources**
   - Android resources include app icons, launch backgrounds, and localized strings under `android/app/src/main/res/`.
   - Flutter assets are present in the top-level `assets/` directory, though the exact contents aren’t shown here.
   - This means the visual identity and localized text are split between Flutter assets and Android resource packaging.

10. **Language support**
   - There is explicit Vietnamese localization in `android/app/src/main/res/values-vi/strings.xml`, plus shared localization infrastructure in Flutter.
   - So internationalization is implemented across both layers, with Android-native strings and Flutter-side locale handling.

11. **Build and platform boundaries**
   - The project uses standard Flutter packaging (`pubspec.yaml`, `pubspec.lock`) and Android Gradle Kotlin DSL (`android/build.gradle.kts`, `android/app/build.gradle.kts`).
   - The architecture is therefore a **hybrid Flutter + native Android** app, not a pure Flutter-only UI application.

12. **Docs and design intent**
   - `glance_architecture.md` and `privacy_display_architecture.md` are likely higher-level design references for the main behavior and privacy model.
   - Those docs probably explain the intended relationship between Flutter controls, Android services, and permission requirements.

13. **Testing and quality**
   - `test/widget_test.dart` suggests at least baseline Flutter widget testing.
   - `analysis_options.yaml` indicates static analysis and linting are part of the development workflow.

14. **How the pieces fit together**
   - The typical control path is: **Flutter UI collects user intent → `glance_channel_service` sends it to Android → native services/tile act on the device → status returns to Flutter for display**.
   - The key architectural boundary is between the **cross-platform presentation/state layer** in `lib/` and the **Android runtime services** that actually manipulate overlays, tiles, and permissions.

Main entry points: [`lib/features/dashboard/screens/dashboard_screen.dart`](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/dashboard_screen.dart) (Dashboard), [`lib/core/services/glance_channel_service.dart`](https://github.com/vochicuongg/glance/blob/main/lib/core/services/glance_channel_service.dart) (Native bridge), [`lib/main.dart`](https://github.com/vochicuongg/glance/blob/main/lib/main.dart) (App entry), [`android/app/src/main/kotlin/com/glanceapp/glance/GlanceQuickTileService.kt`](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/GlanceQuickTileService.kt) (Quick tile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_main(("App entry<br/>Flutter bootstrap<br/>[main.dart]"))
  node_loc["Localization<br/>Flutter i18n<br/>[app_strings.dart]"]
  node_theme["Theme<br/>Flutter theming<br/>[app_theme.dart]"]
  node_channel["Native bridge<br/>Platform channel"]
  node_onboarding["Mode select<br/>Onboarding screen"]
  node_permissions["Permissions<br/>Permission screen"]
  node_dashboard["Dashboard<br/>Main screen"]
  node_settings["Settings<br/>Config screen"]
  node_targeted["Area editor<br/>Protection editor"]
  node_modecard["Mode card<br/>Dashboard widget"]
  node_shieldcard["Shield status<br/>Dashboard widget"]
  node_senscard["Sensitivity<br/>Dashboard widget"]
  node_tolercard["Tolerance<br/>Dashboard widget"]
  node_calcard["Calibration<br/>Dashboard widget"]
  node_langcard["Language<br/>Dashboard widget"]
  node_aboutsheet["About sheet<br/>Info sheet"]
end

subgraph group_android["Android native"]
  node_mainact["Main activity<br/>Android entry<br/>[MainActivity.kt]"]
  node_quicktile["Quick tile<br/>Android tile"]
  node_maxoverlay["Max overlay<br/>Android service"]
  node_stdoverlay["Standard overlay<br/>Android service"]
  node_accesscfg["Accessibility<br/>Android config"]
end

subgraph group_resources["Resources"]
  node_stringsvi["Vietnamese strings<br/>Android locale<br/>[strings.xml]"]
end

node_main -->|"loads"| node_loc
node_main -->|"applies"| node_theme
node_main -->|"creates"| node_channel
node_main -->|"routes to"| node_onboarding
node_onboarding -->|"next"| node_permissions
node_permissions -->|"unlocks"| node_dashboard
node_dashboard -->|"uses"| node_modecard
node_dashboard -->|"uses"| node_shieldcard
node_dashboard -->|"uses"| node_senscard
node_dashboard -->|"uses"| node_tolercard
node_dashboard -->|"uses"| node_calcard
node_dashboard -->|"uses"| node_langcard
node_dashboard -->|"opens"| node_aboutsheet
node_dashboard -->|"navigates"| node_settings
node_dashboard -->|"navigates"| node_targeted
node_loc -->|"feeds text"| node_dashboard
node_theme -->|"styles"| node_dashboard
node_channel -->|"bridges"| node_mainact
node_channel -->|"controls"| node_maxoverlay
node_channel -->|"controls"| node_stdoverlay
node_channel -->|"syncs"| node_quicktile
node_quicktile -->|"toggles"| node_maxoverlay
node_quicktile -->|"toggles"| node_stdoverlay
node_maxoverlay -->|"depends on"| node_accesscfg
node_stdoverlay -->|"depends on"| node_accesscfg
node_stringsvi -.->|"mirrors"| node_loc

click node_main "https://github.com/vochicuongg/glance/blob/main/lib/main.dart"
click node_loc "https://github.com/vochicuongg/glance/blob/main/lib/core/localization/app_strings.dart"
click node_theme "https://github.com/vochicuongg/glance/blob/main/lib/core/theme/app_theme.dart"
click node_channel "https://github.com/vochicuongg/glance/blob/main/lib/core/services/glance_channel_service.dart"
click node_onboarding "https://github.com/vochicuongg/glance/blob/main/lib/features/onboarding/screens/mode_selection_screen.dart"
click node_permissions "https://github.com/vochicuongg/glance/blob/main/lib/features/permissions/screens/permission_screen.dart"
click node_dashboard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/dashboard_screen.dart"
click node_settings "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/settings_screen.dart"
click node_targeted "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/targeted_area_editor.dart"
click node_modecard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/overlay_mode_card.dart"
click node_shieldcard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/shield_status_card.dart"
click node_senscard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/sensitivity_slider_card.dart"
click node_tolercard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/tolerance_slider_card.dart"
click node_calcard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/calibrate_card.dart"
click node_langcard "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/language_selector_card.dart"
click node_aboutsheet "https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/about_app_sheet.dart"
click node_mainact "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/MainActivity.kt"
click node_quicktile "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/GlanceQuickTileService.kt"
click node_maxoverlay "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/MaxOverlayService.kt"
click node_stdoverlay "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/StandardOverlayService.kt"
click node_accesscfg "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/res/xml/accessibility_config.xml"
click node_stringsvi "https://github.com/vochicuongg/glance/blob/main/android/app/src/main/res/values-vi/strings.xml"

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,node_loc,node_theme,node_channel,node_onboarding,node_permissions,node_dashboard,node_settings,node_targeted,node_modecard,node_shieldcard,node_senscard,node_tolercard,node_calcard,node_langcard,node_aboutsheet toneBlue
class node_mainact,node_quicktile,node_maxoverlay,node_stdoverlay,node_accesscfg toneAmber
class node_stringsvi toneMint
```

## Components

### Flutter app

Cross-platform UI, state, and navigation

- [App entry](https://github.com/vochicuongg/glance/blob/main/lib/main.dart): Flutter bootstrap · Initializes app-wide state and routing · `lib/main.dart`
- [Localization](https://github.com/vochicuongg/glance/blob/main/lib/core/localization/app_strings.dart): Flutter i18n · Central string and locale management · `lib/core/localization/app_strings.dart`
- [Theme](https://github.com/vochicuongg/glance/blob/main/lib/core/theme/app_theme.dart): Flutter theming · App colors, theme setup, and theme state · `lib/core/theme/app_theme.dart`
- [Native bridge](https://github.com/vochicuongg/glance/blob/main/lib/core/services/glance_channel_service.dart): Platform channel · Flutter-to-Android control boundary · `lib/core/services/glance_channel_service.dart`
- [Mode select](https://github.com/vochicuongg/glance/blob/main/lib/features/onboarding/screens/mode_selection_screen.dart): Onboarding screen · First-run operating mode choice · `lib/features/onboarding/screens/mode_selection_screen.dart`
- [Permissions](https://github.com/vochicuongg/glance/blob/main/lib/features/permissions/screens/permission_screen.dart): Permission screen · Guides Android permission setup · `lib/features/permissions/screens/permission_screen.dart`
- [Dashboard](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/dashboard_screen.dart): Main screen · Primary control surface for protection state · `lib/features/dashboard/screens/dashboard_screen.dart`
- [Settings](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/settings_screen.dart): Config screen · App configuration and preferences · `lib/features/dashboard/screens/settings_screen.dart`
- [Area editor](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/screens/targeted_area_editor.dart): Protection editor · Defines a targeted protected area · `lib/features/dashboard/screens/targeted_area_editor.dart`
- [Mode card](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/overlay_mode_card.dart): Dashboard widget · Displays and changes overlay mode · `lib/features/dashboard/widgets/overlay_mode_card.dart`
- [Shield status](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/shield_status_card.dart): Dashboard widget · Shows current shielding state · `lib/features/dashboard/widgets/shield_status_card.dart`
- [Sensitivity](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/sensitivity_slider_card.dart): Dashboard widget · Adjusts detection sensitivity · `lib/features/dashboard/widgets/sensitivity_slider_card.dart`
- [Tolerance](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/tolerance_slider_card.dart): Dashboard widget · Adjusts protection tolerance · `lib/features/dashboard/widgets/tolerance_slider_card.dart`
- [Calibration](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/calibrate_card.dart): Dashboard widget · Calibration controls · `lib/features/dashboard/widgets/calibrate_card.dart`
- [Language](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/language_selector_card.dart): Dashboard widget · Locale switching control · `lib/features/dashboard/widgets/language_selector_card.dart`
- [About sheet](https://github.com/vochicuongg/glance/blob/main/lib/features/dashboard/widgets/about_app_sheet.dart): Info sheet · App information and metadata · `lib/features/dashboard/widgets/about_app_sheet.dart`

### Android native

Platform services and entry points

- [Main activity](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/MainActivity.kt): Android entry · Host activity for Flutter and native lifecycle · `android/app/src/main/kotlin/com/glanceapp/glance/MainActivity.kt`
- [Quick tile](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/GlanceQuickTileService.kt): Android tile · System-level toggle/control shortcut · `android/app/src/main/kotlin/com/glanceapp/glance/GlanceQuickTileService.kt`
- [Max overlay](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/MaxOverlayService.kt): Android service · High-intensity overlay protection mode · `android/app/src/main/kotlin/com/glanceapp/glance/MaxOverlayService.kt`
- [Standard overlay](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/kotlin/com/glanceapp/glance/StandardOverlayService.kt): Android service · Default overlay protection mode · `android/app/src/main/kotlin/com/glanceapp/glance/StandardOverlayService.kt`
- [Accessibility](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/res/xml/accessibility_config.xml): Android config · Accessibility service configuration for native runtime · `android/app/src/main/res/xml/accessibility_config.xml`

### Resources

App assets and packaged native resources

- [Vietnamese strings](https://github.com/vochicuongg/glance/blob/main/android/app/src/main/res/values-vi/strings.xml): Android locale · Native Vietnamese resources · `android/app/src/main/res/values-vi/strings.xml`

## Connections

- App entry → Localization: loads · App bootstrap wires localization
- App entry → Theme: applies · App bootstrap wires theme state
- App entry → Native bridge: creates · Initializes platform bridge
- App entry → Mode select: routes to · Launch flow begins with onboarding
- Mode select → Permissions: next · Mode choice leads into permission gating
- Permissions → Dashboard: unlocks · Successful permission flow reaches dashboard
- Dashboard → Mode card: uses · Primary screen composed from controls
- Dashboard → Shield status: uses · Primary screen composed from controls
- Dashboard → Sensitivity: uses · Primary screen composed from controls
- Dashboard → Tolerance: uses · Primary screen composed from controls
- Dashboard → Calibration: uses · Primary screen composed from controls
- Dashboard → Language: uses · Primary screen composed from controls
- Dashboard → About sheet: opens · Dashboard can surface app info
- Dashboard → Settings: navigates · Main control surface links to settings
- Dashboard → Area editor: navigates · Main control surface links to targeted editor
- Localization → Dashboard: feeds text · Localized strings drive UI labels
- Theme → Dashboard: styles · Theme state shapes dashboard presentation
- Native bridge → Main activity: bridges · Flutter delegates native work through Android host
- Native bridge → Max overlay: controls · Native overlay mode can be started or updated
- Native bridge → Standard overlay: controls · Native overlay mode can be started or updated
- Native bridge → Quick tile: syncs · Flutter state is exposed to the system tile
- Quick tile → Max overlay: toggles · Tile can activate overlay protection modes
- Quick tile → Standard overlay: toggles · Tile can activate overlay protection modes
- Max overlay → Accessibility: depends on · High-intensity overlay runtime relies on accessibility setup
- Standard overlay → Accessibility: depends on · Standard overlay runtime relies on accessibility setup
- Vietnamese strings → Localization: mirrors · Native locale resources align with Flutter localization