# hfmsio/dbxlite architecture

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

- Interactive diagram: https://gitdiagram.com/hfmsio/dbxlite
- Repository: https://github.com/hfmsio/dbxlite

## Overview

#### Purpose and Entry Points
dbxlite is a browser SQL workbench with a shared UI for local DuckDB, BigQuery, and Snowflake. It runs either against DuckDB-WASM in the browser or a native DuckDB `-ui` server, while cloud warehouses use browser-facing connectors. Main browser bootstrap: `apps/web-client/src/main.tsx`, application orchestration: `apps/web-client/src/App.tsx`. The distributable asset-server CLI is `apps/cli/src/cli.js`.

#### Application Composition and State
The React/Vite client composes providers for settings, data sources, tabs, and query state, then renders the explorer/editor/results workspace and dialogs. Contexts carry active-tab and connector/query lifecycle state; Zustand-style stores persist UI, onboarding, AI chat, and source metadata. Key boundaries: `apps/web-client/src/contexts/TabContext.tsx`, `apps/web-client/src/contexts/QueryContext.tsx`, `apps/web-client/src/stores/dataSourceStore/store.ts`.

#### Query Routing and Lifecycle
`useQueryExecution` drives user SQL from the editor into the query service. The executor selects an engine/connector mode, manages cancellation and engine-specific lifecycles, and returns structured/streamed results to the grid. This isolates UI from DuckDB, BigQuery, and Snowflake transport differences. Core paths: `apps/web-client/src/hooks/useQueryExecution.ts`, `apps/web-client/src/services/query/query-executor.ts`, `apps/web-client/src/services/query/connector-registry.ts`.

#### Connector and Engine Layer
The reusable connectors package defines the cross-engine boundary: DuckDB (including HTTP/server mode), BigQuery, and Snowflake connectors plus OAuth/PAT transport and parse workers. Engine detection and lifecycle adapters map browser/server execution modes into those interfaces. Relevant paths: `packages/connectors/src/base.ts`, `packages/connectors/src/duckdb-connector.ts`, `packages/connectors/src/bigquery-connector.ts`, `packages/connectors/src/snowflake-connector.ts`. BigQuery uses Google APIs directly; Snowflake uses SQL REST API v2 and requires a proxy because of browser CORS/header constraints.

#### Local DuckDB-WASM and File Access
WASM mode executes DuckDB in a Web Worker through a dedicated adapter. Local files are represented by File System Access handles and virtualized for on-demand reads rather than eagerly copied to memory; remote files rely on DuckDB HTTP access. The browser boundary is material: File System Access API, Web Workers, OPFS, and cross-origin isolation. Paths: `packages/duckdb-wasm-adapter/src/index.ts`, `packages/duckdb-wasm-adapter/src/worker.ts`, `apps/web-client/src/services/query/file-vfs.ts`.

#### Results, Streaming, and Export
Large result sets are streamed/paginated rather than fully rendered. The virtualized table retrieves pages through query services, supports sorting/selection, and routes exports by engine: native DuckDB `COPY`, OPFS/download paths, or cloud chunk streaming into DuckDB-backed Parquet writing. Paths: `apps/web-client/src/services/streaming-query-service.ts`, `apps/web-client/src/components/PaginatedTable.tsx`, `apps/web-client/src/components/table/exporters/index.ts`.

#### Persistence, Credentials, and Optional Integrations
Settings, file handles, and connection metadata are client-side; the storage package provides credential storage, with AES-GCM encryption for supported credential paths. AI is opt-in and provider-pluggable for OpenAI-compatible, Anthropic, Gemini, or warehouse-backed capabilities; consent gates external sends. Gist URL sharing is another external integration. Paths: `packages/storage/src/index.ts`, `apps/web-client/src/services/ai/backend-registry.ts`, `apps/web-client/src/utils/sharingProviders/providers/gist.ts`.

