# 05 — Web App (Next.js) Map
> Surface: `apps/web`
> Stack: Next.js 15 App Router + React 19 + MUI (via `@d3ro/ui`) + Supabase
> Role: cloud console; the reference surface for server-shared data UX
---
## 1. Route tree (`src/app/`)
Root layout: `ThemeProvider → I18nProvider → AuthProvider`.
| Route | Type | Feature |
|---|---|---|
| `/` | server | Redirects: session → `/dashboard`, else `/login` (also `/login` when Supabase unconfigured) |
| `/login` | client | OAuth (Google/GitHub/Apple) + email/password |
| `/accept-invite` | client | Team invite acceptance (`?token=` → `team-accept`); stores pending token if logged out |
| `/download` | client | Download center + release history; desktop installers marked "release pending"; client SHA-256 verify tool |
| `/releases` | server | Re-exports `/download` |
| `/auth/callback` | route handler | OAuth code → session exchange |
| `(app)/record` | server | `
` XSS fix, `isConnected` check, `mermaidReady` reset on error), `meeting-audio-player` (signed URL), `memo-form` |
| `chat/` | `chat-panel.tsx` |
| `teams/` | `create-team-form`, `invite-member-form`, `activity-feed` (team notes + realtime), `team-card-grid` (renders real aggregated `member_count` with localized badge) |
| `knowledge/` | `add-knowledge-form` (text or `.txt`/`.md` file, newline-aware chunking, `embed-chunks` on submit), `knowledge-search` (semantic via `search-knowledge`) |
| `layout/` | `sidebar.tsx` (nav, theme selector, logout, i18n) + `locale-switcher.tsx` (12-locale selector across sidebar & login, 2026-11-13 `GAP-I18N-03`) + `web-push-control.tsx` (permission/subscription status and explicit opt-in/out switch; Wave 6 `mountedRef`/`activeUserIdRef`/`activeToggleSeqRef` + `runWebPushToggle` + `withWebPushTimeout` timeout/re-entry guards) |
| `providers/` | `auth-provider`, `i18n-provider` (persists locale in `localStorage` `d3ro.web.locale`, auto-detects browser language across all 12 locales, updates `document.documentElement.lang`), `theme-mode-context`, `theme-provider` |
---
## 3. Clients (`src/lib/`)
| File | Purpose |
|---|---|
| `billing-catalog.ts` | Parse/validate billing catalog (schema v1, pro/pro_plus, Payple KRW prices only) |
| `command-client.ts` | Custom instruction client (types, error codes, execute) |
| `dashboard-client.ts` | Dashboard snapshot loader |
| `dictionary-client.ts` | Dictionary CRUD/pagination/search + `serializeDictionary` / `parseDictionaryFile` / `importDictionaryFile` (JSON/CSV) |
| `history-client.ts` | History list/get/update/delete, revision-safe |
| `supabase-browser.ts` | Re-export `@d3ro/api-client/supabase-browser` |
| `supabase-server.ts` | Next `cookies()` wrapper |
| `team-client.ts` | Aggregates `team_members` rows into `TeamSummary.member_count` (`aggregateTeamsWithMemberCounts`, 2026-11-13; Wave 6 deduplicates `teamIds` and fails closed on `memberCountError`, `@d3ro/web` Vitest 9 files / 42 tests PASS; `dashboard/page.tsx` adds `mountedRef`/`requestSeqRef` stale-response guard) |
| `web-device.ts` | Stable browser installation identity + active `platform='web'` device lookup/create/check-in; revoked rows are never resurrected |
| `web-push.ts` | Web Push service-worker/VAPID subscribe/unsubscribe helper. Requires a valid active `deviceId`, persists only through register/unregister RPCs, rolls back a failed registration, re-registers an existing browser subscription before reporting it connected, and runs bounded server cleanup independently from local unsubscribe |
| `web-push-session.ts` | Production orchestration boundary used by the sidebar and logout: user-gesture permission → device registration → subscription, plus per-user disabled intent, fail-closed reconciliation, and non-blocking logout cleanup |
| `web-stt-client.ts` | Web STT via `stt-proxy`, 25 MB limit, `WebSttError` codes |
---
## 4. Tests
Two layers:
- **Vitest** (`apps/web/tests/`, `npm --prefix apps/web run test`, part of root `npm test`): pure-logic & SSR contracts — `billing-catalog`, `web-push` (device/RPC/rollback/reconciliation/logout, 17 cases), `web-stt-client`, `team-client` (3 cases), `locale-switcher` (3 cases), `live-transcript-speakers` (2 cases) — 6 files / 32 tests PASS.
- **Playwright** (`apps/web/e2e/`): `smoke.spec.ts` (unauthenticated surface + fail-closed redirects + `/download` handoff), `billing`, `payple-checkout`, `dashboard-dictionary-commands`, `history` (fixture-based browser journeys).
---
## 5. Web status summary
- Full App Router console: auth (email + OAuth), record/STT, history (list+detail), commands, actions, meetings (list+detail+docs), knowledge (add+search), teams (list+detail+invite), chat, dictionary, billing, download/releases.
- Backed by Supabase tables + Edge Functions (`stt-proxy`, `llm-proxy`, `team-invite`, `team-accept`, `payple-checkout`, `payple-manage`, `search-knowledge`, `generate-meeting-document`).
- No literal `TODO`/`FIXME` markers; remaining smaller items (see [`11-gap-backlog.md`](./11-gap-backlog.md) `WEB-*`):
- Action runner team-invite uses a manual redirect safety path instead of a live invite (`action-runner.tsx`).
- `/download` shows "artifact not yet published" when the feed lacks the current version.
- Teams `member_count` aggregation (`team-client.ts`), 12-locale `LocaleSwitcher` + `I18nProvider` persistence, speaker badges/filter chips on `LiveTranscriptList`, knowledge file upload, semantic search, dictionary import/export, and the team activity feed are implemented and unit-tested.
- **2026-11-04 Wave 4 hygiene:** Removed the unreferenced dashboard trend chart and the web `recharts` dependency. Web Push now has a production sidebar opt-in/out flow, stable web-device registration, device-bound register/unregister RPCs, disabled-intent reconciliation, bounded local/server cleanup, logout-independent sign-out, and a Docker-copied service worker. An isolated local browser run with ephemeral VAPID proved one active web device, one `webpush` token, one pending outbox attempt, a completed drain, and a `delivered` provider result; that result proves provider acceptance, not service-worker/browser receipt. A later production-standalone run built and served successfully but timed out during throwaway login navigation before the dashboard, so production-rendered 1440/390, accessibility-tree, hit-target, permission/subscription, and receipt gates remain open. No production secrets or deployment were changed.
- **2026-10-28 designpaca audit (`SHELL-15`):** All 15 routes and shared components aligned with `design.md` v4 ("조용한 계기"): undefined `--d3-text-inverse` replaced with `--d3-accent-ink`, minimum font size raised to `11px` (`0.6875rem`), `uppercase` and positive `letterSpacing` removed from Korean UI copy, raw `monospace` replaced with `var(--d3-font-mono)`, single `component="h1"` hierarchy enforced per route, and native form controls equipped with `:focus-visible` rings and `