2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"]
4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""]
5:I[4126,[],""]
7:I[9630,[],""]
8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"]
9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"]
a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"]
b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"]
3:T275e,
# 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](../UNIFIED_ARCHITECTURE.md)** - Comprehensive system architecture (START HERE)
2. **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** - Visual diagrams (Mermaid)
3. **[SERVICE_CATALOG.md](../SERVICE_CATALOG.md)** - Detailed service descriptions

---

## Documentation Index

### Core Architecture

| Document                                                  | Purpose                              | Last Updated |
| --------------------------------------------------------- | ------------------------------------ | ------------ |
| **[UNIFIED_ARCHITECTURE.md](../UNIFIED_ARCHITECTURE.md)** | **Canonical architecture reference** | 2025-11-20   |
| [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)      | Visual architecture diagrams         | 2025-11-20   |
| [SERVICE_CATALOG.md](../SERVICE_CATALOG.md)               | Comprehensive service catalog        | 2025-11-21   |
| [BACKEND_ARCHITECTURE.md](../BACKEND_ARCHITECTURE.md)     | Backend structure evolution          | 2025-11-20   |

### Design Documents

| Document                                                  | Purpose                            |
| --------------------------------------------------------- | ---------------------------------- |
| [ORCHESTRATION_DESIGN.md](../ORCHESTRATION_DESIGN.md)     | RAG query orchestrator design      |
| [SEMANTIC_SEARCH_DESIGN.md](../SEMANTIC_SEARCH_DESIGN.md) | Vector search implementation       |
| [DATA_MODEL.md](../DATA_MODEL.md)                         | Canonical data entities            |
| [NEXTCLOUD_INTEGRATION.md](../NEXTCLOUD_INTEGRATION.md)   | Nextcloud integration architecture |

### Operations & Observability

| Document                                                          | Purpose                         |
| ----------------------------------------------------------------- | ------------------------------- |
| [operations/SLO_DEFINITIONS.md](../operations/SLO_DEFINITIONS.md) | Service level objectives        |
| [OBSERVABILITY.md](../OBSERVABILITY.md)                           | Monitoring and logging patterns |
| [SECURITY_COMPLIANCE.md](../SECURITY_COMPLIANCE.md)               | HIPAA compliance details        |

### Development

| Document                                                        | Purpose               |
| --------------------------------------------------------------- | --------------------- |
| [Implementation Status](../overview/IMPLEMENTATION_STATUS.md)   | Component status      |
| [DEVELOPMENT_PHASES_V2.md](../DEVELOPMENT_PHASES_V2.md)         | Phase-by-phase plan   |
| [LOCAL_DEVELOPMENT.md](../LOCAL_DEVELOPMENT.md)                 | Local setup guide     |
| [testing/E2E_TESTING_GUIDE.md](../testing/E2E_TESTING_GUIDE.md) | Testing strategy      |
| [Archive: CURRENT_PHASE](../archive/CURRENT_PHASE.md)           | Historical phase info |

---

## 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](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](../UNIFIED_ARCHITECTURE.md) - System overview
2. Review [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md) - Visual understanding
3. Check [SERVICE_CATALOG.md](../SERVICE_CATALOG.md) - Service responsibilities
4. Follow [LOCAL_DEVELOPMENT.md](../LOCAL_DEVELOPMENT.md) - Setup instructions

### For System Architects

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

### For Operations/DevOps

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

### For Security/Compliance

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

---

## Architecture Evolution Timeline

| Phase   | Focus                                                  | Status      |
| ------- | ------------------------------------------------------ | ----------- |
| **0-1** | Foundation (Docker, DB, Redis, Qdrant)                 | ✅ Complete |
| **2-3** | Security & Core Services (JWT, Auth, API Gateway)      | ✅ Complete |
| **4**   | Realtime Communication (WebSocket, QueryOrchestrator)  | ✅ Complete |
| **5**   | Medical AI (RAG, semantic search, document ingestion)  | ✅ Complete |
| **6**   | Nextcloud Integration (CalDAV, WebDAV, file indexing)  | ✅ Complete |
| **7**   | Admin & RBAC (admin endpoints, dashboard, smoke tests) | ✅ Complete |
| **8+**  | OIDC, email, voice, frontend, microservices            | ⏳ Future   |

---

## Related Resources

**Code Repositories:**

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

**External Documentation:**

- [FastAPI Docs](https://fastapi.tiangolo.com/)
- [PostgreSQL pgvector](https://github.com/pgvector/pgvector)
- [Qdrant Docs](https://qdrant.tech/documentation/)
- [Prometheus Best Practices](https://prometheus.io/docs/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](../UNIFIED_ARCHITECTURE.md) first (canonical reference)
2. Update [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md) if visual changes
3. Update [SERVICE_CATALOG.md](../SERVICE_CATALOG.md) if service changes
4. Update [Implementation Status](../overview/IMPLEMENTATION_STATUS.md) 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](../UNIFIED_ARCHITECTURE.md) first
- **Service-Specific Questions**: Check [SERVICE_CATALOG.md](../SERVICE_CATALOG.md)
- **Setup Issues**: Follow [LOCAL_DEVELOPMENT.md](../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
6:["slug","architecture/README","c"]
0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","architecture/README","c"],{"children":["__PAGE__?{\"slug\":[\"architecture\",\"README\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","architecture/README","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"Readme"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","architecture/README.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/architecture/README.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]]
c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"Readme | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"**Last Updated**: 2025-11-20 (Phase 7)"}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]]
1:null