# amandev17/verbadb architecture

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

- Interactive diagram: https://gitdiagram.com/amandev17/verbadb
- Repository: https://github.com/amandev17/verbadb

## Overview

VerbaDB lets people ask questions about databases and build or modify private SQLite sandboxes using natural language. The main workflow runs from the browser through the FastAPI server and an agent loop, which calls Gemini and dispatches database tools; guarded query results and sandbox change diffs return to the UI. Separate paths manage read-only shared/user connections and sandbox snapshots, undo, and prompt history. The README documents these capabilities; some module relationships below are supported by the source index rather than fully sampled implementations.

Main entry points: [`verbadb/manager.py`](https://github.com/amandev17/verbadb/blob/main/verbadb/manager.py) (Database manager), [`verbadb/agent.py`](https://github.com/amandev17/verbadb/blob/main/verbadb/agent.py) (Agent loop), [`verbadb/server.py`](https://github.com/amandev17/verbadb/blob/main/verbadb/server.py) (HTTP and SSE API), [`verbadb/sandbox.py`](https://github.com/amandev17/verbadb/blob/main/verbadb/sandbox.py) (Sandbox changes and undo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_ui["Web UI<br/>[app.js]"]
  node_theme["Theme controls<br/>[theme.js]"]
  node_server["HTTP and SSE API<br/>[server.py]"]
end

subgraph group_conversation["Agent and model"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_prompts["Prompt construction<br/>[prompts.py]"]
  node_llm["Gemini adapter<br/>[llm.py]"]
end

subgraph group_database["Database access"]
  node_tools["Read-only tools<br/>[tools.py]"]
  node_sandbox_tools["Sandbox tools<br/>[sandbox_tools.py]"]
  node_introspect["Schema inspection<br/>[introspect.py]"]
  node_executor["Query execution<br/>[executor.py]"]
  node_guard["Query safety guard<br/>[guard.py]"]
  node_manager["Database manager<br/>[manager.py]"]
  node_connections["Read-only connections<br/>[connections.py]"]
  node_sandbox["Sandbox changes and undo<br/>[sandbox.py]"]
end

subgraph group_workspace["Workspace state"]
  node_settings["Application settings<br/>[config.py]"]
  node_store[("Workspace data store<br/>[store.py]")]
  node_demo_data["Demo data<br/>[demo_data.py]"]
end

node_browser(("Browser user"))
node_gemini{{"Gemini API"}}
node_external_db[("External databases")]

node_browser -->|"uses"| node_ui
node_ui -->|"sends requests"| node_server
node_server -->|"streams questions"| node_agent
node_server -->|"manages databases"| node_manager
node_server -->|"configures"| node_llm
node_ui -->|"switches theme"| node_theme
node_agent -->|"requests turns"| node_llm
node_llm -->|"calls"| node_gemini
node_agent -->|"resolves database"| node_manager
node_agent -->|"dispatches reads"| node_tools
node_agent -->|"dispatches changes"| node_sandbox_tools
node_agent -->|"builds instructions"| node_prompts
node_tools -->|"describes schema"| node_introspect
node_tools -->|"runs queries"| node_executor
node_executor -->|"validates queries"| node_guard
node_sandbox_tools -->|"applies changes"| node_sandbox
node_sandbox_tools -->|"creates databases"| node_manager
node_manager -->|"opens read-only"| node_connections
node_manager -->|"opens sandboxes"| node_sandbox
node_manager -->|"stores workspace data"| node_store
node_manager -->|"inspects databases"| node_introspect
node_manager -->|"loads demo data"| node_demo_data
node_connections -->|"installs query hook"| node_guard
node_connections -->|"connects read-only"| node_external_db
node_sandbox -->|"validates changes"| node_guard
node_sandbox -->|"uses SQLite files"| node_external_db
node_server -->|"loads configuration"| node_settings

click node_ui "https://github.com/amandev17/verbadb/blob/main/verbadb/static/app.js"
click node_theme "https://github.com/amandev17/verbadb/blob/main/verbadb/static/theme.js"
click node_server "https://github.com/amandev17/verbadb/blob/main/verbadb/server.py"
click node_agent "https://github.com/amandev17/verbadb/blob/main/verbadb/agent.py"
click node_prompts "https://github.com/amandev17/verbadb/blob/main/verbadb/prompts.py"
click node_llm "https://github.com/amandev17/verbadb/blob/main/verbadb/llm.py"
click node_tools "https://github.com/amandev17/verbadb/blob/main/verbadb/tools.py"
click node_sandbox_tools "https://github.com/amandev17/verbadb/blob/main/verbadb/sandbox_tools.py"
click node_introspect "https://github.com/amandev17/verbadb/blob/main/verbadb/introspect.py"
click node_executor "https://github.com/amandev17/verbadb/blob/main/verbadb/executor.py"
click node_guard "https://github.com/amandev17/verbadb/blob/main/verbadb/guard.py"
click node_manager "https://github.com/amandev17/verbadb/blob/main/verbadb/manager.py"
click node_connections "https://github.com/amandev17/verbadb/blob/main/verbadb/connections.py"
click node_sandbox "https://github.com/amandev17/verbadb/blob/main/verbadb/sandbox.py"
click node_settings "https://github.com/amandev17/verbadb/blob/main/verbadb/config.py"
click node_store "https://github.com/amandev17/verbadb/blob/main/verbadb/store.py"
click node_demo_data "https://github.com/amandev17/verbadb/blob/main/verbadb/demo_data.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_ui,node_theme,node_server,node_browser toneBlue
class node_agent,node_prompts,node_llm,node_external_db toneAmber
class node_tools,node_sandbox_tools,node_introspect,node_executor,node_guard,node_manager,node_connections,node_sandbox,node_gemini toneMint
class node_settings,node_store,node_demo_data toneRose
```

## Components

### Web interface

- [Web UI](https://github.com/amandev17/verbadb/blob/main/verbadb/static/app.js): `verbadb/static/app.js`
- [Theme controls](https://github.com/amandev17/verbadb/blob/main/verbadb/static/theme.js): `verbadb/static/theme.js`
- [HTTP and SSE API](https://github.com/amandev17/verbadb/blob/main/verbadb/server.py): `verbadb/server.py`

### Agent and model

- [Agent loop](https://github.com/amandev17/verbadb/blob/main/verbadb/agent.py): `verbadb/agent.py`
- [Prompt construction](https://github.com/amandev17/verbadb/blob/main/verbadb/prompts.py): `verbadb/prompts.py`
- [Gemini adapter](https://github.com/amandev17/verbadb/blob/main/verbadb/llm.py): `verbadb/llm.py`

### Database access

- [Read-only tools](https://github.com/amandev17/verbadb/blob/main/verbadb/tools.py): `verbadb/tools.py`
- [Sandbox tools](https://github.com/amandev17/verbadb/blob/main/verbadb/sandbox_tools.py): `verbadb/sandbox_tools.py`
- [Schema inspection](https://github.com/amandev17/verbadb/blob/main/verbadb/introspect.py): `verbadb/introspect.py`
- [Query execution](https://github.com/amandev17/verbadb/blob/main/verbadb/executor.py): `verbadb/executor.py`
- [Query safety guard](https://github.com/amandev17/verbadb/blob/main/verbadb/guard.py): `verbadb/guard.py`
- [Database manager](https://github.com/amandev17/verbadb/blob/main/verbadb/manager.py): `verbadb/manager.py`
- [Read-only connections](https://github.com/amandev17/verbadb/blob/main/verbadb/connections.py): `verbadb/connections.py`
- [Sandbox changes and undo](https://github.com/amandev17/verbadb/blob/main/verbadb/sandbox.py): `verbadb/sandbox.py`

### Workspace state

- [Application settings](https://github.com/amandev17/verbadb/blob/main/verbadb/config.py): `verbadb/config.py`
- [Workspace data store](https://github.com/amandev17/verbadb/blob/main/verbadb/store.py): `verbadb/store.py`
- [Demo data](https://github.com/amandev17/verbadb/blob/main/verbadb/demo_data.py): `verbadb/demo_data.py`

### Other components

- **Browser user**
- **Gemini API**
- **External databases**

## Connections

- Browser user → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP and SSE API: sends requests (evidence: `README.md`)
- HTTP and SSE API → Agent loop: streams questions (evidence: `verbadb/server.py`)
- HTTP and SSE API → Database manager: manages databases (evidence: `verbadb/server.py`)
- HTTP and SSE API → Gemini adapter: configures (evidence: `verbadb/server.py`)
- Web UI → Theme controls: switches theme (evidence: `README.md`)
- Agent loop → Gemini adapter: requests turns (evidence: `verbadb/agent.py`)
- Gemini adapter → Gemini API: calls (evidence: `README.md`)
- Agent loop → Database manager: resolves database (evidence: `verbadb/agent.py`)
- Agent loop → Read-only tools: dispatches reads (evidence: `verbadb/agent.py`)
- Agent loop → Sandbox tools: dispatches changes (evidence: `verbadb/agent.py`)
- Agent loop → Prompt construction: builds instructions (evidence: `verbadb/agent.py`)
- Read-only tools → Schema inspection: describes schema (evidence: `verbadb/tools.py`)
- Read-only tools → Query execution: runs queries (evidence: `verbadb/tools.py`)
- Query execution → Query safety guard: validates queries (evidence: `verbadb/executor.py`)
- Sandbox tools → Sandbox changes and undo: applies changes (evidence: `verbadb/sandbox_tools.py`)
- Sandbox tools → Database manager: creates databases (evidence: `verbadb/sandbox_tools.py`)
- Database manager → Read-only connections: opens read-only (evidence: `verbadb/manager.py`)
- Database manager → Sandbox changes and undo: opens sandboxes (evidence: `verbadb/manager.py`)
- Database manager → Workspace data store: stores workspace data (evidence: `verbadb/manager.py`)
- Database manager → Schema inspection: inspects databases (evidence: `verbadb/manager.py`)
- Database manager → Demo data: loads demo data (evidence: `verbadb/manager.py`)
- Read-only connections → Query safety guard: installs query hook (evidence: `verbadb/connections.py`)
- Read-only connections → External databases: connects read-only (evidence: `README.md`)
- Sandbox changes and undo → Query safety guard: validates changes (evidence: `verbadb/sandbox.py`)
- Sandbox changes and undo → External databases: uses SQLite files (evidence: `README.md`)
- HTTP and SSE API → Application settings: loads configuration (evidence: `verbadb/server.py`)