#### Delivery Modes and Infrastructure
The primary deployment is static assets: Vite builds the client, and nginx serves it with COOP/COEP/CORP headers required for WASM/OPFS behavior. Docker contains no shared query backend. Native server mode instead has DuckDB serve query APIs locally while `dbxlite-ui` supplies UI assets. Paths: `Dockerfile`, `docker/nginx.conf`, `apps/cli/scripts/build.js`.

Main entry points: [`apps/web-client/src/App.tsx`](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/App.tsx) (App workspace), [`apps/web-client/src/services/query/query-executor.ts`](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/query-executor.ts) (Query executor), [`packages/connectors/src/duckdb-connector.ts`](https://github.com/hfmsio/dbxlite/blob/main/packages/connectors/src/duckdb-connector.ts) (DuckDB & cloud connectors), [`packages/duckdb-wasm-adapter/src/index.ts`](https://github.com/hfmsio/dbxlite/blob/main/packages/duckdb-wasm-adapter/src/index.ts) (DuckDB-WASM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Client"]
  node_bootstrap["Web bootstrap<br/>React/Vite entry<br/>[main.tsx]"]
  node_app["App workspace<br/>React composition<br/>[App.tsx]"]
  node_tab_context["Tab state<br/>React context<br/>[TabContext.tsx]"]
  node_query_context["Query state<br/>React context<br/>[QueryContext.tsx]"]
  node_source_store[("Source metadata store<br/>client store<br/>[store.ts]")]
  node_table["Paginated results table<br/>virtualized grid<br/>[PaginatedTable.tsx]"]
  node_exporters["Result exporters<br/>export routing<br/>[index.ts]"]
  node_storage[("Credential storage<br/>encrypted client storage<br/>[index.ts]")]
end

subgraph group_query["Query Execution"]
  node_query_hook["Query execution hook<br/>UI query lifecycle"]
  node_executor{{"Query executor<br/>execution router<br/>[query-executor.ts]"}}
  node_registry["Connector registry<br/>connector selection"]
  node_streaming["Streaming query service<br/>result paging"]
end

subgraph group_connectors["Connector Packages"]
  node_connector_base{{"Connector interface<br/>cross-engine contract<br/>[base.ts]"}}
  node_engine_connectors["DuckDB &amp; cloud connectors<br/>connector implementations"]
end

subgraph group_local["Local DuckDB Runtime"]
  node_wasm_adapter["DuckDB-WASM adapter<br/>worker adapter<br/>[index.ts]"]
  node_wasm_worker["DuckDB WASM worker<br/>Web Worker<br/>[worker.ts]"]
  node_file_vfs["File virtualizer<br/>browser file VFS<br/>[file-vfs.ts]"]
end

subgraph group_external["External Services &amp; Delivery"]
  node_ai_registry["AI backend registry<br/>optional AI integration"]
  node_gist["Gist sharing<br/>external sharing<br/>[gist.ts]"]
  node_cloud_apis{{"Warehouse APIs<br/>external APIs"}}
  node_static_delivery["Static asset delivery<br/>Vite/nginx deployment<br/>[nginx.conf]"]
  node_cli["dbxlite-ui CLI<br/>asset-server CLI<br/>[cli.js]"]
end

node_bootstrap -->|"mounts"| node_app
node_app -->|"provides"| node_tab_context
node_app -->|"provides"| node_query_context
node_app -->|"uses"| node_source_store
node_app -->|"editor SQL"| node_query_hook
node_query_hook -->|"executes"| node_executor
node_executor -->|"selects connector"| node_registry
node_executor -->|"returns results"| node_streaming
node_streaming -->|"paged rows"| node_table
node_table -->|"exports"| node_exporters
node_registry -->|"targets contract"| node_connector_base
node_connector_base -->|"implemented by"| node_engine_connectors
node_engine_connectors -->|"local WASM mode"| node_wasm_adapter
node_wasm_adapter -->|"delegates SQL"| node_wasm_worker
node_wasm_adapter -->|"reads virtual files"| node_file_vfs
node_engine_connectors -->|"BigQuery / Snowflake"| node_cloud_apis
node_source_store -->|"persists metadata"| node_storage
node_app -.->|"optional AI"| node_ai_registry
node_app -.->|"optional sharing"| node_gist
node_static_delivery -->|"serves client"| node_bootstrap
node_cli -.->|"supplies UI assets"| node_app

click node_bootstrap "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/main.tsx"
click node_app "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/App.tsx"
click node_tab_context "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/contexts/TabContext.tsx"
click node_query_context "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/contexts/QueryContext.tsx"
click node_source_store "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/stores/dataSourceStore/store.ts"
click node_query_hook "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/hooks/useQueryExecution.ts"
click node_executor "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/query-executor.ts"
click node_registry "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/connector-registry.ts"
click node_streaming "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/streaming-query-service.ts"
click node_table "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/components/PaginatedTable.tsx"
click node_exporters "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/components/table/exporters/index.ts"
click node_connector_base "https://github.com/hfmsio/dbxlite/blob/main/packages/connectors/src/base.ts"
click node_engine_connectors "https://github.com/hfmsio/dbxlite/blob/main/packages/connectors/src/duckdb-connector.ts"
click node_wasm_adapter "https://github.com/hfmsio/dbxlite/blob/main/packages/duckdb-wasm-adapter/src/index.ts"
click node_wasm_worker "https://github.com/hfmsio/dbxlite/blob/main/packages/duckdb-wasm-adapter/src/worker.ts"
click node_file_vfs "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/file-vfs.ts"
click node_storage "https://github.com/hfmsio/dbxlite/blob/main/packages/storage/src/index.ts"
click node_ai_registry "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/ai/backend-registry.ts"
click node_gist "https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/utils/sharingProviders/providers/gist.ts"
click node_static_delivery "https://github.com/hfmsio/dbxlite/blob/main/docker/nginx.conf"
click node_cli "https://github.com/hfmsio/dbxlite/blob/main/apps/cli/src/cli.js"

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_bootstrap,node_app,node_tab_context,node_query_context,node_source_store,node_table,node_exporters,node_storage toneBlue
class node_query_hook,node_executor,node_registry,node_streaming toneAmber
class node_connector_base,node_engine_connectors toneMint
class node_wasm_adapter,node_wasm_worker,node_file_vfs toneRose
class node_ai_registry,node_gist,node_cloud_apis,node_static_delivery,node_cli toneIndigo
```

## Components

### Browser Client

React workbench and browser-owned state.

- [Web bootstrap](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/main.tsx): React/Vite entry · `apps/web-client/src/main.tsx`
- [App workspace](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/App.tsx): React composition · Composes providers, workspace, dialogs, and primary UI. · `apps/web-client/src/App.tsx`
- [Tab state](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/contexts/TabContext.tsx): React context · Tracks active tabs and editor workspace state. · `apps/web-client/src/contexts/TabContext.tsx`
- [Query state](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/contexts/QueryContext.tsx): React context · Carries query and connector lifecycle state. · `apps/web-client/src/contexts/QueryContext.tsx`
- [Source metadata store](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/stores/dataSourceStore/store.ts): client store · Persists data-source and UI metadata. · `apps/web-client/src/stores/dataSourceStore/store.ts`
- [Paginated results table](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/components/PaginatedTable.tsx): virtualized grid · Renders result pages with sorting and selection. · `apps/web-client/src/components/PaginatedTable.tsx`
- [Result exporters](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/components/table/exporters/index.ts): export routing · Uses engine-specific export and download paths. · `apps/web-client/src/components/table/exporters/index.ts`
- [Credential storage](https://github.com/hfmsio/dbxlite/blob/main/packages/storage/src/index.ts): encrypted client storage · Stores supported credentials with AES-GCM encryption. · `packages/storage/src/index.ts`

### Query Execution

Engine-neutral routing, execution, and result handling.

- [Query execution hook](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/hooks/useQueryExecution.ts): UI query lifecycle · Sends editor SQL into the query service. · `apps/web-client/src/hooks/useQueryExecution.ts`
- [Query executor](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/query-executor.ts): execution router · Selects execution mode and manages cancellation. · `apps/web-client/src/services/query/query-executor.ts`
- [Connector registry](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/connector-registry.ts): connector selection · Maps data sources and modes to connectors. · `apps/web-client/src/services/query/connector-registry.ts`
- [Streaming query service](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/streaming-query-service.ts): result paging · Provides structured and streamed result pages. · `apps/web-client/src/services/streaming-query-service.ts`

### Connector Packages

Cross-engine execution interfaces and implementations.

- [Connector interface](https://github.com/hfmsio/dbxlite/blob/main/packages/connectors/src/base.ts): cross-engine contract · Shared contract for DuckDB and cloud connectors. · `packages/connectors/src/base.ts`
- [DuckDB & cloud connectors](https://github.com/hfmsio/dbxlite/blob/main/packages/connectors/src/duckdb-connector.ts): connector implementations · DuckDB, BigQuery, and Snowflake transports implement the common contract. · `packages/connectors/src/duckdb-connector.ts`

### Local DuckDB Runtime

Browser WASM execution and virtual file access.

- [DuckDB-WASM adapter](https://github.com/hfmsio/dbxlite/blob/main/packages/duckdb-wasm-adapter/src/index.ts): worker adapter · Runs local DuckDB through a dedicated Web Worker. · `packages/duckdb-wasm-adapter/src/index.ts`
- [DuckDB WASM worker](https://github.com/hfmsio/dbxlite/blob/main/packages/duckdb-wasm-adapter/src/worker.ts): Web Worker · `packages/duckdb-wasm-adapter/src/worker.ts`
- [File virtualizer](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/query/file-vfs.ts): browser file VFS · Uses file handles for on-demand local reads. · `apps/web-client/src/services/query/file-vfs.ts`

### External Services & Delivery

Cloud APIs, optional integrations, and deployment modes.

- [AI backend registry](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/services/ai/backend-registry.ts): optional AI integration · Provider-pluggable AI behind consent gates. · `apps/web-client/src/services/ai/backend-registry.ts`
- [Gist sharing](https://github.com/hfmsio/dbxlite/blob/main/apps/web-client/src/utils/sharingProviders/providers/gist.ts): external sharing · `apps/web-client/src/utils/sharingProviders/providers/gist.ts`
- **Warehouse APIs**: external APIs · BigQuery uses Google APIs; Snowflake SQL REST v2 requires a proxy.
- [Static asset delivery](https://github.com/hfmsio/dbxlite/blob/main/docker/nginx.conf): Vite/nginx deployment · nginx serves assets with cross-origin isolation headers. · `docker/nginx.conf`
- [dbxlite-ui CLI](https://github.com/hfmsio/dbxlite/blob/main/apps/cli/src/cli.js): asset-server CLI · Builds and supplies UI assets for native DuckDB server mode. · `apps/cli/src/cli.js`

## Connections

- Web bootstrap → App workspace: mounts
- App workspace → Tab state: provides
- App workspace → Query state: provides
- App workspace → Source metadata store: uses
- App workspace → Query execution hook: editor SQL
- Query execution hook → Query executor: executes
- Query executor → Connector registry: selects connector
- Query executor → Streaming query service: returns results
- Streaming query service → Paginated results table: paged rows
- Paginated results table → Result exporters: exports
- Connector registry → Connector interface: targets contract
- Connector interface → DuckDB & cloud connectors: implemented by
- DuckDB & cloud connectors → DuckDB-WASM adapter: local WASM mode
- DuckDB-WASM adapter → DuckDB WASM worker: delegates SQL
- DuckDB-WASM adapter → File virtualizer: reads virtual files
- DuckDB & cloud connectors → Warehouse APIs: BigQuery / Snowflake
- Source metadata store → Credential storage: persists metadata
- App workspace → AI backend registry: optional AI
- App workspace → Gist sharing: optional sharing
- Static asset delivery → Web bootstrap: serves client
- dbxlite-ui CLI → App workspace: supplies UI assets