[Epic] Local-first dev experience (unblock from missing live API)

[mattrace-gloo]

Summary

Priority epic — unblock mobile development without requiring every engineer to run Docker locally. On the Expo SDK 56 CNG (Android-only) baseline, developers point EXPO_PUBLIC_API_BASE_URL at a real Fluent API and sync into on-device SQLite. This epic documents the workflow and closes the local Docker My Work gap on the server side.

Pivot (2026-06): Mobile mock seed (#106) and offline auth bypass (#107) are descoped. Data arrives via syncAllData() from real APIs — not fake mobile fixtures.

Verify pass (2026-07): #108 docs complete and closed. #106/#107 descoped. Epic complete; fluent-api seeder (E2) remains optional follow-up outside this epic.

Sub-issues / deliverables

• Document local-only run workflow #108 — Local development workflow docs (hosted dev + local Docker)
• fluent-api — Local dev data seeder (project + chapter assignment for translator; Docker Postgres only) — optional E2 follow-up
• Local SQLite seed/fixtures for offline dev #106 — Descoped (mobile mock seed superseded)
• Mock-API / offline dev mode when EXPO_PUBLIC_API_BASE_URL unset #107 — Descoped (offline mock mode superseded; optional app-shell hardening tracked separately)

Two co-equal dev paths

Path	EXPO_PUBLIC_API_BASE_URL
Hosted dev	https://dev.api.fluent.bible
Local Docker	http://10.0.2.2:9999 (./fapi.sh up + db:init in fluent-api)

Web app: https://dev.app.fluent.bible

Dependency ordering

1. Document local-only run workflow #108 (E1) — Document both paths (unblocks team immediately for hosted dev) — done
2. fluent-api seeder (E2) — Populate My Work on local Docker stack (optional)
3. Optional — App-shell error when API unreachable (reduced Mock-API / offline dev mode when EXPO_PUBLIC_API_BASE_URL unset #107)

Unblocks feature epics (#115/#116/#117/#118) for UI development against real data.

Open dependencies

• Postgres read access to shared dev (inspection only)
• Hosted-dev login credentials (team to share)

Links

• fluent-api local stack: PR #187, fapi.sh
• Related: EAS/dev-client onboarding + prebuild docs #112 (onboarding consolidation)

[mattrace-gloo]

Epic pivot — local development workflow (not mobile mock seed)

After reviewing fluent-api on main (PR #187 local dev seeders + fapi.sh) and confirming hosted dev is live, this epic pivots:

We are NOT building mobile SQLite mock seed (#106) or offline auto-auth bypass (#107). The mobile app gets data via sync hydration from real APIs.

Two co-equal dev paths (switch via EXPO_PUBLIC_API_BASE_URL only)

Path	API URL	Use when
Hosted dev	https://dev.api.fluent.bible (same backend as Azure scribe-server-dev)	See shared remote data; no Docker
Local Docker	http://10.0.2.2:9999 after ./fapi.sh up + db:init	Seed your own Postgres; offline API work

Web app for login/testing: https://dev.app.fluent.bible

Revised deliverables

1. Document local-only run workflow #108 — Document local development workflow (both paths) — primary
2. NEW fluent-api issue — Local dev data seeder (project + chapter assignment for translator My Work on Docker only)
3. Local SQLite seed/fixtures for offline dev #106 / Mock-API / offline dev mode when EXPO_PUBLIC_API_BASE_URL unset #107 — Descoped (superseded by real APIs)
4. Optional — App-shell error when API URL unset/unreachable (reduced Mock-API / offline dev mode when EXPO_PUBLIC_API_BASE_URL unset #107 scope)

Dependencies

• Postgres read access to shared dev: done (inspection/debugging only)
• Hosted-dev login credentials: open (need team account; t@fluent.local is local Docker only)

Hosted dev already has rich data (100+ users, 297 projects, 27k+ assignments). My Work works once you have login creds.

[mattrace-gloo]

Epic delivery — PRs open

Phase 0 ticket hygiene is complete (#106/#107 closed, #108 updated, fluent-api#207 created).

Pull requests (awaiting merge)

Issue	Repo	PR
#108 — local development workflow docs	fluent-mobile	#136
fluent-api#207 — local dev project seeder	fluent-api	eten-tech-foundation/fluent-api#208
#137 — app shell API config/connectivity (optional, reduced #107)	fluent-mobile	#138

Verification status

• Automated gates: passed locally on all three branches (format:check, lint, typecheck, tests).
• Manual — hosted dev path: docs in PR [#108]: Document local development workflow #136 describe EXPO_PUBLIC_API_BASE_URL=https://dev.api.fluent.bible; requires team login credentials (still an open dependency on this epic).
• Manual — local Docker path: after PR [#205]: Extract shared account session helpers #208 merges, ./fapi.sh up + seeds → sign in as t@fluent.local / t@123456 → mobile sync should show GEN 1 in My Work.

Epic stays open until #108 + #207 are merged and manual smoke is confirmed. Close with Fixes #119 from a merge commit or follow-up comment once verified.

[mattrace-gloo]

Epic closeout

Delivered: fluent-mobile PR #136 — local development workflow docs (hosted dev + local Docker, sync hydration, no mobile mock seed).

Descoped / closed:

• fluent-api#207 + PR [#205]: Extract shared account session helpers #208 — automated project seeder not needed
• fluent-mobile#138 — optional app-shell hardening, closed without merge

Acceptance: Devs pick API via EXPO_PUBLIC_API_BASE_URL, sign in, sync. Local Docker My Work: web UI project setup or use hosted dev.

Closing epic — docs are the durable deliverable.

[mattrace-gloo]

Reopened: epic deliverable #108 still has open PR #136 awaiting merge. Per prior epic comment, this epic should stay open until #108 is merged and verified.