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

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

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:

Entry Point: src/main.tsx Dev Port: 5173 Documentation: See 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

Development Commands

# 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.

// 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<void>;
  logout: () => void;
}

API Communication

REST API

Use @voiceassist/api-client for all backend calls:

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:

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:

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
• Development Roadmap: client-implementation/CLIENT_DEV_ROADMAP.md
• Web App Specs: WEB_APP_SPECS.md
• Admin Panel Specs: ADMIN_PANEL_SPECS.md
• Component Library: Run pnpm storybook to view

Version History