2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"] 4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""] 5:I[4126,[],""] 7:I[9630,[],""] 8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"] 9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"] a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"] b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"] 3:T2848, # VoiceAssist Frontend Architecture **Last Updated**: 2025-12-03 **Status**: Production Ready (Phases 0-3.5 Complete, Web App and Admin Panel stable) **Detailed Spec**: [client-implementation/TECHNICAL_ARCHITECTURE.md](client-implementation/TECHNICAL_ARCHITECTURE.md) --- ## Overview VoiceAssist uses a **pnpm monorepo with Turborepo** for build orchestration. All frontend applications share common packages for consistency, type safety, and code reuse. ### Quick Facts | Aspect | Technology | | ----------------- | ------------------------------ | | Package Manager | pnpm 8+ | | Build System | Turborepo | | UI Framework | React 18+ | | Language | TypeScript (strict mode) | | Bundler | Vite (apps), Rollup (packages) | | State Management | Zustand | | Styling | Tailwind CSS | | Component Library | shadcn/ui + custom | --- ## Architecture Diagram ``` ┌─────────────────────────────────────────────────────────────┐ │ apps/ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ web-app │ │ admin-panel │ │ docs-site │ │ │ │ (Vite) │ │ (Vite) │ │ (Next.js 14) │ │ │ │ │ │ │ │ │ │ │ │ User-facing │ │ Admin ops │ │ Documentation │ │ │ │ medical AI │ │ dashboard │ │ & guides │ │ │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │ │ │ │ │ │ │ └─────────────────┼────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ packages/ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │ │ │ │ ui │ │ types │ │ utils │ │ api- │ │ │ │ │ │ │ │ │ │ │ │ client │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ config │ │telemetry │ │ design- │ │ │ │ │ │ │ │ │ │ tokens │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend (FastAPI) │ │ services/api-gateway/ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Applications ### 1. Web App (`apps/web-app/`) Main user-facing medical AI assistant application. **Features:** - **Unified Chat/Voice Interface** (NEW) - Seamless text and voice mode in single view - Medical knowledge retrieval with citations - Document upload and management - Conversation history with branching - PHI-safe data handling **Key Components:** | Component | Path | Purpose | | ---------------------- | ------------------------------ | --------------------------------------------------- | | UnifiedChatContainer | `src/components/unified-chat/` | Three-panel layout with sidebar, main, context pane | | CollapsibleSidebar | `src/components/unified-chat/` | Conversation list with pinning and search | | UnifiedInputArea | `src/components/unified-chat/` | Text/voice mode toggle | | CollapsibleContextPane | `src/components/unified-chat/` | Citations, clinical context, branches | **Entry Point:** `src/main.tsx` **Dev Port:** 5173 **Documentation:** See [UNIFIED_CHAT_VOICE_UI.md](./UNIFIED_CHAT_VOICE_UI.md) ### 2. Admin Panel (`apps/admin-panel/`) System administration and monitoring dashboard. **Features:** - Real-time system metrics - User management (RBAC) - Knowledge base administration - Feature flag management - Audit log viewer **Entry Point:** `src/main.tsx` **Dev Port:** 5174 ### 3. Docs Site (`apps/docs-site/`) Documentation website built with Next.js 14. **Features:** - Markdown documentation rendering - Navigation from `navigation.ts` config - Support for docs from multiple locations (`@root/` prefix) - Search functionality (planned) **Entry Point:** `src/app/layout.tsx` **Dev Port:** 3000 --- ## Shared Packages | Package | Purpose | Key Exports | | ---------------------------- | --------------------------- | ----------------------------------------- | | `@voiceassist/ui` | React component library | Button, Input, Card, ChatMessage, etc. | | `@voiceassist/types` | TypeScript type definitions | API types, User, Session, Message, etc. | | `@voiceassist/utils` | Utility functions | PHI detection, formatters, validators | | `@voiceassist/api-client` | HTTP client | Type-safe API calls, auto token injection | | `@voiceassist/config` | Shared configurations | ESLint, Prettier, Tailwind presets | | `@voiceassist/telemetry` | Observability | Error tracking, analytics helpers | | `@voiceassist/design-tokens` | Design system | Colors, typography, spacing tokens | --- ## Development Commands ```bash # Install dependencies pnpm install # Start all apps in dev mode pnpm dev # Start specific app pnpm --filter web-app dev pnpm --filter admin-panel dev pnpm --filter docs-site dev # Build all packages pnpm build # Run tests pnpm test # Type checking pnpm type-check # Lint pnpm lint # Storybook (component library) pnpm storybook ``` --- ## State Management **Zustand** is used for client-side state management. ```typescript // Store structure pattern interface AppStore { // Auth state user: User | null; token: string | null; // UI state sidebarOpen: boolean; theme: "light" | "dark"; // Actions login: (credentials: LoginCredentials) => Promise; logout: () => void; } ``` --- ## API Communication ### REST API Use `@voiceassist/api-client` for all backend calls: ```typescript import { apiClient } from "@voiceassist/api-client"; // Typed API call with auto-token injection const sessions = await apiClient.conversations.list(); const session = await apiClient.conversations.create({ title: "New Chat" }); ``` ### WebSocket Real-time communication for streaming responses: ```typescript import { useWebSocket } from "@/hooks/useWebSocket"; const { connect, send, messages } = useWebSocket("/ws"); // Send message send({ type: "chat", content: "Hello" }); // Receive streaming response messages.forEach((msg) => { if (msg.type === "assistant_chunk") { appendToResponse(msg.content); } }); ``` --- ## Key Design Patterns ### 1. Feature-based Organization ``` src/ ├── features/ │ ├── chat/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── services/ │ │ └── index.ts │ ├── auth/ │ └── admin/ ``` ### 2. Type-safe API Layer All API calls are typed end-to-end using shared types from `@voiceassist/types`. ### 3. PHI Protection Client-side PHI detection using `@voiceassist/utils`: ```typescript import { detectPHI, redactPHI } from "@voiceassist/utils"; if (detectPHI(userInput)) { // Warn user or apply redaction const safe = redactPHI(userInput); } ``` --- ## Related Documentation - **Detailed Architecture:** [client-implementation/TECHNICAL_ARCHITECTURE.md](client-implementation/TECHNICAL_ARCHITECTURE.md) - **Development Roadmap:** [client-implementation/CLIENT_DEV_ROADMAP.md](client-implementation/CLIENT_DEV_ROADMAP.md) - **Web App Specs:** [WEB_APP_SPECS.md](WEB_APP_SPECS.md) - **Admin Panel Specs:** [ADMIN_PANEL_SPECS.md](ADMIN_PANEL_SPECS.md) - **Component Library:** Run `pnpm storybook` to view --- ## Version History | Version | Date | Changes | | ------- | ---------- | --------------------------------------------------- | | 1.1.0 | 2025-12-03 | Updated status to Production Ready (Phase 3.5 done) | | 1.0.0 | 2025-11-27 | Initial architecture document | 6:["slug","FRONTEND_ARCHITECTURE","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","FRONTEND_ARCHITECTURE","c"],{"children":["__PAGE__?{\"slug\":[\"FRONTEND_ARCHITECTURE\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","FRONTEND_ARCHITECTURE","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"Frontend Architecture"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","FRONTEND_ARCHITECTURE.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/FRONTEND_ARCHITECTURE.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]] c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"Frontend Architecture | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Client applications architecture - pnpm monorepo with React, TypeScript, and shared packages."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]] 1:null