vochicuongg/glance

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.