Flutter Architecture Overview (Light Mode)

​
Overview

Welcome to the documentation for Gremlin Mobile, the mobile client platform for the Gremlin ecosystem. The mobile application platform is designed as a multi-app monorepo from day one using Flutter, communicating with the Go/Postgres/NATS backend. The mobile app acts strictly as a client—the Go backend remains the single source of truth and write authority.

​
📱 The Applications

The workspace hosts two primary applications, each targeting both iOS and Android:
  1. FieldForce
    An offline-first, background-location-tracking application designed for field workers operating in locations with poor or no network connectivity.
  2. Digital Worker
    A role-agent and chat-observation application allowing team members to communicate, observation-log, and manage tasks. It is lighter than FieldForce and does not track location.

​
🛠 Why Flutter?

We chose Flutter (targeting iOS and Android from a single codebase) over other options (such as React Native or Web Shells/Capacitor) for several reasons:
  • Consistent Ecosystem: Standardized first-party packages reduce the risk of version incompatibilities, making code generation much cleaner and less bug-prone.
  • Pixel-Perfect Rendering: Flutter’s Impeller rendering engine guarantees identical UI rendering across different OS versions and devices, avoiding platform-specific UI bugs.
  • Sound Null Safety: Code-level null safety eliminates a major class of runtime exceptions before the app is ever deployed.
  • Unified Tooling: Single test, build, and development loop (flutter test, flutter build, Dart DevTools).

​
📂 Workspace Structure

The monorepo uses Melos to manage package dependencies and workspace actions. It is structured into two main directories: 
gremlin_mobile/
  ├── apps/                   # Independently deployable applications
  │   ├── fieldforce/         # FieldForce application bundle
  │   └── digital_worker/     # Digital Worker application bundle
  └── packages/               # Shared internal packages
      ├── core_models/        # Domain core (Entities, Result types) - pure Dart, zero deps
      ├── core_network/       # Data layer network client & DTOs
      ├── core_auth/          # JWT authentication & session management
      ├── core_database/      # PowerSync local DB & schemas
      ├── core_ui/            # Shared Brand components, tokens, and themes
      ├── core_i18n/          # Translations and slang infrastructure (zero deps, slang runtime & Flutter only)
      ├── core_notifications/ # FCM/APNs push notifications & deep links
      └── core_location/      # Background location engine (FieldForce only)
  • Apps (apps/*) are fully independent projects with their own bundle IDs, release cycles, and configurations.
  • Packages (packages/*) house shared logic. No package should depend on an app, enforcing clear boundaries and strict modularity.

​
🔗 Related Resources