Flutter app

​

Locked decisions

​

Core concepts (domain language)

​

State management: Riverpod v3

• Provider requires BuildContext to read state — Riverpod does not. This matters for services, repositories, and background tasks.
• Riverpod’s AsyncNotifier handles loading/error/data states cleanly without boilerplate.
• Compile-time safety with @riverpod code generation — no string keys, no runtime errors.
• Providers are composable and testable in isolation.
• Scales to the complexity of this app (multiple workspaces, per-channel message streams, gateway lifecycle).

​

Architecture: feature-first + 3-layer

Presentation  →  Application  →  Domain  ←  Data
(widgets)        (providers)     (models,    (repositories,
                 (notifiers)      contracts)  remote, local)

• domain has zero Flutter or third-party dependencies. Pure Dart.
• data implements domain contracts (repository interfaces).
• application (Riverpod providers/notifiers) wires domain + data together.
• presentation reads providers only. Never touches repositories or services directly.

​

Folder structure

lib/
├── main.dart                    # ProviderScope, bootstrap only
├── app.dart                     # MaterialApp.router, theme, router config
│
├── core/                        # Shared primitives — no feature logic here
│   ├── constants/
│   ├── errors/
│   ├── extensions/
│   ├── utils/
│   └── ui/                      # Design system / UI kit
│       ├── atoms/
│       ├── molecules/
│       └── theme/
│
├── config/
│   └── router/
│
├── platform/                    # Platform-specific adapters behind interfaces
│   ├── biometrics/
│   ├── notifications/
│   ├── media/
│   └── storage/
│
├── data/                        # Data layer — no UI here
│   ├── local/
│   │   ├── database/
│   │   └── cache/
│   ├── remote/
│   │   ├── gateway/
│   │   └── http/
│   └── repositories/
│
├── domain/                      # Pure Dart — zero Flutter dependency
│   ├── models/
│   ├── repositories/            # Contracts (abstract classes only)
│   └── services/
│
├── application/                 # Riverpod providers and notifiers
│   ├── providers.dart
│   ├── auth/
│   ├── gateway/
│   ├── channels/
│   ├── messages/
│   └── ...
│
└── features/                    # Presentation layer — screens and widgets
    ├── shell/
    ├── onboarding/
    ├── lock/
    ├── channels/
    ├── chat/
    ├── bots/
    └── settings/

​

Routing structure

/                                → redirect: auth guard → lock guard → /app/channels
/onboarding                      → OnboardingScreen
/lock                            → LockScreen
/workspaces                      → WorkspaceListScreen
/app  (StatefulShellRoute)       → AppShell
  /app/channels                  → ChannelListScreen
  /app/channels/:channelId       → ChatScreen
  /app/channels/:channelId/sessions/:sessionId  → SessionChatScreen
  /app/bots                      → BotListScreen
  /app/bots/:botId               → BotWebViewScreen
  /app/bots/:botId/stream        → PixelStreamScreen
  /app/settings                  → SettingsScreen

​

Key implementation rules

​

Models

• Every domain model uses freezed. No mutable model classes anywhere.
• JSON serialization lives in data/ DTOs, not domain models. A mapper converts DTO → domain model.
• Never pass raw Map<String, dynamic> outside the data/ layer.

​

Widgets

• Screens are thin: they read providers and pass data down to child widgets.
• No business logic in widgets. No repository calls from widgets.
• No if/else chains dispatching message types in one widget — use switch in a dispatcher widget that delegates to typed sub-widgets.
• Strings are never hardcoded in widgets. Use a constants file or ARB files (i18n-ready from day one).
• Split any widget that exceeds ~80 lines into smaller named widgets.

​

Gateway / WebSocket

• GatewayClient owns the raw connection, reconnect loop, and heartbeat. It knows nothing about domain models.
• GatewayProtocol handles frame parsing. It converts raw JSON to typed DTOs.
• GatewayAuthHandler handles the challenge/response and pairing flow.
• GatewayNotifier (Riverpod) owns the connection lifecycle and exposes state to the UI.
• MessageRepository subscribes to the gateway stream and writes to the local Drift DB.
• The UI reads from the local DB stream — it never reads directly from the WebSocket.

​

Outbox pattern

​

Platform abstraction

​

Adaptive layout

• AppShell detects screen width and renders either a NavigationRail (wide) or NavigationBar (narrow).
• The split-pane (channel list + chat) is implemented inside StatefulShellRoute.
• A single AdaptiveLayout.isWide(context) utility (based on MediaQuery.sizeOf) is the single source of truth for breakpoints.

