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
Multilingual Agent Strategy Jan 2026 Approved
Vapi.ai Integration Architecture Jan 2026 Approved
EMR Abstraction Layer Jan 2026 Approved

Decision Summary

Multilingual Agent: ONE Agent Per Clinic

Decision: Use a single multilingual Vapi.ai assistant per clinic with auto-language detection, rather than separate agents per language.

Rationale:

  • Deepgram Nova-2 "multi" mode auto-detects English/Mandarin
  • Eliminates IVR language selection ("Press 1 for English...")
  • Supports mid-conversation language switching (common in BC)
  • 5x fewer assistants to manage (1 vs 5 per clinic)

Dedicated Agent Per Language (Rejected Alternative)

Rejected: Creating 3+ language-specific agents per clinic.

Why rejected:

  • 3x configuration burden
  • 200-500ms transfer latency between agents
  • Poor UX for bilingual patients
  • No architectural benefit for v1.0 use cases

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