# iamvinhnt/quriodb architecture

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

- Interactive diagram: https://gitdiagram.com/iamvinhnt/quriodb
- Repository: https://github.com/iamvinhnt/quriodb

## Overview

QurioDB is a desktop-first database management and analytics platform. The central workflow is: users configure a database connection, inspect schema in SQL Lab, submit queries for policy-checked execution, and review results, history, or saved queries. AI-assisted SQL and database-aware RAG add a parallel query-understanding and context-retrieval path; imports, dashboards, settings, and authentication are supporting product capabilities. The README documents the desktop sidecar lifecycle; sampled source confirms API setup, query execution ownership, authentication, metadata discovery, and retrieval behavior, but not every subsystem’s internal wiring.

Main entry points: [`apps/web/src/lib/api.ts`](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/lib/api.ts) (API client), [`apps/web/src/app/sqllab/page.tsx`](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/sqllab/page.tsx) (SQL Lab), [`apps/api/services/execution`](https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/execution) (Query execution), [`apps/api/services/ai`](https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/ai) (AI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_app["Web application<br/>[App.tsx]"]
  node_connections_ui["Connections<br/>[page.tsx]"]
  node_sql_lab["SQL Lab<br/>[page.tsx]"]
  node_ai_assistant["AI assistant<br/>[AIAssistant.tsx]"]
  node_settings_ui["Settings<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_backend["API and services"]
  node_api_app["FastAPI application<br/>[app.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_metadata_store[("Local metadata store<br/>[database.py]")]
end

subgraph group_database_ops["Database operations"]
  node_connections["Connection service<br/>[connection.py]"]
  node_metadata["Metadata discovery<br/>[metadata_routes.py]"]
  node_execution_routes["Execution API"]
  node_execution_service["Query execution"]
  node_imports["Data import<br/>[import_service.py]"]
  node_dashboard_service["Analytics service"]
end

subgraph group_ai_rag["AI and RAG"]
  node_ai_routes["AI and RAG API<br/>[ai.py]"]
  node_ai_runtime["AI runtime"]
  node_rag_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_rag_retrieval["RAG retrieval"]
end

subgraph group_desktop["Desktop runtime"]
  node_desktop_shell["Tauri desktop shell<br/>[lib.rs]"]
  node_sidecar["Python API sidecar<br/>[desktop_app.py]"]
end

node_user(("User"))
node_external_db[("Connected databases")]
node_model_provider(("AI model providers"))

node_user -->|"uses"| node_web_app
node_web_app -->|"requests"| node_api_client
node_api_app -->|"registers routes"| node_auth
node_api_app -->|"initializes"| node_metadata_store
node_connections_ui -->|"manages connections"| node_api_client
node_connections -->|"connects"| node_external_db
node_sql_lab -->|"submits queries"| node_api_client
node_api_client -->|"sends requests"| node_execution_routes
node_execution_routes -->|"invokes"| node_execution_service
node_execution_service -->|"executes queries"| node_external_db
node_execution_service -->|"records history"| node_metadata_store
node_metadata -->|"reads schema"| node_external_db
node_sql_lab -->|"browses schema"| node_metadata
node_sql_lab -->|"requests execution"| node_execution_routes
node_ai_assistant -->|"requests assistance"| node_ai_routes
node_ai_routes -->|"dispatches"| node_ai_runtime
node_ai_runtime -->|"builds context"| node_rag_pipeline
node_rag_pipeline -->|"retrieves evidence"| node_rag_retrieval
node_rag_retrieval -->|"reads indexed sources"| node_metadata_store
node_rag_retrieval -->|"searches vectors"| node_external_db
node_ai_runtime -->|"calls models"| node_model_provider
node_settings_ui -->|"configures AI"| node_api_client
node_dashboard_ui -->|"requests analytics"| node_api_client
node_imports -->|"loads data"| node_external_db
node_desktop_shell -->|"starts sidecar"| node_sidecar
node_sidecar -->|"hosts API"| node_api_app
node_desktop_shell -->|"publishes API URL"| node_web_app

click node_web_app "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/App.tsx"
click node_connections_ui "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/connections/page.tsx"
click node_sql_lab "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/sqllab/page.tsx"
click node_ai_assistant "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/sqllab/components/AIAssistant.tsx"
click node_settings_ui "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/settings/page.tsx"
click node_dashboard_ui "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/page.tsx"
click node_api_client "https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/lib/api.ts"
click node_api_app "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/app.py"
click node_auth "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/auth_service.py"
click node_connections "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/connection.py"
click node_metadata "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/metadata_routes.py"
click node_execution_routes "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/execution_routes.py"
click node_execution_service "https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/execution"
click node_imports "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/import_service.py"
click node_dashboard_service "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/analytics_service.py"
click node_ai_routes "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/ai.py"
click node_ai_runtime "https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/ai"
click node_rag_pipeline "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/ai/retrieval/pipeline.py"
click node_rag_retrieval "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/ai/retrieval/retrieval_service.py"
click node_metadata_store "https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/models/database.py"
click node_desktop_shell "https://github.com/iamvinhnt/quriodb/blob/dev/apps/desktop/src-tauri/src/lib.rs"
click node_sidecar "https://github.com/iamvinhnt/quriodb/blob/dev/apps/desktop/python/desktop_app.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_web_app,node_connections_ui,node_sql_lab,node_ai_assistant,node_settings_ui,node_dashboard_ui,node_api_client,node_user toneBlue
class node_api_app,node_auth,node_metadata_store,node_external_db toneAmber
class node_connections,node_metadata,node_execution_routes,node_execution_service,node_imports,node_dashboard_service toneMint
class node_ai_routes,node_ai_runtime,node_rag_pipeline,node_rag_retrieval toneRose
class node_desktop_shell,node_sidecar,node_model_provider toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Connections](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/connections/page.tsx): `apps/web/src/app/connections/page.tsx`
- [SQL Lab](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/sqllab/page.tsx): `apps/web/src/app/sqllab/page.tsx`
- [AI assistant](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/sqllab/components/AIAssistant.tsx): `apps/web/src/app/sqllab/components/AIAssistant.tsx`
- [Settings](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/settings/page.tsx): `apps/web/src/app/settings/page.tsx`
- [Dashboard](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [API client](https://github.com/iamvinhnt/quriodb/blob/dev/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API and services

- [FastAPI application](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/app.py): `apps/api/app.py`
- [Authentication](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/auth_service.py): `apps/api/services/auth_service.py`
- [Local metadata store](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/models/database.py): `apps/api/models/database.py`

### Database operations

- [Connection service](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/connection.py): `apps/api/services/connection.py`
- [Metadata discovery](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/metadata_routes.py): `apps/api/routes/metadata_routes.py`
- [Execution API](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/execution_routes.py): `apps/api/routes/execution_routes.py`
- [Query execution](https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/execution): `apps/api/services/execution`
- [Data import](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/import_service.py): `apps/api/services/import_service.py`
- [Analytics service](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/analytics_service.py): `apps/api/services/analytics_service.py`

### AI and RAG

- [AI and RAG API](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/routes/ai.py): `apps/api/routes/ai.py`
- [AI runtime](https://github.com/iamvinhnt/quriodb/tree/dev/apps/api/services/ai): `apps/api/services/ai`
- [RAG pipeline](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/ai/retrieval/pipeline.py): `apps/api/services/ai/retrieval/pipeline.py`
- [RAG retrieval](https://github.com/iamvinhnt/quriodb/blob/dev/apps/api/services/ai/retrieval/retrieval_service.py): `apps/api/services/ai/retrieval/retrieval_service.py`

### Desktop runtime

- [Tauri desktop shell](https://github.com/iamvinhnt/quriodb/blob/dev/apps/desktop/src-tauri/src/lib.rs): `apps/desktop/src-tauri/src/lib.rs`
- [Python API sidecar](https://github.com/iamvinhnt/quriodb/blob/dev/apps/desktop/python/desktop_app.py): `apps/desktop/python/desktop_app.py`

### Other components

- **User**
- **Connected databases**
- **AI model providers**

## Connections

- User → Web application: uses
- Web application → API client: requests
- FastAPI application → Authentication: registers routes
- FastAPI application → Local metadata store: initializes
- Connections → API client: manages connections
- Connection service → Connected databases: connects
- SQL Lab → API client: submits queries
- API client → Execution API: sends requests
- Execution API → Query execution: invokes
- Query execution → Connected databases: executes queries
- Query execution → Local metadata store: records history
- Metadata discovery → Connected databases: reads schema
- SQL Lab → Metadata discovery: browses schema
- SQL Lab → Execution API: requests execution
- AI assistant → AI and RAG API: requests assistance
- AI and RAG API → AI runtime: dispatches
- AI runtime → RAG pipeline: builds context
- RAG pipeline → RAG retrieval: retrieves evidence
- RAG retrieval → Local metadata store: reads indexed sources
- RAG retrieval → Connected databases: searches vectors
- AI runtime → AI model providers: calls models
- Settings → API client: configures AI
- Dashboard → API client: requests analytics
- Data import → Connected databases: loads data
- Tauri desktop shell → Python API sidecar: starts sidecar
- Python API sidecar → FastAPI application: hosts API
- Tauri desktop shell → Web application: publishes API URL