ADR — universal Expo client + OpenAPI contract #177

New issue

Closed

opened 2026-06-20 15:43:35 +00:00 by james · 0 comments

james commented

2026-06-20 15:43:35 +00:00

Owner

Write the architectural decision record for splitting the frontend off the Next.js process onto a universal Expo Router + React Native Web client, with an OpenAPI-contracted API as the only sanctioned boundary between the two.

The rest of the work in #176 follows from this decision being recorded.

Scope

New ADR docs/adr/0027-frontend-backend-split-and-universal-client.md (or the next free number), following the format from ADR-0001.
Decision: pick Expo Router + RN Web over Flutter, Tauri, and Capacitor — record the tradeoffs the way ADR-0003 (Kysely) and ADR-0012 (TanStack) do.
Architecture-in-prose: Next.js = API + static fallback; Expo Web = PWA; Expo Native = Android + Linux Flatpak shell; OpenAPI = the wire.
Note which existing ADRs this supersedes (0025 i18n runtime), extends (0004 sessions, 0015 OAuth2), or reaffirms (0012 TanStack, 0023 DS tokens, 0018 storage).
Update CLAUDE.md "Shape of the system" to describe the split (Next.js = API, Expo = universal client, OpenAPI = contract).
Update idea.md to match.

Acceptance criteria

ADR-0027 written and merged.
CLAUDE.md "Shape of the system" reflects the split.
idea.md reflects the split.
Affected ADRs (0004, 0015, 0025) carry a "Superseded by 0027" or "Extended by 0027" header note where appropriate.

Out of scope

Any implementation. Decision document only.

Composes with

ADR-0001, ADR-0004, ADR-0012, ADR-0015, ADR-0023, ADR-0025.

Part of

#176

Write the architectural decision record for splitting the frontend off the Next.js process onto a universal **Expo Router + React Native Web** client, with an **OpenAPI-contracted API** as the only sanctioned boundary between the two. The rest of the work in #176 follows from this decision being recorded. ## Scope - New ADR `docs/adr/0027-frontend-backend-split-and-universal-client.md` (or the next free number), following the format from ADR-0001. - Decision: pick Expo Router + RN Web over Flutter, Tauri, and Capacitor — record the tradeoffs the way ADR-0003 (Kysely) and ADR-0012 (TanStack) do. - Architecture-in-prose: Next.js = API + static fallback; Expo Web = PWA; Expo Native = Android + Linux Flatpak shell; OpenAPI = the wire. - Note which existing ADRs this **supersedes** (0025 i18n runtime), **extends** (0004 sessions, 0015 OAuth2), or **reaffirms** (0012 TanStack, 0023 DS tokens, 0018 storage). - Update `CLAUDE.md` "Shape of the system" to describe the split (Next.js = API, Expo = universal client, OpenAPI = contract). - Update `idea.md` to match. ## Acceptance criteria - [ ] ADR-0027 written and merged. - [ ] `CLAUDE.md` "Shape of the system" reflects the split. - [ ] `idea.md` reflects the split. - [ ] Affected ADRs (0004, 0015, 0025) carry a "Superseded by 0027" or "Extended by 0027" header note where appropriate. ## Out of scope - Any implementation. Decision document only. ## Composes with ADR-0001, ADR-0004, ADR-0012, ADR-0015, ADR-0023, ADR-0025. ## Part of #176

james added the

area:service

label

2026-06-20 15:45:17 +00:00

james referenced this issue from a commit

2026-06-20 16:12:23 +00:00

docs(adr): adopt ADR-0027 for frontend/backend split (#177)

james referenced this issue from a pull request that will close it,

2026-06-20 16:12:41 +00:00

docs(adr): adopt ADR-0027 for frontend/backend split (#177) #189

james referenced this issue from a commit

2026-06-20 16:16:31 +00:00