# tetherto/qvac architecture

> Architecture diagram of the GitHub repository tetherto/qvac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tetherto/qvac
- Repository: https://github.com/tetherto/qvac

## Overview

QVAC is a local-first, cross-platform AI monorepo: its SDKs expose local model workloads, while its CLI can serve models through an OpenAI-compatible HTTP API. The principal documented workflow is loading a model, running inference, and returning streamed or complete results; the repository also contains many workload-specific engines and a RAG subsystem. Edges are limited to README statements and source-index references; much runtime wiring is unsampled, so uncertain links are omitted.

Main entry points: [`packages/audiogen-ggml/index.js`](https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/index.js) (Audio generation), [`packages/cli/src/serve/core/server.ts`](https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/server.ts) (Server lifecycle), [`packages/rag/src/adapters/database/HyperDBStorage.ts`](https://github.com/tetherto/qvac/blob/main/packages/rag/src/adapters/database/HyperDBStorage.ts) (HyperDB storage), [`packages/rag/src/services/IngestionService.ts`](https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/IngestionService.ts) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["SDKs and provider"]
  node_ts_sdk["TypeScript SDK"]
  node_py_sdk["Python SDK"]
  node_provider["AI SDK provider<br/>[provider.ts]"]
end

subgraph group_engines["Local AI engines"]
  node_asr["Speech recognition"]
  node_audio_gen["Audio generation<br/>[index.js]"]
  node_audio_formats["Audio formats<br/>[audio-format.js]"]
  node_audio_backends["Audio backends<br/>[backends.js]"]
  node_audio_models["Audio models<br/>[models.js]"]
  node_bci["Neural speech input<br/>[bci.js]"]
  node_bci_stream["BCI stream handling<br/>[stream.js]"]
  node_ocr["OCR pipeline<br/>[Pipeline.cpp]"]
end

subgraph group_server["HTTP serving"]
  node_server_cli["Serve CLI<br/>[command.ts]"]
  node_server_core["Server lifecycle<br/>[server.ts]"]
  node_openai_routes["OpenAI API routes"]
  node_load_manager["Model loading<br/>[load-manager.ts]"]
  node_catalog["Model catalog<br/>[model-catalog.ts]"]
end

subgraph group_rag["RAG workflows"]
  node_rag_workspace["RAG workspaces"]
  node_ingestion["Document ingestion"]
  node_embedding["Embedding service"]
  node_embedding_schema["Embedding validation<br/>[embedding.ts]"]
  node_hyperdb[("HyperDB storage<br/>[HyperDBStorage.ts]")]
  node_retrieval["Document retrieval"]
end

node_developer(("Developer or AI tool"))

node_developer -->|"loads and runs"| node_ts_sdk
node_developer -->|"loads and runs"| node_py_sdk
node_developer -->|"starts server"| node_server_cli
node_developer -->|"sends API request"| node_openai_routes
node_audio_gen -->|"uses models"| node_audio_models
node_audio_gen -->|"uses formats"| node_audio_formats
node_audio_gen -->|"uses backends"| node_audio_backends
node_bci -->|"uses stream helpers"| node_bci_stream
node_rag_workspace -->|"creates adapter"| node_hyperdb
node_ingestion -->|"generates embeddings"| node_embedding
node_embedding -->|"validates input"| node_embedding_schema
node_ingestion -.->|"writes documents"| node_hyperdb
node_retrieval -.->|"queries documents"| node_hyperdb
node_server_cli -.->|"starts lifecycle"| node_server_core
node_server_core -.->|"loads models"| node_load_manager
node_server_core -.->|"registers routes"| node_openai_routes
node_load_manager -.->|"resolves models"| node_catalog

click node_ts_sdk "https://github.com/tetherto/qvac/tree/main/packages/sdk/src"
click node_py_sdk "https://github.com/tetherto/qvac/tree/main/packages/sdk-python/src/tetherto/qvac_sdk"
click node_provider "https://github.com/tetherto/qvac/blob/main/packages/ai-sdk-provider/src/provider.ts"
click node_server_cli "https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/command.ts"
click node_server_core "https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/server.ts"
click node_openai_routes "https://github.com/tetherto/qvac/tree/main/packages/cli/src/serve/extensions/openai/routes"
click node_load_manager "https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/load-manager.ts"
click node_catalog "https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/model-catalog.ts"
click node_asr "https://github.com/tetherto/qvac/tree/main/packages/asr-ggml/src/engines"
click node_audio_gen "https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/index.js"
click node_audio_formats "https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/lib/audio-format.js"
click node_audio_backends "https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/lib/backends.js"
click node_audio_models "https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/models.js"
click node_bci "https://github.com/tetherto/qvac/blob/main/packages/bci-whispercpp/bci.js"
click node_bci_stream "https://github.com/tetherto/qvac/blob/main/packages/bci-whispercpp/lib/stream.js"
click node_ocr "https://github.com/tetherto/qvac/blob/main/packages/ocr-ggml/addon/src/model-interface/Pipeline.cpp"
click node_rag_workspace "https://github.com/tetherto/qvac/blob/main/packages/inference/src/rag/rag-workspace-manager.ts"
click node_ingestion "https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/IngestionService.ts"
click node_embedding "https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/core/EmbeddingService.ts"
click node_embedding_schema "https://github.com/tetherto/qvac/blob/main/packages/rag/src/schemas/embedding.ts"
click node_hyperdb "https://github.com/tetherto/qvac/blob/main/packages/rag/src/adapters/database/HyperDBStorage.ts"
click node_retrieval "https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/RetrievalService.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ts_sdk,node_py_sdk,node_provider toneBlue
class node_asr,node_audio_gen,node_audio_formats,node_audio_backends,node_audio_models,node_bci,node_bci_stream,node_ocr toneAmber
class node_server_cli,node_server_core,node_openai_routes,node_load_manager,node_catalog toneMint
class node_rag_workspace,node_ingestion,node_embedding,node_embedding_schema,node_hyperdb,node_retrieval toneRose
class node_developer toneIndigo
```

## Components

### SDKs and provider

- [TypeScript SDK](https://github.com/tetherto/qvac/tree/main/packages/sdk/src): `packages/sdk/src`
- [Python SDK](https://github.com/tetherto/qvac/tree/main/packages/sdk-python/src/tetherto/qvac_sdk): `packages/sdk-python/src/tetherto/qvac_sdk`
- [AI SDK provider](https://github.com/tetherto/qvac/blob/main/packages/ai-sdk-provider/src/provider.ts): `packages/ai-sdk-provider/src/provider.ts`

### Local AI engines

- [Speech recognition](https://github.com/tetherto/qvac/tree/main/packages/asr-ggml/src/engines): `packages/asr-ggml/src/engines`
- [Audio generation](https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/index.js): `packages/audiogen-ggml/index.js`
- [Audio formats](https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/lib/audio-format.js): `packages/audiogen-ggml/lib/audio-format.js`
- [Audio backends](https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/lib/backends.js): `packages/audiogen-ggml/lib/backends.js`
- [Audio models](https://github.com/tetherto/qvac/blob/main/packages/audiogen-ggml/models.js): `packages/audiogen-ggml/models.js`
- [Neural speech input](https://github.com/tetherto/qvac/blob/main/packages/bci-whispercpp/bci.js): `packages/bci-whispercpp/bci.js`
- [BCI stream handling](https://github.com/tetherto/qvac/blob/main/packages/bci-whispercpp/lib/stream.js): `packages/bci-whispercpp/lib/stream.js`
- [OCR pipeline](https://github.com/tetherto/qvac/blob/main/packages/ocr-ggml/addon/src/model-interface/Pipeline.cpp): `packages/ocr-ggml/addon/src/model-interface/Pipeline.cpp`

### HTTP serving

- [Serve CLI](https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/command.ts): `packages/cli/src/serve/command.ts`
- [Server lifecycle](https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/server.ts): `packages/cli/src/serve/core/server.ts`
- [OpenAI API routes](https://github.com/tetherto/qvac/tree/main/packages/cli/src/serve/extensions/openai/routes): `packages/cli/src/serve/extensions/openai/routes`
- [Model loading](https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/load-manager.ts): `packages/cli/src/serve/core/load-manager.ts`
- [Model catalog](https://github.com/tetherto/qvac/blob/main/packages/cli/src/serve/core/model-catalog.ts): `packages/cli/src/serve/core/model-catalog.ts`

### RAG workflows

- [RAG workspaces](https://github.com/tetherto/qvac/blob/main/packages/inference/src/rag/rag-workspace-manager.ts): `packages/inference/src/rag/rag-workspace-manager.ts`
- [Document ingestion](https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/IngestionService.ts): `packages/rag/src/services/IngestionService.ts`
- [Embedding service](https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/core/EmbeddingService.ts): `packages/rag/src/services/core/EmbeddingService.ts`
- [Embedding validation](https://github.com/tetherto/qvac/blob/main/packages/rag/src/schemas/embedding.ts): `packages/rag/src/schemas/embedding.ts`
- [HyperDB storage](https://github.com/tetherto/qvac/blob/main/packages/rag/src/adapters/database/HyperDBStorage.ts): `packages/rag/src/adapters/database/HyperDBStorage.ts`
- [Document retrieval](https://github.com/tetherto/qvac/blob/main/packages/rag/src/services/RetrievalService.ts): `packages/rag/src/services/RetrievalService.ts`

### Other components

- **Developer or AI tool**

## Connections

- Developer or AI tool → TypeScript SDK: loads and runs
- Developer or AI tool → Python SDK: loads and runs
- Developer or AI tool → Serve CLI: starts server
- Developer or AI tool → OpenAI API routes: sends API request
- Audio generation → Audio models: uses models (evidence: `packages/audiogen-ggml/index.js`)
- Audio generation → Audio formats: uses formats (evidence: `packages/audiogen-ggml/index.js`)
- Audio generation → Audio backends: uses backends (evidence: `packages/audiogen-ggml/index.js`)
- Neural speech input → BCI stream handling: uses stream helpers (evidence: `packages/bci-whispercpp/index.js`)
- RAG workspaces → HyperDB storage: creates adapter (evidence: `packages/inference/src/rag/rag-workspace-manager.ts`)
- Document ingestion → Embedding service: generates embeddings (evidence: `packages/rag/src/services/IngestionService.ts`)
- Embedding service → Embedding validation: validates input (evidence: `packages/rag/src/services/core/EmbeddingService.ts`)
- Document ingestion → HyperDB storage: writes documents
- Document retrieval → HyperDB storage: queries documents
- Serve CLI → Server lifecycle: starts lifecycle
- Server lifecycle → Model loading: loads models
- Server lifecycle → OpenAI API routes: registers routes
- Model loading → Model catalog: resolves models
