8.8 KiB
8.8 KiB
05 — Web App (Next.js) Map
Surface:
apps/webStack: 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 | <MicRecorder/> real-time record/STT |
(app)/commands |
client | Custom instruction CRUD/reorder/activate/execute |
(app)/dashboard |
client | Stats (sessions, time, words, streak), tier, recent history |
(app)/actions |
server | NL command → LLM parse → action (<ActionRunner/>) |
(app)/meetings |
server | Meetings list |
(app)/meetings/[id] |
server | Meeting detail: audio player, live transcript (Realtime), memos, generated docs |
(app)/knowledge |
server | RAG doc list + add + semantic search (search "planned V2-M+1") |
(app)/teams |
server | Teams list + create |
(app)/teams/[id] |
server | Team detail: members, owner-only invite, team meetings |
(app)/chat |
server | Talk AI chat (<ChatPanel/>) |
(app)/dictionary |
client | Pronunciation dictionary CRUD |
(app)/history |
client | History list: search, favorites, pagination, copy/delete |
(app)/history/[id] |
client | History detail: edit title/original/polished, favorite, delete |
(app)/billing |
client | Plans + Payple checkout/manage (Stripe removed 2026-09-26; legacy provider='stripe' rows shown read-only) |
(app)/layout.tsx is the auth guard + shared <Sidebar/>.
2. Components (src/components/)
| Group | Components |
|---|---|
actions/ |
action-runner.tsx (LLM parse → action: create_meeting/search_knowledge/create_memo/send_team_invite) |
record/ |
mic-recorder.tsx (MediaRecorder + level analyser → transcribeWebAudio) |
billing/ |
billing-checkout-options, payple-checkout-button, payple-client, payple-manage-button |
meetings/ |
document-editor (MarkdownPreview lazy-loaded client-only via next/dynamic), generate-document-button, live-transcript-list (Realtime + color-coded speaker badges & multi-speaker filter chips, 2026-11-13 GAP-MTG-02), markdown-preview (Mermaid loaded only when ```mermaid blocks exist; Wave 6 useId() + render-seq + replaceChildren <pre> 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 rootnpm 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 +/downloadhandoff),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/FIXMEmarkers; remaining smaller items (see11-gap-backlog.mdWEB-*):- Action runner team-invite uses a manual redirect safety path instead of a live invite (
action-runner.tsx). /downloadshows "artifact not yet published" when the feed lacks the current version.
- Action runner team-invite uses a manual redirect safety path instead of a live invite (
- Teams
member_countaggregation (team-client.ts), 12-localeLocaleSwitcher+I18nProviderpersistence, speaker badges/filter chips onLiveTranscriptList, 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
rechartsdependency. 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, onewebpushtoken, one pending outbox attempt, a completed drain, and adeliveredprovider 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 withdesign.mdv4 ("조용한 계기"): undefined--d3-text-inversereplaced with--d3-accent-ink, minimum font size raised to11px(0.6875rem),uppercaseand positiveletterSpacingremoved from Korean UI copy, rawmonospacereplaced withvar(--d3-font-mono), singlecomponent="h1"hierarchy enforced per route, and native form controls equipped with:focus-visiblerings and<label htmlFor>/aria-labelattributes.