docs(website): cross-component blast-radius review + /api/mobile facade (Phase 0) #47

wtclaude · 2026-07-23T04:54:44Z

wtclaude commented

2026-07-23 04:54:44 +00:00

What & why

Expands the API v2 plan to account for consumers beyond the browser, and adds a decision made in review: stand up a version-agnostic /api/mobile facade before v2 so the Android app leaves the version-churn blast radius entirely.

The original plan was written as if the website were the whole world. It isn't — three independent clients consume the site API, and two live in separate repos on separate release cadences.

Changes

website/API_V2_PLAN.md

Cross-component blast radius section: inventories the three v1 consumers (browser = lockstep, Android app = ~70 hardcoded api/v1/… endpoints + SSE path + SSO URLs, Discord bot = env repoint) and maps the site↔link / site↔mobile contracts.
Two concrete plan bugs fixed:
- The public /public/shard/stream SSE must stay anonymous — logged-out browsers and the app's ShardStreamClient send no Authorization header; the original step 5 would have requireAuth-gated it and blacked out the public live boards. Only the admin stream moves to Bearer.
- The useShardFeed.js EventSource → fetch rewrite is scoped to the admin stream only.
New "Phase 0 — the mobile facade": a thin BFF at /api/mobile delegating to current controllers behind pinned wire shapes (contract tests), landed before v2 so the auth merge never touches the app. Must cover the app's entire surface and preserve the same auth middleware (a re-exposed admin route missing adminOnly = priv-esc).
link/ documented as out of scope — no PROTOCOL_VERSION bump; the admin-stream allowlist split is the only shared seam.
Resequenced PRs (Phase 0 first) and gated v1 retirement on the pre-facade app fleet aging out via an app-version floor, not the web client.

docs/android/PLAN.md

M11 milestone: migrate the app to /api/mobile (pure rename, no behavior change) + ship the app-version floor, cross-referenced with the website plan's Phase 0. Plus a path note at §6.

Key nuance (not oversold)

The facade does not make /api/v1 deletable on the web client's schedule — the pre-facade installed app still calls v1 until the version floor ages it out. What it buys: that becomes a one-time, behavior-free, pre-v2 cutover instead of the auth merge being hostage to the app fleet, and the app never migrates again.

Docs-only; no code changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

## What & why Expands the API v2 plan to account for **consumers beyond the browser**, and adds a decision made in review: stand up a **version-agnostic `/api/mobile` facade before v2** so the Android app leaves the version-churn blast radius entirely. The original plan was written as if the website were the whole world. It isn't — **three independent clients** consume the site API, and two live in separate repos on separate release cadences. ## Changes **`website/API_V2_PLAN.md`** - **Cross-component blast radius** section: inventories the three v1 consumers (browser = lockstep, **Android app** = ~70 hardcoded `api/v1/…` endpoints + SSE path + SSO URLs, Discord bot = env repoint) and maps the site↔link / site↔mobile contracts. - **Two concrete plan bugs fixed:** - The public `/public/shard/stream` SSE **must stay anonymous** — logged-out browsers *and* the app's `ShardStreamClient` send no `Authorization` header; the original step 5 would have `requireAuth`-gated it and blacked out the public live boards. Only the *admin* stream moves to Bearer. - The `useShardFeed.js` `EventSource → fetch` rewrite is scoped to the **admin stream only**. - **New "Phase 0 — the mobile facade":** a thin BFF at `/api/mobile` delegating to current controllers behind **pinned wire shapes** (contract tests), landed before v2 so the auth merge never touches the app. Must cover the app's *entire* surface and preserve the same auth middleware (a re-exposed admin route missing `adminOnly` = priv-esc). - **`link/` documented as out of scope** — no `PROTOCOL_VERSION` bump; the admin-stream allowlist split is the only shared seam. - **Resequenced PRs** (Phase 0 first) and gated v1 retirement on the *pre-facade app fleet* aging out via an app-version floor, not the web client. **`docs/android/PLAN.md`** - **M11** milestone: migrate the app to `/api/mobile` (pure rename, no behavior change) + ship the app-version floor, cross-referenced with the website plan's Phase 0. Plus a path note at §6. ## Key nuance (not oversold) The facade does **not** make `/api/v1` deletable on the web client's schedule — the pre-facade installed app still calls v1 until the version floor ages it out. What it buys: that becomes a **one-time, behavior-free, pre-v2 cutover** instead of the auth merge being hostage to the app fleet, and the app never migrates again. Docs-only; no code changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

wtclaude added 1 commit 2026-07-23 04:54:46 +00:00

docs(website): add cross-component blast-radius review + /api/mobile facade (Phase 0) 3eafaef97e

Expand the API v2 plan to account for consumers beyond the browser and
insulate the Android app from version churn before the v2 work begins.

- Inventory the three v1 API consumers (browser, Android app, Discord bot)
  and map the cross-component contracts (site<->link, site<->mobile).
- Fix two concrete plan bugs: the public shard SSE stream must stay
  anonymous (logged-out browsers and the app's ShardStreamClient send no
  auth header), and the useShardFeed fetch-rewrite is admin-stream-only.
- Add "Phase 0 - the mobile facade": a version-agnostic /api/mobile
  namespace (a thin BFF delegating to current controllers behind pinned
  wire shapes), landed before v2 so the auth merge never touches the app.
- Note link/ is essentially out of scope (no PROTOCOL_VERSION bump), with
  the admin-stream allowlist split as the only shared seam.
- Resequence PRs (Phase 0 first) and gate v1 retirement on the pre-facade
  app fleet aging out via an app-version floor, not the web client.
- Add M11 to docs/android/PLAN.md: migrate the app to /api/mobile + ship
  the app-version floor, cross-referenced with the website plan's Phase 0.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

whitlocktech approved these changes 2026-07-23 04:59:55 +00:00

whitlocktech merged commit 81f7d58fbe into main

2026-07-23 05:00:02 +00:00

whitlocktech deleted branch docs/api-v2-blast-radius-mobile-facade

2026-07-23 05:00:02 +00:00

whitlocktech referenced this issue from a commit

2026-07-23 05:00:03 +00:00

Merge pull request 'docs(website): cross-component blast-radius review + /api/mobile facade (Phase 0)' (#47) from docs/api-v2-blast-radius-mobile-facade into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#47