Mobile Architecture

Overview

The GENIE.AI mobile app (mobile/genie_ai_mobile/) is a Flutter client that wraps the public-sector RAG stack behind OIDC-authenticated chat. It targets Android and iOS phones, builds in release mode through Flutter flavors (dev / staging / e2e / itu), and exchanges every backend call through an AuthInterceptor that injects a Keycloak-issued Bearer token.

This document is the developer entry point. It covers how the app is layered, how state is managed, how authentication works at the wire level, and where to look in the source tree. Operational deployment is in Mobile Deployment Guide; the user-facing UI surface is in UI Component Inventory; end-user authentication behaviour is in User Authentication; chat streaming and feedback are in Chat Pipeline.

1. Tech stack

The OpenAPI client (openapi_client/) is auto-generated from the backend JSDoc annotations and is checked in. Regenerate with ./scripts/generate-api-client.sh (see mobile/genie_ai_mobile/CLAUDE.md).

Local flutter_appauth fork — pubspec.yaml:28-29 references a vendored fork at flutter_appauth/flutter_appauth/. The fork exists to work around an upstream InsecureConnectionBuilder issue (tracked as flutter_appauth upstream issue #386). The fork is development-only: revert the path: override and drop the flutter_appauth/ directory before any merge to main — production uses CA-signed certs and allowInsecureConnections=false.

2. Application layers

The app follows a five-layer split that maps to directories under mobile/genie_ai_mobile/lib/:

Composition root lives in lib/main.dart (root widget MyApp, multi-provider scope). The lib/src/app.dart file is a Flutter project-template leftover (uses SettingsController, hardcodes a 3-locale list [en, de, ar], references sample_feature/ and settings/ views) and is not wired into the running app — see UI Component Inventory for the same “unused at runtime” note.

The codebase does not use a Proxy/Service-Provider pattern at the service layer. Domain classes (UserService, ConnectivityService, KeycloakService) are plain Dart classes; cross-cutting concerns (auth headers, logging, error classification) are wired by Riverpod providers and the AuthInterceptor, not by service proxies.

3. API layer

Provider wiring (lib/providers/api_providers.dart)

Riverpod exposes one provider per backend API domain. Each provider constructs a generated API client that shares the same authenticated http.Client injected by AuthInterceptor. Example shape (paraphrased from api_providers.dart):

final authenticatedApiProvider = Provider<ApiClient>((ref) {
  final config = getConfig();
  final tokenStorage = ref.watch(tokenStorageProvider);
  final client = config.allowInsecureConnections
      ? InsecureHttpClient()
      : http.Client();
  final interceptor = AuthInterceptor(
    inner: client,
    tokenStorage: tokenStorage,
    onRefreshToken: () => ref.read(authProvider.notifier).refreshToken(),
    logger: ref.read(authLoggerProvider),
  );
  return ApiClient(basePath: config.backendUrl)..client = interceptor;
});

This keeps the surface small and lets tests override a single provider.

Backend routes the app calls

Verified against components/gov-chat-backend/routes/:

For full request/response shapes, error codes, and pagination, see API Contracts (backend) — that document is the source of truth.

4. State management (Riverpod)

Provider layout (lib/services/auth/auth_providers.dart)

AuthNotifier lifecycle (lib/services/auth/auth_notifier.dart)

AuthNotifier is the single authority for the auth state machine. The lifecycle has five entry points:

1. init() — runs at app startup. Reads flutter_secure_storage, validates stored tokens, sets AuthState to authenticated if still valid, unauthenticated otherwise.
2. authorize() — kicked off by the OIDC login screen. Discovers Keycloak via OIDC metadata, opens the system browser via flutter_appauth, exchanges the PKCE-verified authorization code for tokens, and persists them.
3. refreshTokens() — called transparently when a backend call returns 401 (see User Authentication for the single-flight mutex).
4. didChangeAppLifecycleState(state) — wired to Flutter’s WidgetsBindingObserver. When state == AppLifecycleState.resumed and the user is authenticated, runs validateTokens() (proactive expiry check on resume).
5. logout() — fires the parallel logout sequence (see User Authentication).

_FailedOperation enum (auth_notifier.dart:41) tracks which operation last failed, so the UI can resume after a retry instead of asking the user to re-authorize.

AuthState (lib/services/auth/auth_state.dart)

enum AuthStatus { authenticated, unauthenticated, error }

class AuthState {
  final AuthStatus status;
  final String? userId;
  final String? displayName;
  final String? errorMessage;
  final bool retryable;

  const AuthState({
    this.status = AuthStatus.unauthenticated,
    this.userId,
    this.displayName,
    this.errorMessage,
    this.retryable = false,
  });

  const AuthState.authenticated({this.userId, this.displayName})
    : status = AuthStatus.authenticated,
      errorMessage = null,
      retryable = false;

  const AuthState.unauthenticated()
    : status = AuthStatus.unauthenticated,
      userId = null,
      displayName = null,
      errorMessage = null,
      retryable = false;

  AuthState.error({required String message, this.retryable = false})
    : status = AuthStatus.error,
      userId = null,
      displayName = null,
      errorMessage = message;
}

Widgets read authProvider and switch on state.status; the retryable flag controls whether a “Retry” button is shown.

5. Networking and SSE

AuthInterceptor (lib/services/auth/auth_interceptor.dart)

A BaseClient wrapper that:

• On onRequest: reads the access token from TokenStorage and adds Authorization: Bearer <token>.
• On onResponse: if the backend returns 401, attempts one transparent refresh, then retries the original request once. If the retry still fails with 401, throws AuthException so the UI can surface “Session expired”.

The refresh step is single-flight: while one refresh is in flight, parallel 401s wait on the same Completer<TokenSet?> rather than each issuing their own refresh call. This prevents Keycloak’s refresh-token rotation from invalidating a just-rotated token.

SSE parsing (lib/services/sse_parser.dart)

For the /api/queries/stream endpoint, the response is a text/event-stream. SseParser chunks the byte stream and emits five typed events (verbatim from sse_parser.dart:6-11):

The full taxonomy and downstream propagation are documented in Chat Pipeline.

6. Security features

SSL pinning is not implemented in production builds. The custom HTTP client (insecure_http_client.dart) is a development convenience for self-signed certificates on local Keycloak. Production relies on the system trust store (CA-signed certs).

For the user-visible flow of these features — login screen tap, browser handover, refresh on 401, logout sequence, error classes — see User Authentication.

7. i18n

Deployment-level locale whitelist is config-driven, not file-presence-driven — all 14 locale files stay in the source. A flavor restricts the active set via KeycloakConfig.supportedLocaleCodes.

See Restrict active locales for the canonical deployer reference.

8. Cross-cutting services

9. Project layout

For the complete annotated directory tree — including the design system, providers, utils, and locale files — see UI Component Inventory. The single most important contract for contributors: never edit openapi_client/ by hand — regenerate it with ./scripts/generate-api-client.sh from the backend JSDoc.

10. Next steps

• Shipping a build: see Mobile Deployment Guide — covers flavor creation, Android signing, iOS provisioning, App Links, and store submission.
• End-user auth behaviour: see User Authentication — covers the PKCE flow, refresh-on-401, error classes, and logout sequence.
• Chat UX: see Chat Pipeline — covers SSE event flow, feedback dialog, Quick Help overlay, PDF export.
• Per-widget API: see UI Component Inventory.
• Contributor workflows: see mobile/genie_ai_mobile/CLAUDE.md — OpenAPI regeneration, emulator SSL setup, E2E tests.