VoiceAssist V2 - Architecture Documentation

Last Updated: 2025-11-20 (Phase 7)

This directory contains comprehensive architecture documentation for VoiceAssist V2.

Quick Start

New to VoiceAssist? Start here:

1. UNIFIED_ARCHITECTURE.md - Comprehensive system architecture (START HERE)
2. ARCHITECTURE_DIAGRAMS.md - Visual diagrams (Mermaid)
3. SERVICE_CATALOG.md - Detailed service descriptions

Documentation Index

Core Architecture

Design Documents

Operations & Observability

Development

Architecture Overview

VoiceAssist V2 follows a progressive architecture strategy:

• Phases 0-7 (Current): Monorepo-first backend with Docker Compose
• Phases 8-14 (Future): Optional microservices with Kubernetes

Current Capabilities (Phase 7)

✅ JWT authentication with RBAC ✅ RAG-powered medical knowledge base ✅ Real-time WebSocket communication ✅ Nextcloud integration (CalDAV, WebDAV) ✅ Multi-level caching (L1 + L2) ✅ Comprehensive observability (Prometheus, Grafana) ✅ Admin panel with system monitoring ✅ Async background job processing

System Architecture (High-Level)

┌─────────────────────────────────────────────┐
│           Users (Web/Mobile)                 │
└─────────────────┬───────────────────────────┘
                  │
        ┌─────────┴──────────┐
        │                    │
┌───────▼────────┐  ┌────────▼───────────────┐
│  Nextcloud     │  │  VoiceAssist Backend   │
│  (Separate)    │◄─┤  - API Gateway         │
│  - Auth/SSO    │  │  - RAG Service         │
│  - Calendar    │  │  - Admin Service       │
│  - Files       │  │  - Integrations        │
└────────────────┘  └────────┬───────────────┘
                             │
                    ┌────────┴────────┐
                    │   Data Layer    │
                    │  - PostgreSQL   │
                    │  - Redis        │
                    │  - Qdrant       │
                    └─────────────────┘

For detailed diagrams, see ARCHITECTURE_DIAGRAMS.md.

Key Architecture Principles

1. Progressive Complexity: Start simple (monorepo), maintain boundaries, scale when needed
2. Security by Design: Zero-trust, HIPAA-compliant, audit everything
3. Observability First: Metrics, logs, tracing, dashboards, alerts
4. API-First Design: Standard envelope, typed errors, versioning
5. Performance Optimization: Multi-level caching, async processing

Technology Stack Summary

Backend: Python 3.11, FastAPI, SQLAlchemy, Pydantic Databases: PostgreSQL (pgvector), Redis, Qdrant AI/ML: OpenAI (embeddings + LLM) Integration: caldav, webdavclient3, httpx Observability: Prometheus, Grafana, (future: Jaeger, Loki) Infrastructure: Docker Compose (current), Kubernetes (future)

Reading Guide by Role

For New Developers

1. Read UNIFIED_ARCHITECTURE.md - System overview
2. Review ARCHITECTURE_DIAGRAMS.md - Visual understanding
3. Check SERVICE_CATALOG.md - Service responsibilities
4. Follow LOCAL_DEVELOPMENT.md - Setup instructions

For System Architects

1. Read UNIFIED_ARCHITECTURE.md - Complete architecture
2. Review BACKEND_ARCHITECTURE.md - Monorepo to microservices
3. Study ORCHESTRATION_DESIGN.md - RAG pipeline
4. Check SEMANTIC_SEARCH_DESIGN.md - Vector search

For Operations/DevOps

1. Read operations/SLO_DEFINITIONS.md - SLOs and error budgets
2. Review OBSERVABILITY.md - Monitoring patterns
3. Check UNIFIED_ARCHITECTURE.md - Deployment architecture
4. Study future K8s deployment in ARCHITECTURE_DIAGRAMS.md

For Security/Compliance

1. Read SECURITY_COMPLIANCE.md - HIPAA details
2. Review security architecture section in UNIFIED_ARCHITECTURE.md
3. Check audit logging in SERVICE_CATALOG.md
4. Review authentication flows in ARCHITECTURE_DIAGRAMS.md

Architecture Evolution Timeline

Related Resources

Code Repositories:

• Backend: /services/api-gateway/
• Tests: /services/api-gateway/tests/
• Infrastructure: /infrastructure/observability/

External Documentation:

• FastAPI Docs
• PostgreSQL pgvector
• Qdrant Docs
• Prometheus Best Practices

Contributing to Architecture Docs

When to Update:

• After completing a major phase
• After significant architectural changes
• After adding new services or components
• After infrastructure changes (new databases, observability)

Update Process:

1. Update UNIFIED_ARCHITECTURE.md first (canonical reference)
2. Update ARCHITECTURE_DIAGRAMS.md if visual changes
3. Update SERVICE_CATALOG.md if service changes
4. Update Implementation Status for component status changes
5. Create phase completion report in /docs/ (e.g., PHASE_XX_COMPLETION_REPORT.md)

Review Cycle:

• Minor updates: As needed during development
• Major reviews: After each phase completion
• Full audit: Every 3 phases (currently at Phase 7, next full audit at Phase 10)

Questions or Issues?

• Architecture Questions: Review UNIFIED_ARCHITECTURE.md first
• Service-Specific Questions: Check SERVICE_CATALOG.md
• Setup Issues: Follow LOCAL_DEVELOPMENT.md
• Bug Reports: Use issue tracker with architecture context

Document Version: 1.0 Last Updated: 2025-11-20 Maintained By: VoiceAssist Development Team Next Review: After Phase 10 completion