Architecture Overview

VAssist uses a unique dual-mode architecture that allows the same codebase to run as both a standalone web app and a Chrome extension.

Two Modes, Same Code

VAssist runs in two distinct modes that share 95% of the same code:

Demo Mode (Standalone Web App)

Characteristics:

Lives at the demo URL as a standard React app
Makes direct API calls to AI services
Hot reload for fast development
Perfect for quickly testing features
Simpler architecture without extension constraints

Use Cases:

Feature development and testing
UI/UX experimentation
Quick demos and prototypes

Extension Mode (Chrome Extension)

Characteristics:

Injects into any website as a Chrome extension
Uses message passing between isolated contexts
Shadow DOM for complete CSS isolation
Multi-tab support with per-tab state management
Manifest V3 architecture

Use Cases:

Production usage on any website
Multi-tab scenarios
Privacy-focused local AI processing
Integration with host page content

Shared Components (95%)

These directories contain code that works identically in both modes:

src/
├── components/     # All React UI components
├── babylon/        # All 3D rendering (Babylon.js)
├── config/         # Configuration files
├── utils/          # Utility functions
├── contexts/       # React contexts
├── hooks/          # React hooks
└── styles/         # CSS and styling

Components in src/components/ automatically work in both demo and extension modes without modification.

Mode-Specific Code (5%)

Demo Mode: Direct API Calls

src/services/       # Direct service implementations
├── AIService.js           # Direct OpenAI/API calls
├── TTSService.js          # Direct TTS API calls
└── StorageManager.js      # localStorage/IndexedDB

Extension Mode: Message Passing

extension/
├── manifest.json          # Extension configuration
├── background/            # Service worker
│   ├── index.js          # Message handlers
│   ├── TabManager.js     # Per-tab state
│   └── BackgroundBridge.js
├── content/               # Content script
│   ├── index.js          # Injection logic
│   └── ContentBridge.js  # Message bridge
├── offscreen/             # Heavy processing
│   └── offscreen.js      # Audio/Kokoro TTS
└── shared/                # Shared utilities
    └── MessageBridge.js   # Base message class

Smart Proxies

Proxies in src/services/proxies/ automatically detect the environment and route calls:

// Automatically routes to demo or extension implementation
import aiService from './services/proxies/AIServiceProxy';

// Works in both modes!
await aiService.sendMessage(messages);

How it works:

Detects if running in extension context (chrome.runtime exists)
Routes to background service worker (extension mode)
Or routes to direct service implementation (demo mode)

Project Structure

Main Source (`src/`)

src/
├── components/
│   ├── VirtualAssistant.jsx    # Main app component
│   ├── SettingsPanel.jsx       # Settings UI
│   ├── setup/                  # Setup wizard
│   ├── settings/               # Settings panels
│   ├── toolbar/                # Toolbar components
│   └── common/                 # Shared UI components
│
├── babylon/                    # 3D rendering engine
│   ├── MMDModelScene.js       # Main 3D scene
│   └── AnimationManager.js    # Animation control
│
├── services/
│   ├── AIService.js           # AI chat service
│   ├── TTSService.js          # Text-to-speech
│   ├── STTService.js          # Speech-to-text
│   ├── TranslatorService.js   # Translation
│   └── proxies/               # Mode routing
│
├── managers/
│   ├── ChatManager.js         # Chat state management
│   └── StorageManager.js      # Data persistence
│
├── config/
│   ├── aiConfig.js            # AI provider configs
│   ├── animationConfig.js     # Animation mappings
│   └── uiConfig.js            # UI defaults
│
└── workers/
    ├── AudioWorkerClient.js   # Audio processing
    └── shared/                # Shared processing cores
        ├── VMDGenerationCore.js    # Lip sync generation
        ├── KokoroTTSCore.js        # Kokoro TTS engine
        └── BVMDConversionCore.js   # Animation format

Extension-Specific (`extension/`)