​

Theming

• AppTheme provides both light and dark ThemeData using flex_color_scheme.
• No hardcoded colors or text styles in widgets — always use Theme.of(context) or named tokens from app_colors.dart.
• Theme mode is persisted in SettingsRepository and restored on startup.

​

Packages

dependencies:
  # State
  flutter_riverpod: ^3.x
  riverpod_annotation: ^4.x

  # Navigation
  go_router: ^14.x

  # Models
  freezed_annotation: ^3.x
  json_annotation: ^4.x

  # Local DB
  drift: ^2.x
  drift_flutter: ^0.x  # bundles sqlite3 3.x natively; sqlite3_flutter_libs is no longer needed

  # Theming
  flex_color_scheme: ^8.x

  # Secure storage
  flutter_secure_storage: ^9.x

  # WebSocket
  web_socket_channel: ^3.x

  # Crypto
  cryptography: ^2.x

  # Biometrics
  local_auth: ^2.x

  # QR scanning
  mobile_scanner: ^7.x

  # Media
  image_picker: ^1.x
  file_picker: ^8.x

  # Notifications
  flutter_local_notifications: ^18.x

  # WebView
  webview_flutter: ^4.x

dev_dependencies:
  build_runner: ^2.x
  freezed: ^3.x
  json_serializable: ^6.x
  riverpod_generator: ^4.x
  drift_dev: ^2.x

​

Build order

​

AI coding guardrails

1. “Implement by feature slice. Each feature has its own folder under features/ for presentation and application/ for state.”
2. “Respect the 3-layer boundary: features/ → application/ → domain/ ← data/. No layer may skip a level.”
3. “Do not place business logic in widgets. Widgets read providers and render data.”
4. “Do not access the gateway, database, or any service directly from a widget or screen.”
5. “No raw Map<String, dynamic> outside data/. All data crossing the data/domain boundary must be a typed, freezed model.”
6. “Every new feature requires: a freezed domain model, a repository contract in domain/repositories/, an implementation in data/repositories/, and a Riverpod notifier in application/.”
7. “All platform-specific behavior (biometrics, notifications, file system, WebView) must be behind an abstract interface in platform/.”
8. “No hardcoded strings in widgets. Use constants or ARB keys.”
9. “No hardcoded colors or text styles in widgets. Use Theme.of(context) tokens.”
10. “The gateway connection lifecycle lives in GatewayNotifier. The UI reads message data from the local DB stream via MessageRepository, not from the WebSocket directly.”
11. “Adaptive layout breakpoints use AdaptiveLayout.isWide(context) only. No inline MediaQuery width checks scattered across widgets.”
12. “A Bot is not a Channel. They are separate domain models with separate providers and separate screens.”
13. “Message bubble rendering uses a dispatcher widget that switches on MessageType and delegates to a typed sub-widget. No monolithic bubble widget.”
14. “State management is Riverpod v3 with code generation (@riverpod). Do not introduce Provider, Bloc, or GetX anywhere.”

​

Troubleshooting

drift: ">=2.28.1 <2.32.0"
drift_dev: ">=2.28.1 <2.32.0"

// v2
final state = ref.watch(authProvider).valueOrNull;

// v3
final state = ref.watch(authProvider).value;

// v2 — no longer compiles with freezed v3
@freezed
class Channel with _$Channel {
  const factory Channel({...}) = _Channel;
}

// v3 fix
@freezed
abstract class Channel with _$Channel {
  const factory Channel({...}) = _Channel;
}

// router_notifier.dart only imported auth_notifier.dart, not auth_state.dart directly.
// auth_notifier.dart uses `import` (not `export`) for auth_state.dart, so the
// AuthStatePatterns extension was not in scope.
// Error: "The method 'when' isn't defined for the type 'AuthState'"

// Fix: add a direct import to bring the extension into scope
import 'auth/auth_state.dart';

// ❌ BAD — ref.read after await will throw if provider was rebuilt/disposed
Future<void> sendText(...) async {
  final repo = ref.read(messageRepositoryProvider);
  await repo.insertOutbound(...);
  ref.read(gatewayProvider.notifier).send({...}); // 💥 ref may be dead here
}

// ✅ GOOD — all refs resolved before any await
Future<void> sendText(...) async {
  final repo = ref.read(messageRepositoryProvider);
  final gateway = ref.read(gatewayProvider.notifier); // captured early
  await repo.insertOutbound(...);
  gateway.send({...}); // safe — local variable, not going through ref
}