Skip to content

Architecture Decisions

Key technical decisions and their rationale

Overview

This section documents significant architectural decisions made during VitaraVox development. Each document follows the Architecture Decision Record (ADR) format.

Decision Records

Decision Date Status Version
Multilingual Agent Strategy Jan 2026, Updated Feb 2026 Updated v1.0 -> v3.0
Vapi.ai Integration Architecture Jan 2026, Updated Feb 2026 Updated v1.0 -> v3.0
EMR Abstraction Layer Jan 2026 Approved v1.4.0
OSCAR Schedule Deep Dive Feb 2026 Active v3.2.3
Booking Product Architecture (ADR-004) Feb 2026 Approved v3.2.4

Decision Summary

Vapi Integration: v1.0 -> v2.3.0 -> v3.0

Version Architecture Key Decision
v1.0 Single multilingual agent per clinic Simplicity first, minimal configuration
v2.0-v2.3.0 6-agent squad with auto-detect multilingual Specialized roles, inline confirmation, silent handoffs
v3.0 9-agent dual-track with explicit language gate Per-language STT/TTS, eliminates LLM language confusion

Multilingual Strategy: Auto-Detect -> Dual-Track

v1.0-v2.3.0: Single multilingual agent with Deepgram Nova-2 "multi" mode auto-detects English/Mandarin. Supports mid-conversation language switching.

v3.0: Explicit language gate in Router. Dedicated EN and ZH tracks with per-language STT (Deepgram nova-2 en/zh) and TTS (ElevenLabs/Azure). Eliminates LLM language confusion at the cost of mid-call language switching.

Rationale for v3.0 change:

  • GPT-4o occasionally output space-separated Chinese characters
  • Per-language Deepgram models outperform universal multi mode
  • Azure zh-CN-XiaoxiaoNeural provides native Mandarin voice quality
  • Monolingual prompts are simpler and shorter

EMR Abstraction Layer: Adapter Pattern

Decision: Implement an adapter pattern with IEmrAdapter interface, BaseEmrAdapter base class, and EMR-specific adapters (starting with OscarUniversalAdapter).

Rationale:

  • Decouples voice agent from OSCAR-specific code
  • Enables future EMR integrations (Oscar Pro, Telus Health, Juno)
  • Feature flags for controlled rollout (USE_EMR_ADAPTER)
  • Per-clinic EMR configuration via emr_type and emr_config columns

Direct OSCAR Integration (Rejected Alternative)

Rejected: Hardcoding OSCAR API calls throughout the codebase.

Why rejected:

  • Prevents multi-EMR support
  • Tight coupling makes testing difficult
  • No clean path to adding new EMR systems

Key Principles

  1. Simplicity First - Minimize moving parts for v1.0 pilot
  2. Latency Optimized - Target <800ms voice response
  3. Clinic Independence - Each clinic has isolated config and EMR connection
  4. Compliance Ready - Architecture supports PIPEDA/PHIPA requirements
  5. Language Accuracy (v3.0) - Per-language models over universal compromise