extension/
├── manifest.json              # Extension metadata
│
├── background/                # Service worker (persistent)
│   ├── index.js              # Main entry point
│   ├── BackgroundBridge.js   # Message routing
│   ├── TabManager.js         # Per-tab state
│   └── OffscreenManager.js   # Offscreen document control
│
├── content/                   # Content script (per-page)
│   ├── index.js              # Injection logic
│   ├── main.jsx              # React entry point
│   └── ContentBridge.js      # Message bridge
│
├── offscreen/                 # Offscreen document
│   ├── offscreen.html        # Minimal HTML
│   └── offscreen.js          # Heavy processing
│
└── shared/                    # Shared utilities
    ├── MessageTypes.js       # Message type constants
    └── MessageBridge.js      # Base message class

Static Assets (`public/`)

public/
└── res/
    └── assets/
        ├── model/             # 3D character models (.bpmx)
        └── motion/            # Animations (.bvmd)

Key Technologies

Frontend Framework

React 19 - UI components and state management
Tailwind CSS 4 - Styling with Shadow DOM support
Vite (Rolldown) - Lightning-fast build tool

3D Graphics

Babylon.js 8 - WebGL rendering engine
babylon-mmd - MMD model and animation support
Havok Physics - Physics simulation

AI & Processing

OpenAI SDK - GPT and TTS API integration
Transformers.js - On-device AI (Kokoro TTS)
Chrome AI APIs - Built-in browser AI features

Data Storage

Dexie.js - IndexedDB wrapper for large data
chrome.storage - Extension storage API
localStorage - Simple key-value storage

Architecture Principles

1. Maximum Code Reuse

95% code sharing between modes means:

Features work everywhere by default
Single codebase to maintain
Consistent behavior across modes

2. Context Isolation

Extension mode uses multiple isolated contexts:

Main World: React app with full DOM access
Content Script: Isolated bridge between worlds
Background Worker: Persistent service handler
Offscreen Document: Heavy processing with AudioContext

3. Message-Based Communication

All inter-context communication uses structured messages:

{
  type: 'AI_SEND_MESSAGE',
  requestId: 'unique-id',
  data: { messages: [...] },
  timestamp: Date.now()
}

4. Per-Tab State Management

Each browser tab gets isolated state:

Independent chat histories
Separate AI sessions
Isolated abort controllers
Automatic cleanup on tab close

5. Progressive Enhancement

Works with minimal permissions
Gracefully degrades without APIs
Optional features (TTS, STT, Chrome AI)
Fallback to basic functionality

Performance Considerations

Code Splitting

Heavy dependencies loaded on-demand
Separate bundles for demo vs extension
Web Workers for parallel processing

Memory Management

Per-tab resource cleanup
Automatic inactive tab cleanup (1 hour)
Model caching in IndexedDB
Explicit abort controller cleanup

Build Optimization

Vite (Rolldown) for fast builds
Tree-shaking unused code
Minification and compression
Source maps for debugging

Next Steps

Extension Architecture - Deep dive into extension mode
Contributing Guide - Start contributing to VAssist
AI Toolbar - Explore VAssist capabilities

​Two Modes, Same Code

​Demo Mode (Standalone Web App)

​Extension Mode (Chrome Extension)

​Code Sharing Strategy

​Shared Components (95%)

​Mode-Specific Code (5%)

​Demo Mode: Direct API Calls

​Extension Mode: Message Passing

​Smart Proxies

​Project Structure

​Main Source (src/)

​Extension-Specific (extension/)

​Static Assets (public/)

​Key Technologies

​Frontend Framework

​3D Graphics

​AI & Processing

​Data Storage

​Architecture Principles

​1. Maximum Code Reuse

​2. Context Isolation

​3. Message-Based Communication

​4. Per-Tab State Management

​5. Progressive Enhancement

​Performance Considerations

​Code Splitting

​Memory Management

​Build Optimization

​Next Steps

Two Modes, Same Code

Demo Mode (Standalone Web App)

Extension Mode (Chrome Extension)

Code Sharing Strategy

Shared Components (95%)

Mode-Specific Code (5%)

Demo Mode: Direct API Calls

Extension Mode: Message Passing

Smart Proxies

Project Structure

Main Source (`src/`)

Extension-Specific (`extension/`)

Static Assets (`public/`)

Key Technologies

Frontend Framework

3D Graphics

AI & Processing

Data Storage

Architecture Principles

1. Maximum Code Reuse

2. Context Isolation

3. Message-Based Communication

4. Per-Tab State Management

5. Progressive Enhancement

Performance Considerations

Code Splitting

Memory Management

Build Optimization

Next Steps