# caioricciuti/duck-ui architecture

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

- Interactive diagram: https://gitdiagram.com/caioricciuti/duck-ui
- Repository: https://github.com/caioricciuti/duck-ui

## Overview

Duck-UI is a browser-based DuckDB workbench. The main workflow is to open a workspace, connect or import data, write and execute SQL, then inspect results as tables or charts and save or share the analysis. Notebooks, dashboards, AI-assisted SQL, and live collaboration add distinct workflows. The graph includes the query execution and persistence layers as internal architecture. README capabilities are represented, but where source excerpts do not establish component wiring, links are omitted rather than inferred.

Main entry points: [`src/services/engine/drivers`](https://github.com/caioricciuti/duck-ui/tree/main/src/services/engine/drivers) (Database drivers), [`src/store/slices/querySlice.ts`](https://github.com/caioricciuti/duck-ui/blob/main/src/store/slices/querySlice.ts) (Query state), [`src/services/engine/index.ts`](https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/index.ts) (Engine registry), [`src/lib/duckBrain/index.ts`](https://github.com/caioricciuti/duck-ui/blob/main/src/lib/duckBrain/index.ts) (Duck Brain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workbench UI"]
  node_app["App routing<br/>[main.tsx]"]
  node_home["Workspace home<br/>[Home.tsx]"]
  node_editor["SQL editor<br/>[SqlEditor.tsx]"]
  node_tabs["Workspace tabs<br/>[WorkspaceTabs.tsx]"]
end

subgraph group_execution["Data and Queries"]
  node_import["Data import<br/>[FileImporter.tsx]"]
  node_engine["Engine registry<br/>[index.ts]"]
  node_sessions["Connection sessions<br/>[session.ts]"]
  node_drivers["Database drivers"]
  node_query["Query state<br/>[querySlice.ts]"]
  node_stream["Query streaming<br/>[queryStream.ts]"]
  node_duckdb["DuckDB services"]
end

subgraph group_analysis["Analysis Tools"]
  node_results["Results grid<br/>[DuckUItable.tsx]"]
  node_charts["Charts"]
  node_notebook["Notebooks<br/>[NotebookTab.tsx]"]
  node_dashboard["Dashboards<br/>[queryRunner.ts]"]
end

subgraph group_state["Local Persistence"]
  node_persistence[("Persistence repositories")]
  node_history["Query history"]
end

subgraph group_sharing["Sharing and AI"]
  node_share["Share links<br/>[index.ts]"]
  node_urlhook["URL analysis loader<br/>[useQueryFromURL.ts]"]
  node_collab["Live collaboration<br/>[liveSession.ts]"]
  node_assistant["Duck Brain<br/>[index.ts]"]
  node_webllm["In-browser AI<br/>[webllm.service.ts]"]
end

node_user(("Workbench user"))
node_externaldb["External DuckDB"]
node_aiapi["AI provider APIs"]

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_home
node_query -->|"executes via"| node_engine
node_engine -->|"resolves session"| node_sessions
node_sessions -->|"dispatches to"| node_drivers
node_drivers -->|"produces events"| node_stream
node_query -->|"collects"| node_stream
node_query -->|"records execution"| node_history
node_history -->|"stores through"| node_persistence
node_drivers -->|"uses"| node_duckdb
node_drivers -.->|"connects to"| node_externaldb
node_dashboard -->|"collects execution"| node_engine
node_urlhook -->|"decodes payload"| node_share
node_share -->|"returns analysis"| node_urlhook
node_assistant -.->|"supports local model"| node_webllm
node_assistant -.->|"calls provider"| node_aiapi

click node_app "https://github.com/caioricciuti/duck-ui/blob/main/src/main.tsx"
click node_home "https://github.com/caioricciuti/duck-ui/blob/main/src/pages/Home.tsx"
click node_editor "https://github.com/caioricciuti/duck-ui/blob/main/src/components/editor/SqlEditor.tsx"
click node_tabs "https://github.com/caioricciuti/duck-ui/blob/main/src/components/workspace/WorkspaceTabs.tsx"
click node_import "https://github.com/caioricciuti/duck-ui/blob/main/src/components/explorer/FileImporter.tsx"
click node_engine "https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/index.ts"
click node_sessions "https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/session.ts"
click node_drivers "https://github.com/caioricciuti/duck-ui/tree/main/src/services/engine/drivers"
click node_query "https://github.com/caioricciuti/duck-ui/blob/main/src/store/slices/querySlice.ts"
click node_stream "https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/queryStream.ts"
click node_duckdb "https://github.com/caioricciuti/duck-ui/tree/main/src/services/duckdb"
click node_results "https://github.com/caioricciuti/duck-ui/blob/main/src/components/table/DuckUItable.tsx"
click node_charts "https://github.com/caioricciuti/duck-ui/blob/main/src/components/charts/ChartVisualizationPro.tsx"
click node_notebook "https://github.com/caioricciuti/duck-ui/blob/main/src/components/notebook/NotebookTab.tsx"
click node_dashboard "https://github.com/caioricciuti/duck-ui/blob/main/src/services/dashboard/queryRunner.ts"
click node_persistence "https://github.com/caioricciuti/duck-ui/tree/main/src/services/persistence/repositories"
click node_history "https://github.com/caioricciuti/duck-ui/blob/main/src/services/persistence/repositories/queryHistoryRepository.ts"
click node_share "https://github.com/caioricciuti/duck-ui/blob/main/src/lib/share/index.ts"
click node_urlhook "https://github.com/caioricciuti/duck-ui/blob/main/src/hooks/useQueryFromURL.ts"
click node_collab "https://github.com/caioricciuti/duck-ui/blob/main/src/services/collaboration/liveSession.ts"
click node_assistant "https://github.com/caioricciuti/duck-ui/blob/main/src/lib/duckBrain/index.ts"
click node_webllm "https://github.com/caioricciuti/duck-ui/blob/main/src/lib/duckBrain/webllm.service.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_app,node_home,node_editor,node_tabs,node_user toneBlue
class node_import,node_engine,node_sessions,node_drivers,node_query,node_stream,node_duckdb toneAmber
class node_results,node_charts,node_notebook,node_dashboard,node_aiapi toneMint
class node_persistence,node_history toneRose
class node_share,node_urlhook,node_collab,node_assistant,node_webllm,node_externaldb toneIndigo
```

## Components

### Workbench UI

- [App routing](https://github.com/caioricciuti/duck-ui/blob/main/src/main.tsx): `src/main.tsx`
- [Workspace home](https://github.com/caioricciuti/duck-ui/blob/main/src/pages/Home.tsx): `src/pages/Home.tsx`
- [SQL editor](https://github.com/caioricciuti/duck-ui/blob/main/src/components/editor/SqlEditor.tsx): `src/components/editor/SqlEditor.tsx`
- [Workspace tabs](https://github.com/caioricciuti/duck-ui/blob/main/src/components/workspace/WorkspaceTabs.tsx): `src/components/workspace/WorkspaceTabs.tsx`

### Data and Queries

- [Data import](https://github.com/caioricciuti/duck-ui/blob/main/src/components/explorer/FileImporter.tsx): `src/components/explorer/FileImporter.tsx`
- [Engine registry](https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/index.ts): `src/services/engine/index.ts`
- [Connection sessions](https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/session.ts): `src/services/engine/session.ts`
- [Database drivers](https://github.com/caioricciuti/duck-ui/tree/main/src/services/engine/drivers): `src/services/engine/drivers`
- [Query state](https://github.com/caioricciuti/duck-ui/blob/main/src/store/slices/querySlice.ts): `src/store/slices/querySlice.ts`
- [Query streaming](https://github.com/caioricciuti/duck-ui/blob/main/src/services/engine/queryStream.ts): `src/services/engine/queryStream.ts`
- [DuckDB services](https://github.com/caioricciuti/duck-ui/tree/main/src/services/duckdb): `src/services/duckdb`

### Analysis Tools

- [Results grid](https://github.com/caioricciuti/duck-ui/blob/main/src/components/table/DuckUItable.tsx): `src/components/table/DuckUItable.tsx`
- [Charts](https://github.com/caioricciuti/duck-ui/blob/main/src/components/charts/ChartVisualizationPro.tsx): `src/components/charts/ChartVisualizationPro.tsx`
- [Notebooks](https://github.com/caioricciuti/duck-ui/blob/main/src/components/notebook/NotebookTab.tsx): `src/components/notebook/NotebookTab.tsx`
- [Dashboards](https://github.com/caioricciuti/duck-ui/blob/main/src/services/dashboard/queryRunner.ts): `src/services/dashboard/queryRunner.ts`

### Local Persistence

- [Persistence repositories](https://github.com/caioricciuti/duck-ui/tree/main/src/services/persistence/repositories): `src/services/persistence/repositories`
- [Query history](https://github.com/caioricciuti/duck-ui/blob/main/src/services/persistence/repositories/queryHistoryRepository.ts): `src/services/persistence/repositories/queryHistoryRepository.ts`

### Sharing and AI

- [Share links](https://github.com/caioricciuti/duck-ui/blob/main/src/lib/share/index.ts): `src/lib/share/index.ts`
- [URL analysis loader](https://github.com/caioricciuti/duck-ui/blob/main/src/hooks/useQueryFromURL.ts): `src/hooks/useQueryFromURL.ts`
- [Live collaboration](https://github.com/caioricciuti/duck-ui/blob/main/src/services/collaboration/liveSession.ts): `src/services/collaboration/liveSession.ts`
- [Duck Brain](https://github.com/caioricciuti/duck-ui/blob/main/src/lib/duckBrain/index.ts): `src/lib/duckBrain/index.ts`
- [In-browser AI](https://github.com/caioricciuti/duck-ui/blob/main/src/lib/duckBrain/webllm.service.ts): `src/lib/duckBrain/webllm.service.ts`

### Other components

- **Workbench user**
- **External DuckDB**
- **AI provider APIs**

## Connections

- Workbench user → App routing: opens
- App routing → Workspace home: routes to
- Query state → Engine registry: executes via
- Engine registry → Connection sessions: resolves session
- Connection sessions → Database drivers: dispatches to
- Database drivers → Query streaming: produces events
- Query state → Query streaming: collects
- Query state → Query history: records execution
- Query history → Persistence repositories: stores through
- Database drivers → DuckDB services: uses
- Database drivers → External DuckDB: connects to
- Dashboards → Engine registry: collects execution
- URL analysis loader → Share links: decodes payload
- Share links → URL analysis loader: returns analysis
- Duck Brain → In-browser AI: supports local model
- Duck Brain → AI provider APIs: calls provider