Skip to content

gracefullight/pkgs / .agents/skills/oma-mobile

oma-mobile

Unverified

Implement Flutter, React Native, or native Swift apps. Use for mobile screens, widgets, platform integrations, and application data flows.

variants/flutter/tech-stack.md

View on GitHub
# Mobile Agent - Tech Stack Reference (Flutter)

Starter reference for the selected platform. Preserve existing project choices. The caching implementation below applies only when caching is required; do not add it for an unrelated screen or widget change.

## Framework + State Management

- **Language**: Dart 3.10+
- **UI Framework**: Flutter 3.44+
- **UI Toolkit**: Material Design 3 (Android) + iOS HIG adaptations via `CupertinoAdaptiveTheme` or `Platform.isIOS` guards
- **State Management**: Riverpod 3.x with `@riverpod` code generation (`AsyncNotifier`, `Notifier`, `StreamNotifier`)
- **Concurrency**: Dart async/await, `Stream`, `StreamController`, structured cancellation via `ref.onDispose`
- **Minimum SDK**: Flutter 3.44 / Dart 3.10 / Android API 24 / iOS 16

Riverpod 3.x with `@riverpod` codegen replaces manual `StateNotifierProvider` and hand-written provider constants. The code generator emits typed, cancellation-safe notifier subclasses at build time (`AsyncNotifier` for `Future` builds, `StreamNotifier` for `Stream` builds). Riverpod 3 drops the generated `FooRef` typedefs — provider and notifier build signatures take the unified `Ref` type. Provider state is disposed automatically when the last listener is removed; side-effectful providers use `ref.onDispose` to cancel in-flight requests.

## HTTP / API Client: Dio with Interceptors

| Component | Package |
|-----------|---------|
| HTTP transport | `dio` |
| Auth interceptor | custom `AuthInterceptor` (injects Bearer token) |
| Retry interceptor | custom `RetryInterceptor` (exponential back-off) |
| Logging interceptor | `pretty_dio_logger` (debug builds only) |

Dio is the **transport layer only**. Interceptors handle cross-cutting concerns (auth injection, retry, logging) — they must never cache or interpret domain objects. All Dio interceptors operate on raw `RequestOptions` / `Response` bytes. Domain-level caching belongs exclusively at the Repository layer (see below).

```
Presentation (Riverpod provider)
  |  calls
  v
Repository (data layer)  ──reads/writes──►  Local Cache (Drift table)
  |  on miss / revalidate
  v
RemoteDataSource  (Dio)  ──HTTP──►  Backend REST API
```

## Response Cache: Offline-First Repository (Drift)

When response caching is required, implement it at the Repository (data) layer, using a Drift database table as the local cache. The cache stores **decoded domain entities** — never raw HTTP bytes or JSON strings. The Dio client and its interceptors are never cache-aware.

**Placement rule — Repository layer, not transport.** Do **not** add a Dio cache interceptor (e.g. `dio_http_cache`, `dio_cache_interceptor`) as the system of record for domain reads. Such interceptors operate on raw bytes, making them invisible to the domain and untestable at the business-logic level. Cache the typed result *after* decoding instead.

```
View (Flutter Widget)
  |  watches
  v
Riverpod StreamNotifier  (features/<feature>/presentation/)
  |  calls
  v
Repository interface    (features/<feature>/domain/)
  |  reads/writes (stale-while-revalidate)
  +──────────────────►  Drift table (local cache of decoded entities)
  |  on miss / revalidate
  v
RemoteDataSource / Dio  (features/<feature>/data/)
  |  HTTP
  v
Backend REST API
```

**Mandatory rules:**

1. Every read operation goes through the Repository, which queries Drift first and returns a `Stream` (or `Future`) of cached entities. The Repository then triggers a background network revalidation and upserts the result back into Drift — the stream re-emits automatically.
2. Cache **key** = logical operation ID + a stable hash of its parameters (e.g., `"todos"`, `"todo:$id"`). Never key on URLs or raw path strings.
3. Apply a **stale-while-revalidate** policy: emit the locally-cached rows immediately (instant render), then fetch from the network, upsert into Drift, and let the stream re-emit the fresh rows. Store an explicit `cachedAt` timestamp column; check it against a per-resource TTL before deciding to revalidate.
4. Any **write** (create / update / delete) must upsert or delete the affected Drift rows after a successful network response, so the next stream emission reflects the change immediately without a separate read round-trip.
5. Drift is for transient **server-owned** data caches (and optionally durable user-owned data). **Secrets** (tokens, credentials) still belong in `flutter_secure_storage`. Do not use the cache table as a system of record for user-authored drafts — use a separate Drift table with a different retention policy.

See `snippets.md §3` for the canonical offline-first repository and `snippets.md §4` for the Riverpod `StreamNotifier` consuming it.

## Local Storage

| Library | Purpose |
|---------|---------|
| `drift` | Durable structured persistence (system-of-record user data **and** the offline response cache table) |
| `flutter_secure_storage` | Tokens, credentials, and secrets |
| `shared_preferences` | Lightweight key-value preferences (theme, locale, flags) |
| `hive` / `hive_flutter` | Lightweight alternative to Drift for simple caches where SQL is unnecessary |

**Drift vs Hive for the cache table:** Drift is the default because it provides SQL queries, type-safe DAOs, and Dart `Stream`s that auto-emit on row changes — exactly what the stale-while-revalidate pattern needs. Use Hive when the cached type is a simple flat object and you want to avoid the Drift codegen dependency. Either way, the Repository interface is unchanged; only the impl swaps out. This stack uses Drift (`response_cache: drift-offline-repo`).

