rl-docs-hub

Home · Apps · rl-main-infra · todo_api · todo_mobile

---

Architecture

High-level Components

• UI/Navigation: go_router with routes:
  • /login (LoginPage)
  • /lists (ListsPage)
  • /lists/todo/:todoId (TodoEditorPage)
• State and DI: Riverpod providers generated via @riverpod
• Local persistence: Hive boxes (lists, todos, syncQueue, auth)
• Sync engine: SyncRepository + SyncCoordinator (connectivity-triggered flush)
• Auth: Auth0 WebAuth + secure token storage + biometric unlock
• Notifications: local reminder service + push gateway abstraction (NoopPushNotificationGateway default)

Auth + Routing Flow

flowchart TD
    A[App launch] --> B[GoRouter initialLocation=/login]
    B --> C[LoginPage: Continue with Auth0]
    C --> D[AuthRepository.login() via Auth0 WebAuth]
    D --> E[Store id_token in secure storage]
    E --> F[unlockWithBiometrics()]
    F -->|success| G[context.go('/lists')]
    F -->|fail| B

Data + Sync Architecture

flowchart LR
    UI[Pages / Widgets] --> RP[Riverpod Providers]
    RP --> LR[ListsRepository / TodosRepository]
    LR --> H[(Hive boxes)]
    RP --> SR[SyncRepository]
    SR --> Q[(syncQueue)]
    SR --> GQL[GraphQLClient]
    GQL --> API[(GraphQL endpoint)]
    NET[Connectivity events] --> SC[SyncCoordinator]
    SC --> SR

Offline-first Behavior

1. User actions update local entities first (TodoList, TodoItem).
2. Sync payloads are queued as SyncJob entries.
3. SyncCoordinator listens to connectivity changes.
4. On reconnection, syncAll() pushes queued mutations and removes successful jobs.
5. Conflict handling strategy is runtime-configurable:
   • serverWins
   • clientWins (replay with force: true)
   • manualMerge via injectable hook.

Current Gaps / Integration Expectations

• GraphQL client currently has no auth link for bearer token injection.
• Reminder scheduling API currently uses immediate show path (not zoned schedule yet).
• Push gateway is intentionally abstracted and still noop in this repo.