Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

11 — Flutter App Architecture (Shared)

How the Flutter client is built. Module docs 15_Flutter_Implementation_Guide.md extend this with module-specific structure. Forward-looking spec (no client repo exists yet).

1. Project & dependencies

studylyon_app/          (Flutter 3.x, Dart 3)
├── lib/
│   ├── main.dart
│   ├── app.dart
│   ├── core/            # di, router, theme, dio, storage, i18n, analytics, ws
│   ├── features/
│   │   └── <module>/    # data, domain, presentation (see §3)
│   └── shared/          # shared widgets, mixins, extensions
└── test/                # unit, widget, golden, integration

Recommended deps (verify licenses): flutter_bloc, dio, go_router, get_it, hive (cache) or shared_preferences, intl, flutter_localizations, connectivity_plus (or internet_connection_checker), fl_chart, mobile_scanner (flagged), flutter_markdown, cached_network_image, secure_storage, uuid.

2. DI (get_it)

  • AppDio (authenticated client), AuthRepository, TenantRepository, module repositories, cubits (lazy factory). No singletons holding per-screen state.

3. Module folder structure (per module)

features/<module>/
├── data/
│   ├── dto/<entity>_dto.dart        # envelope-payload mappers
│   ├── models/<entity>.dart         # domain models
│   └── repositories/<entity>_repository.dart
├── domain/
│   └── (optional) use cases when > 1 repo interaction
└── presentation/
    ├── cubit/<screen>_cubit.dart
    ├── pages/<screen>_page.dart
    └── widgets/<screen-specific widgets>

4. DTO → model mapping

  • API payload → *Dto.fromJson (validate types) → domain model (normalized ids, enums, dates DateTime, money in minor units int).
  • Serialization with json_serializable (build_runner) or hand-written fromJson (small modules) — pick one, prefer codegen for consistency.
  • Never pass DTOs into widgets; widgets consume models.

5. Networking

  • AppDio: base URL, bearer interceptor (auto-attach token), refresh interceptor (single-flight refresh, queue requests), error interceptor mapping envelope → typed ApiException (code/status/fieldDetails), idempotency header helper, requestId header, timeout 15 s (uploads 120 s).
  • WS: WsClient (socket.io-client or dart web_socket_channel per backend gateway — verify backend protocol; flagged assumption) with auto-reconnect + backoff.

6. Router (go_router)

  • AppRouter: GoRouter with StatefulShellRoute.indexedStack branches per top-level destination; route guards: authGuard, permissionGuard('x.y'), tenantGuard.
  • Deep links: Uri route table in module docs; push-notification tap → navigate by path.
  • 403/404/500 error screens registered globally.

7. Theme

  • AppTheme.light()/dark() from 02_Design_Tokens.md; org branding override; MaterialApp(theme, darkTheme, themeMode, locale, localizationsDelegates).

8. Extensions (shared)

  • context helpers: spacing, colorScheme shortcuts, showAppSnackbar(type, message, action).
  • String: toDate, capitalize, maskedEmail, initials.
  • int: toMoney(currency), toOrdinal.
  • DateTime: toDisplayDate(locale), startOfDay, isSameDay, weekdayLabel.
  • List: groupBy, chunk.

9. Localization

  • .arb files: app_en.arb, app_fr.arb, … (start: en; add per org demand).
  • AppLocalizations generated (intl_utils); all user-facing strings via keys — including server messages mapping (error code → key, fallback to server message only for business 4xx text).

10. Analytics

  • AnalyticsService interface (firebase_analytics recommended; swappable); events per 10_QA_Baseline.md §8; consent-gated; no PII beyond necessity.

11. Storage & security

  • flutter_secure_storage: access/refresh tokens, session meta.
  • shared_preferences: theme, locale, onboarding flags, cache of reference data.
  • Hive (if adopted): paginated list caches per module key {tenant}:{module}:{query}.

12. Testing strategy

  • Unit: cubits (mock repos), validators, formatters, mappers.
  • Widget: state-machine tests per screen; golden per shared component + screen (light/dark, 3 sizes); fonts bundled in test assets for stable goldens.
  • Integration: integration_test journeys: login → home; attendance mark flow; invoice pay flow; offline banner behavior.
  • E2E: device-cloud smoke per release (P0 journeys).
  • Run: flutter analyze, flutter test, flutter test integration_test -d <device>.

13. Performance

  • const constructors everywhere; ListView.builder mandatory for lists; RepaintBoundary on charts/media; image cache cached_network_image with resize; shader compilation jank → target Android 15+ Impeller; defer heavy init off first frame; isolate for CSV parsing (bulk import preview).
  • Profile every release on mid-range device against 10_QA_Baseline.md §1.

14. CI/CD (proposal)

  • GitHub Actions: analyze → unit → widget → golden → integration (Android emulator + Chrome) → build signed AAB/IPA; screenshots for QA on PRs (golden diffs).