## Testing

| Layer | Framework |
|-------|-----------|
| Unit (domain + repository) | `flutter_test` + `mocktail` |
| Widget | `flutter_test` (`WidgetTester`) |
| Integration | `integration_test` package |
| E2E | Maestro (`maestro test`) |

Mock the `Repository` **interface** (abstract class), not the concrete implementation or Dio. `mocktail` stubs are preferred over hand-written fakes for brevity, but both are acceptable. Never mock Drift internals — test the real Drift DB in-memory (`NativeDatabase.memory()`) for repository-layer tests.

Run tests with `flutter test` (unit + widget) and `flutter test integration_test/` (integration). Maestro `.yaml` flow files live in `maestro/` at the project root; see `snippets.md §11` for a runnable launch → add → assert flow.

## Project Layout

```
my_app/
  pubspec.yaml                            # deps + build_runner config
  pubspec.lock
  build.yaml                              # build_runner options (riverpod_generator, drift)
  maestro/                                # Maestro E2E flow files
    todos_flow.yaml
  lib/
    main.dart                             # runApp entry; ProviderScope at root
    core/
      di/
        providers.dart                    # App-wide singleton providers (Dio, DB, SecureStorage)
      network/
        dio_client.dart                   # Dio factory + AuthInterceptor + RetryInterceptor (all in one file; see §5)
      database/
        app_database.dart                 # Drift @DriftDatabase definition
        app_database.g.dart               # generated
      router/
        app_router.dart                   # GoRouter typed routes
        app_router.g.dart                 # generated (go_router_builder)
      theme/
        app_theme.dart
    features/
      todos/
        domain/
          todo.dart                       # Domain entity (freezed or plain Dart)
          todo_repository.dart            # Abstract repository interface
        data/
          dtos/
            todo_dto.dart                 # JSON <-> entity mapping
          local/
            todos_dao.dart                # Drift DAO for todos cache table
            todos_dao.g.dart              # generated
          remote/
            todos_remote_data_source.dart # Dio calls
          todo_repository_impl.dart       # Offline-first impl; cache + remote
        presentation/
          providers/
            todos_provider.dart           # @riverpod StreamNotifier
            todos_provider.g.dart         # generated
          screens/
            todos_screen.dart
            todo_detail_screen.dart
          widgets/
            todo_list_item.dart
    shared/
      widgets/
        loading_indicator.dart
        empty_state.dart
        error_view.dart
  test/
    features/
      todos/
        todo_repository_impl_test.dart    # in-memory Drift DB
        todos_provider_test.dart          # mocked repository interface
        todos_screen_test.dart            # WidgetTester
  integration_test/
    todos_integration_test.dart
```

## Architecture Pattern

```
todos_screen.dart  (ConsumerWidget)
  |  ref.watch(todosProvider)
  v
todosProvider  (@riverpod StreamNotifier<List<Todo>>)
  |  ref.watch(todoRepositoryProvider)
  v
TodoRepository  (abstract interface in domain/)
  |  watchAll() · findById(id) · create(title) · toggle(id) · delete(id)
  |  implemented by TodoRepositoryImpl (data/)
  |
  +──── TodosDao (Drift)  ◄──────── local cache of decoded Todo entities
  |       Stream<List<TodosTableData>> watchAll()
  |       Future<TodosTableData?> findById(int id)
  |       Future<void> replaceAll(List<TodosTableCompanion>)   // mirrors full server list
  |       Future<void> upsertOne(TodosTableCompanion)
  |       Future<void> deleteById(int id)
  |
  +──── TodosRemoteDataSource (Dio)
          Future<List<TodoDto>> fetchAll()
          Future<TodoDto> fetchById(int id)
          Future<TodoDto> create(String title)
          Future<TodoDto> toggle(int id)
          Future<void> delete(int id)
```

Each `features/<name>/` folder is a vertical slice owning its domain, data, and presentation sub-layers. `shared/` holds stateless reusable widgets with no feature knowledge. `core/` holds app-wide infrastructure (Dio, Drift DB, GoRouter, DI providers).

The `@riverpod` notifier calls the repository directly — there is no use-case/interactor layer in this stack. Add a `usecases/` class only when a single user action coordinates multiple repositories or carries non-trivial orchestration logic; a straight pass-through to one repository method does not warrant one.

<!-- oma-docs:ignore-start -->
**Sanctioned layering exception (Drift).** `core/database/app_database.dart` imports the feature DAOs (e.g. `features/todos/data/local/todos_dao.dart`) to register them on `@DriftDatabase(daos: [...])`. This is a `core → features` upward import, the reverse of the normal dependency direction. It is the single allowed exception: Drift requires the database class to reference its tables and DAOs for code generation. No other `core` code may import from `features/`.
<!-- oma-docs:ignore-end -->

## Navigation: GoRouter with Typed Routes

<!-- oma-docs:ignore-start -->
`go_router` 17.x with `go_router_builder` (typed route classes generated at build time via `build_runner`) is the navigation layer. Define route classes annotated with `@TypedGoRoute`; the generator emits `.g.dart` files with `push()` / `go()` helpers. `go_router_builder` is a dev-only builder — the `@TypedGoRoute` annotation and `GoRouteData` base class are imported from `package:go_router/go_router.dart`, never from `go_router_builder`.
<!-- oma-docs:ignore-end -->

Route guards (auth checks, onboarding redirects) are handled by `GoRouter.redirect` callbacks, not inside screens. Deep links are declared in `GoRoute.path` and handled by the platform-level `AndroidManifest.xml` / `Info.plist` intent filters.

See `snippets.md §2` for the typed GoRouter setup.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall