d3ro-voice/docs/map/05-web-app.md
Yun Chan 876e72ea2f
Some checks failed
ci / 정본·보안·린트·타입·테스트 (push) Failing after 18s
ci / 워크스페이스 빌드 검증 (push) Has been skipped
ci / 모바일 린트·타입·Jest (push) Successful in 45s
ci / Supabase Edge Functions + Cloudflare Worker (push) Successful in 22s
ci / .NET API 서버 테스트 (push) Successful in 11s
deploy-site / deploy (push) Successful in 44s
docs(wave7): record peer-swarm bug fixes, metrics, and map sync
2026-11-14 15:41:48 +09:00

9.8 KiB

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 <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)
edge-fetch.ts Shared Edge invoke URL builder (resolveSupabaseFunctionUrl), bounded timeout signal (createTimedAbortSignal), and unmount check (shouldExitAfterAwait) (Wave 7 2026-11-14)
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), security-and-lifecycle (Wave 7) — 10 files / 52 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 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 <label htmlFor> / aria-label attributes.
  • 2026-11-14 Wave 7 hardening (c68e81e, 4bf0f0d, post-v1.17.1): closed /app//evil, backslash, and control-char open redirects in web-app-url.ts (safeReturnPath) and public/sw.js; scrubbed OAuth callback error leakage (auth/callback/route.ts); centralized Edge invocation & bounded abort/unmount checks in src/lib/edge-fetch.ts across chat-panel.tsx (executeChatSendTurn), action-runner.tsx, payple-checkout-button.tsx, payple-manage-button.tsx, generate-document-button.tsx, document-editor.tsx, invite-member-form.tsx, and (app)/history routes; hardened auth-provider.tsx (bindAuthSession) and mic-recorder.tsx (acquireGuardedMediaStream). Added tests/security-and-lifecycle.test.ts (@d3ro/web Vitest 10 files / 52 tests PASS).