Lazurite#

Host Selection#

Host selection is a first-class concern:

1. Unauthenticated, public reads (fast path)

   • Base URL: https://public.api.bsky.app
   • Use for: browsing without login (profiles, public feeds, threads, search)

2. Authenticated requests (normal logged-in mode)

   • Base URL: the user's PDS (discovered from identity resolution)
   • Why: authenticated requests are "usually made to the user's PDS, with automatic service proxying"

3. Service proxying (chat + some services)

   • Make the request to the user's PDS, and set the service proxy header to target the downstream service
   • Bluesky chat endpoints require proxying to did:web:api.bsky.chat

Endpoint Map by Feature#

Identity + Sessions#

Core Reading#

Notifications#

Writing (Posts, Likes, Reposts, Follows)#

Collections used with createRecord/putRecord/deleteRecord:

• Post: app.bsky.feed.post
• Like: app.bsky.feed.like
• Repost: app.bsky.feed.repost
• Follow: app.bsky.graph.follow

DMs (Bluesky Chat via PDS proxy)#

Implementation note: The "proxying header" mechanism is standardized in XRPC HTTP specs; implement it once in Dio as an interceptor/RequestOptions hook, then reuse.

Local-only Features#

"Smart" folders#

• Definition: locally stored queries over cached timeline/threads + local labels
• Example folder rules: "Unread", "From follows only", "Mentions + keyword", "Media only", "Saved"
• Inputs (network): whatever you choose to cache (timeline/author feed/thread/etc.)
• Output: purely local projection; no server-side "custom feed generator" required

Local post drafts#

• Stored in Drift only; not published until you call repo.createRecord/applyWrites

Why go_router?#

• URL-based navigation (deep links, shareable routes, desktop parity)
• Nested navigation with persistent tab state
• Auth gating via redirect()
• Path + query parameters, nested routes, and redirection support

Router Shape#

Use StatefulShellRoute.indexedStack for bottom tabs so each tab preserves state (scroll position, nested stacks).

Tabs (StatefulShellRoute branches):

• Home
• Search
• Notifications
• DMs
• Profile (Me)

Rules:

• Put "detail" routes (thread, profile, convo) as children of the branch where the user is coming from, so the bottom bar stays visible
• Put "global modals" (compose, settings) on the root navigator so they present above tabs

Route Map#

About :postKey: Don't put raw at://did/... in the path. Encode it as a URL-safe token (base64url(atUri) or percent-encode into a query param like /home/t?uri=...).

Auth Gating + Reactive Redirects (Riverpod)#

go_router redirects are not automatically reactive; you must provide a refreshListenable if you want auth changes to trigger redirects reliably.

Pattern (opinionated, reliable):

• Auth state lives in Riverpod (e.g., AuthController Notifier)
• Create a small Listenable bridge for GoRouter.refreshListenable:
  • ValueNotifier<int> "tick"
  • ref.listen(authProvider, (_, __) => tick.value++)
• In redirect(), read auth state and return:
  • unauthenticated → /login for protected routes
  • authenticated → redirect away from /login to /home

Protected vs public routes:

• Public allowed: /home (read-only), /search, viewing threads/profiles
• Auth required: /notifs, /dms, /compose publish, follow/like/repost actions

Deep Linking (Android/iOS)#

• Use go_router URL paths that mirror shareable content
• Configure Android App Links + iOS Universal Links so https://<yourdomain>/... can open the app to a matching route
• Prefer path params for required IDs; query params for optional filters/search

Why Riverpod?#

• Dependency injection (Dio clients, DB, repositories)
• View-model state (timeline paging, thread loading, draft autosave, DM outbox)
• Flutter's architecture guide recommends separation of concerns and "Views + ViewModels" with repositories in the data layer
• Riverpod recommends (Async)Notifier/(Async)NotifierProvider for state that changes via user interaction

Provider Types#

Dependencies (singletons / resources):

• Provider<AppDb> (Drift DB)
• Provider<Dio> dioPublic
• Provider<Dio> dioPds
• Provider<AuthSessionStore> (secure storage-backed)
• Provider<EndpointMap> (single source of routing truth)

Repositories (data layer):

• Provider<TimelineRepository>
• Provider<ThreadRepository>
• Provider<DmRepository>
• Provider<DraftRepository>

ViewModels (presentation layer):

• AsyncNotifierProvider<TimelineController, TimelineState>
• AsyncNotifierProvider<ThreadController, ThreadState>
• NotifierProvider<ComposerController, ComposerState> (sync + autosave)
• AsyncNotifierProvider<DmInboxController, DmInboxState>
• AsyncNotifierProvider<DmConvoController, DmConvoState>

Rule of thumb:

• Use AsyncNotifier when you do I/O (network/db) or have "loading/error/data"
• Use Notifier for purely local synchronous state (text fields + local draft), while persisting via a repository

File Placement#

lib/src/app/providers.dart
  - global providers for env, dio, db, secure storage, endpoint map

lib/src/infrastructure/...
  - pure Dart classes: XrpcClient, interceptors, DAOs (no Riverpod here)

lib/src/features/<feature>/presentation/<feature>_controller.dart
  - Notifier/AsyncNotifier implementation
  - holds paging cursors, refresh logic, optimistic UI, etc.

lib/src/features/<feature>/domain/usecases/
  - optional: thin usecases called by controllers, especially for complex flows
    (publish draft pipeline, DM outbox flush)

Testing Conventions#

• Unit test controllers with ProviderContainer:
  • Override repositories with fakes
  • Assert state transitions: loading → data, optimistic updates, retry behavior
• DAO tests run against an in-memory/temporary Drift database
• Network tests mock Dio adapters (or replace XrpcClient in providers)

Principles#

• Use stable keys (DID, at:// URIs)
• Store raw JSON payloads for forward compatibility, plus minimal indexed columns
• Keep auth secrets out of Drift; store them in secure storage

Core Cache Tables#

DMs#

Smart Folders#

Drafts#