# zvec-ai/zvec-studio architecture

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

- Interactive diagram: https://gitdiagram.com/zvec-ai/zvec-studio
- Repository: https://github.com/zvec-ai/zvec-studio

## Overview

Zvec Studio is a visual management application for the embedded Zvec vector database. The main user workflow is to create or open a collection, define its schema, insert or import documents, and browse or search its data; AI functions enable text-based embedding and reranking. The frontend calls a FastAPI backend, which routes collection, document, and search operations to Zvec storage. Snapshot import/export and persistent AI and recent-collection configuration are additional capabilities. Edges reflect README statements and indexed source references; unsampled wiring is left unasserted.

Main entry points: [`apps/backend/zvec_studio/main.py`](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/main.py) (FastAPI app), [`apps/backend/zvec_studio/routers/collections.py`](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/collections.py) (Collection operations), [`apps/backend/zvec_studio/routers/documents.py`](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/documents.py) (Document operations), [`apps/frontend/src/lib/api-client.ts`](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/lib/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Studio interface"]
  node_app["Frontend app<br/>[App.tsx]"]
  node_routes["Feature routes<br/>[routes.tsx]"]
  node_collections_ui["Collection workspace<br/>[QueryTab.tsx]"]
  node_ai_ui["AI functions UI"]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_api["Backend API"]
  node_schemas["API schemas<br/>[collection.py]"]
  node_server["FastAPI app<br/>[main.py]"]
  node_collection_routes["Collection operations<br/>[collections.py]"]
  node_document_routes["Document operations<br/>[documents.py]"]
  node_search_routes["Search operations<br/>[searches.py]"]
  node_filesystem["Filesystem access<br/>[fs.py]"]
end

subgraph group_storage["Collection storage"]
  node_sdk["Zvec backend<br/>[sdk.py]"]
  node_snapshot["Snapshot exchange<br/>[snapshot.py]"]
  node_formats["Document formats<br/>[formats.py]"]
  node_config[("Recent collections<br/>[config_store.py]")]
end

subgraph group_ai["AI extensions"]
  node_ai_service["AI runtime<br/>[ai_service.py]"]
  node_ai_store[("AI function registry<br/>[ai_store.py]")]
end

subgraph group_runtime["Application runtime"]
  node_desktop["Desktop shell<br/>[lib.rs]"]
  node_sidecar["Backend sidecar<br/>[sidecar.rs]"]
  node_middleware["Request middleware<br/>[logging.py]"]
end

node_user(("Studio user"))
node_zvec["Zvec SDK"]

node_user -->|"uses"| node_app
node_user -->|"runs"| node_desktop
node_desktop -->|"manages"| node_sidecar
node_app -->|"renders"| node_routes
node_app -->|"configures"| node_api_client
node_collections_ui -.->|"requests data"| node_api_client
node_ai_ui -.->|"requests AI"| node_api_client
node_api_client -.->|"sends requests"| node_server
node_server -->|"registers routes"| node_collection_routes
node_server -->|"registers routes"| node_document_routes
node_server -->|"registers routes"| node_search_routes
node_server -->|"registers routes"| node_filesystem
node_server -->|"configures"| node_middleware
node_collection_routes -->|"manages collections"| node_sdk
node_collection_routes -->|"updates recents"| node_config
node_collection_routes -->|"exchanges snapshots"| node_snapshot
node_collection_routes -->|"uses formats"| node_formats
node_document_routes -->|"operates on data"| node_sdk
node_document_routes -->|"imports documents"| node_formats
node_document_routes -->|"exchanges snapshots"| node_snapshot
node_search_routes -->|"queries collections"| node_sdk
node_search_routes -->|"embeds or reranks"| node_ai_service
node_ai_service -->|"loads functions"| node_ai_store
node_sdk -->|"persists collections"| node_zvec

click node_desktop "https://github.com/zvec-ai/zvec-studio/blob/main/apps/desktop/src-tauri/src/lib.rs"
click node_sidecar "https://github.com/zvec-ai/zvec-studio/blob/main/apps/desktop/src-tauri/src/sidecar.rs"
click node_app "https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/App.tsx"
click node_routes "https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/router/routes.tsx"
click node_collections_ui "https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/pages/collections/QueryTab.tsx"
click node_ai_ui "https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/pages/ai/AiFunctionsPage.tsx"
click node_api_client "https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/lib/api-client.ts"
click node_schemas "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/schemas/collection.py"
click node_server "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/main.py"
click node_collection_routes "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/collections.py"
click node_document_routes "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/documents.py"
click node_search_routes "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/searches.py"
click node_filesystem "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/fs.py"
click node_sdk "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/sdk.py"
click node_snapshot "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/snapshot.py"
click node_formats "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/formats.py"
click node_config "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/config_store.py"
click node_ai_service "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/ai_service.py"
click node_ai_store "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/ai_store.py"
click node_middleware "https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/middleware/logging.py"

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_app,node_routes,node_collections_ui,node_ai_ui,node_api_client,node_user toneBlue
class node_schemas,node_server,node_collection_routes,node_document_routes,node_search_routes,node_filesystem toneAmber
class node_sdk,node_snapshot,node_formats,node_config toneMint
class node_ai_service,node_ai_store toneRose
class node_desktop,node_sidecar,node_middleware,node_zvec toneIndigo
```

## Components

### Studio interface

- [Frontend app](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/App.tsx): `apps/frontend/src/App.tsx`
- [Feature routes](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/router/routes.tsx): `apps/frontend/src/router/routes.tsx`
- [Collection workspace](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/pages/collections/QueryTab.tsx): `apps/frontend/src/pages/collections/QueryTab.tsx`
- [AI functions UI](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/pages/ai/AiFunctionsPage.tsx): `apps/frontend/src/pages/ai/AiFunctionsPage.tsx`
- [API client](https://github.com/zvec-ai/zvec-studio/blob/main/apps/frontend/src/lib/api-client.ts): `apps/frontend/src/lib/api-client.ts`

### Backend API

- [API schemas](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/schemas/collection.py): `apps/backend/zvec_studio/schemas/collection.py`
- [FastAPI app](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/main.py): `apps/backend/zvec_studio/main.py`
- [Collection operations](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/collections.py): `apps/backend/zvec_studio/routers/collections.py`
- [Document operations](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/documents.py): `apps/backend/zvec_studio/routers/documents.py`
- [Search operations](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/searches.py): `apps/backend/zvec_studio/routers/searches.py`
- [Filesystem access](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/routers/fs.py): `apps/backend/zvec_studio/routers/fs.py`

### Collection storage

- [Zvec backend](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/sdk.py): `apps/backend/zvec_studio/storage/sdk.py`
- [Snapshot exchange](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/snapshot.py): `apps/backend/zvec_studio/storage/snapshot.py`
- [Document formats](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/storage/formats.py): `apps/backend/zvec_studio/storage/formats.py`
- [Recent collections](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/config_store.py): `apps/backend/zvec_studio/config_store.py`

### AI extensions

- [AI runtime](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/ai_service.py): `apps/backend/zvec_studio/ai_service.py`
- [AI function registry](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/ai_store.py): `apps/backend/zvec_studio/ai_store.py`

### Application runtime

- [Desktop shell](https://github.com/zvec-ai/zvec-studio/blob/main/apps/desktop/src-tauri/src/lib.rs): `apps/desktop/src-tauri/src/lib.rs`
- [Backend sidecar](https://github.com/zvec-ai/zvec-studio/blob/main/apps/desktop/src-tauri/src/sidecar.rs): `apps/desktop/src-tauri/src/sidecar.rs`
- [Request middleware](https://github.com/zvec-ai/zvec-studio/blob/main/apps/backend/zvec_studio/middleware/logging.py): `apps/backend/zvec_studio/middleware/logging.py`

### Other components

- **Studio user**
- **Zvec SDK**

## Connections

- Studio user → Frontend app: uses (evidence: `README.md`)
- Studio user → Desktop shell: runs (evidence: `README.md`)
- Desktop shell → Backend sidecar: manages (evidence: `apps/desktop/src-tauri/src/lib.rs`)
- Frontend app → Feature routes: renders (evidence: `apps/frontend/src/App.tsx`)
- Frontend app → API client: configures (evidence: `apps/frontend/src/App.tsx`)
- Collection workspace → API client: requests data
- AI functions UI → API client: requests AI
- API client → FastAPI app: sends requests
- FastAPI app → Collection operations: registers routes (evidence: `apps/backend/zvec_studio/main.py`)
- FastAPI app → Document operations: registers routes (evidence: `apps/backend/zvec_studio/main.py`)
- FastAPI app → Search operations: registers routes (evidence: `apps/backend/zvec_studio/main.py`)
- FastAPI app → Filesystem access: registers routes (evidence: `apps/backend/zvec_studio/main.py`)
- FastAPI app → Request middleware: configures (evidence: `apps/backend/zvec_studio/main.py`)
- Collection operations → Zvec backend: manages collections (evidence: `apps/backend/zvec_studio/routers/collections.py`)
- Collection operations → Recent collections: updates recents (evidence: `apps/backend/zvec_studio/routers/collections.py`)
- Collection operations → Snapshot exchange: exchanges snapshots (evidence: `apps/backend/zvec_studio/routers/collections.py`)
- Collection operations → Document formats: uses formats (evidence: `apps/backend/zvec_studio/routers/collections.py`)
- Document operations → Zvec backend: operates on data (evidence: `apps/backend/zvec_studio/routers/documents.py`)
- Document operations → Document formats: imports documents (evidence: `apps/backend/zvec_studio/routers/documents.py`)
- Document operations → Snapshot exchange: exchanges snapshots (evidence: `apps/backend/zvec_studio/routers/documents.py`)
- Search operations → Zvec backend: queries collections (evidence: `apps/backend/zvec_studio/routers/searches.py`)
- Search operations → AI runtime: embeds or reranks (evidence: `apps/backend/zvec_studio/routers/searches.py`)
- AI runtime → AI function registry: loads functions (evidence: `apps/backend/zvec_studio/ai_service.py`)
- Zvec backend → Zvec SDK: persists collections (evidence: `apps/backend/zvec_studio/storage/sdk.py`)
