# frectonz/sql-studio architecture

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

- Interactive diagram: https://gitdiagram.com/frectonz/sql-studio
- Repository: https://github.com/frectonz/sql-studio

## Overview

1. **Repo shape**
   - This is a **two-runtime product**: a **Rust command-line backend** plus a **TypeScript/React frontend**.
   - The production app is the **single binary `sql-studio`**; the UI is built separately and then **statically embedded into the Rust executable**.

2. **Primary execution model**
   - A user launches `sql-studio` with a **database-specific subcommand** such as `sqlite`, `libsql`, `postgres`, `mysql`, `duckdb`, `parquet`, `csv`, `clickhouse`, or `mssql`.
   - Those arguments determine the **connection target and driver mode**, and the backend becomes a local database explorer for that datasource.

3. **Rust backend boundary**
   - `src/main.rs` is the backend entrypoint and likely owns:
     - CLI parsing / startup
     - choosing the database connector
     - serving the embedded web UI
     - exposing the API used by the frontend
   - The backend is the **authority for database access**; the frontend does not talk to databases directly.

4. **Database connectivity layer**
   - The application supports multiple database/file backends with different connection styles:
     - local files: SQLite, DuckDB, Parquet, CSV
     - remote servers: libSQL, PostgreSQL, MySQL, ClickHouse, MSSQL
   - Architecture-wise, this implies a **driver abstraction layer** in Rust that normalizes schema inspection, table listing, row paging, and query execution across engines.

5. **Browser UI as a separate client**
   - `ui/` is a standalone **Vite + React** app.
   - It behaves like a client shell for the backend API and is organized around a routed SPA, not server-rendered pages.
   - The frontend is built to be packaged into the binary, but during development it remains its own Node toolchain.

6. **Frontend state and API flow**
   - `ui/src/api.ts` and `ui/src/provider/sql.provider.tsx` suggest a central **SQL/session state layer** that manages:
     - current connection context
     - query execution
     - metadata fetching
     - result pagination/infinite scroll
   - Data flows from **backend API → React state/provider → route-specific views**.

7. **Main user-facing views**
   - The UI is split into route-level screens:
     - `overview` / schema-style metadata view
     - `tables` explorer
     - `query` editor and results
     - `schema` diagram view
   - These are the core “exploration” surfaces and likely share the same backend metadata/query endpoints.

8. **Querying and visualization subsystem**
   - `ui/src/components/editor.tsx` and `editor.config.ts` indicate a **rich SQL editor** with IntelliSense/formatting support.
   - `ui/src/components/erd/*` implements the **ERD visualization**, with layout logic separated from rendering.
   - `ui/src/components/ui/*` is a reusable UI kit for dialogs, tables, tabs, sheets, etc., supporting the explorer workflow.

9. **Documentation site is a separate app**
   - `docs/` is its own **Next.js documentation site**, not part of the runtime product.
   - It contains MDX content for installation, configuration, and database-specific guidance, plus an `/api/docs` route and OG image generation script.
   - In architecture diagrams, this should be shown as a **separate marketing/docs system** connected to the project, not to the app’s runtime data path.

10. **Build, packaging, and release pipeline**
   - The repo uses **Cargo**, **npm/pnpm**, **Nix**, and **GitHub Actions**.
   - CI/release workflows build the Rust binary, the embedded UI, docs assets, and release artifacts; Docker is also supported.
   - `dist-workspace.toml`, `flake.nix`, and the release/image workflows indicate the project is packaged as a **cross-platform distributable desktop-style CLI/web hybrid**.

11. **Important architectural boundary to capture**
   - The most important boundary is:
     - **Database engines and files** on one side
     - **Rust backend API** in the middle
     - **React browser UI** on the other side
   - The backend translates heterogeneous database capabilities into a uniform exploration experience, while the frontend focuses on interaction, rendering, and navigation.

12. **Net result**
   - SQL Studio is best diagrammed as a **local server application**: one binary, one UI, many database adapters, and a browser-based client.
   - The system is optimized for **interactive inspection and ad hoc querying**, not for long-running multi-user service orchestration.

Main entry points: [`ui/src/provider/sql.provider.tsx`](https://github.com/frectonz/sql-studio/blob/main/ui/src/provider/sql.provider.tsx) (SQL state), [`.github/workflows/release.yml`](https://github.com/frectonz/sql-studio/blob/main/.github/workflows/release.yml) (Build pipeline), [`docs/app/page.tsx`](https://github.com/frectonz/sql-studio/blob/main/docs/app/page.tsx) (Docs site), [`src/main.rs`](https://github.com/frectonz/sql-studio/blob/main/src/main.rs) (Rust backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_dbs[("Databases<br/>engines/files")]
  node_backend["Rust backend<br/>CLI/API host<br/>[main.rs]"]
end

subgraph group_frontend["Frontend"]
  node_uiapp["UI shell<br/>Vite/React app<br/>[main.tsx]"]
  node_apiclient["API client<br/>HTTP bridge<br/>[api.ts]"]
  node_sqlstate["SQL state<br/>provider/store<br/>[sql.provider.tsx]"]
  node_overview["Overview<br/>route screen<br/>[index.tsx]"]
  node_tables["Tables<br/>route screen<br/>[tables.tsx]"]
  node_query["Query<br/>route screen<br/>[query.tsx]"]
  node_schema["Schema<br/>route screen<br/>[schema.tsx]"]
  node_editor["SQL editor<br/>editor component<br/>[editor.tsx]"]
  node_erd{{"ERD view<br/>visualization<br/>[erd-diagram.tsx]"}}
  node_uikit["UI kit<br/>shared components"]
end

subgraph group_docs["Docs"]
  node_docsite["Docs site<br/>Next.js site<br/>[page.tsx]"]
  node_docpages["Docs content<br/>MDX docs<br/>[page.mdx]"]
  node_docapi["Docs API<br/>route handler<br/>[route.ts]"]
end

subgraph group_delivery["Delivery"]
  node_build["Build pipeline<br/>CI/release<br/>[release.yml]"]
  node_nix["Nix flake<br/>packaging<br/>[flake.nix]"]
end

node_dbs -->|"connects to"| node_backend
node_backend -->|"serves"| node_uiapp
node_uiapp -->|"uses"| node_apiclient
node_apiclient -->|"hydrates"| node_sqlstate
node_sqlstate -->|"drives"| node_overview
node_sqlstate -->|"drives"| node_tables
node_sqlstate -->|"drives"| node_query
node_sqlstate -->|"drives"| node_schema
node_query -->|"contains"| node_editor
node_schema -->|"renders"| node_erd
node_editor -->|"composes"| node_uikit
node_erd -->|"composes"| node_uikit
node_docsite -->|"contains"| node_docpages
node_docsite -->|"uses"| node_docapi
node_build -->|"builds"| node_backend
node_build -->|"packages"| node_uiapp
node_build -->|"publishes"| node_docsite
node_build -->|"uses"| node_nix

click node_backend "https://github.com/frectonz/sql-studio/blob/main/src/main.rs"
click node_uiapp "https://github.com/frectonz/sql-studio/blob/main/ui/src/main.tsx"
click node_apiclient "https://github.com/frectonz/sql-studio/blob/main/ui/src/api.ts"
click node_sqlstate "https://github.com/frectonz/sql-studio/blob/main/ui/src/provider/sql.provider.tsx"
click node_overview "https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/index.tsx"
click node_tables "https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/tables.tsx"
click node_query "https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/query.tsx"
click node_schema "https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/schema.tsx"
click node_editor "https://github.com/frectonz/sql-studio/blob/main/ui/src/components/editor.tsx"
click node_erd "https://github.com/frectonz/sql-studio/blob/main/ui/src/components/erd/erd-diagram.tsx"
click node_uikit "https://github.com/frectonz/sql-studio/tree/main/ui/src/components/ui"
click node_docsite "https://github.com/frectonz/sql-studio/blob/main/docs/app/page.tsx"
click node_docpages "https://github.com/frectonz/sql-studio/blob/main/docs/app/docs/page.mdx"
click node_docapi "https://github.com/frectonz/sql-studio/blob/main/docs/app/api/docs/route.ts"
click node_build "https://github.com/frectonz/sql-studio/blob/main/.github/workflows/release.yml"
click node_nix "https://github.com/frectonz/sql-studio/blob/main/flake.nix"

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_dbs,node_backend toneBlue
class node_uiapp,node_apiclient,node_sqlstate,node_overview,node_tables,node_query,node_schema,node_editor,node_erd,node_uikit toneAmber
class node_docsite,node_docpages,node_docapi toneMint
class node_build,node_nix toneRose
```

## Components

### Runtime

Single-binary Rust backend plus embedded browser client.

- **Databases**: engines/files · Supported local files and remote database backends exposed through one explorer model.
- [Rust backend](https://github.com/frectonz/sql-studio/blob/main/src/main.rs): CLI/API host · Binary entrypoint that parses subcommands, opens connections, serves the embedded UI, and exposes the database API. · `src/main.rs`

### Frontend

Standalone Vite/React SPA that becomes the embedded UI.

- [UI shell](https://github.com/frectonz/sql-studio/blob/main/ui/src/main.tsx): Vite/React app · Browser client that is built separately and embedded into the Rust executable. · `ui/src/main.tsx`
- [API client](https://github.com/frectonz/sql-studio/blob/main/ui/src/api.ts): HTTP bridge · Central frontend API layer for session, metadata, queries, and paging. · `ui/src/api.ts`
- [SQL state](https://github.com/frectonz/sql-studio/blob/main/ui/src/provider/sql.provider.tsx): provider/store · Shared SQL session and connection state used by the route screens. · `ui/src/provider/sql.provider.tsx`
- [Overview](https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/index.tsx): route screen · Metadata and summary view for the current connection. · `ui/src/routes/index.tsx`
- [Tables](https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/tables.tsx): route screen · Table explorer for browsing database objects and rows. · `ui/src/routes/tables.tsx`
- [Query](https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/query.tsx): route screen · Interactive SQL editor and result view. · `ui/src/routes/query.tsx`
- [Schema](https://github.com/frectonz/sql-studio/blob/main/ui/src/routes/schema.tsx): route screen · ERD-focused schema visualization screen. · `ui/src/routes/schema.tsx`
- [SQL editor](https://github.com/frectonz/sql-studio/blob/main/ui/src/components/editor.tsx): editor component · Rich query editor with formatting and IntelliSense support. · `ui/src/components/editor.tsx`
- [ERD view](https://github.com/frectonz/sql-studio/blob/main/ui/src/components/erd/erd-diagram.tsx): visualization · Diagram renderer and layout logic for schema relationships. · `ui/src/components/erd/erd-diagram.tsx`
- [UI kit](https://github.com/frectonz/sql-studio/tree/main/ui/src/components/ui): shared components · Reusable dialogs, tables, tabs, sheets, inputs, and related primitives. · `ui/src/components/ui`

### Docs

Separate Next.js documentation site and content.

- [Docs site](https://github.com/frectonz/sql-studio/blob/main/docs/app/page.tsx): Next.js site · Standalone documentation app with installation, configuration, feature, and database guides. · `docs/app/page.tsx`
- [Docs content](https://github.com/frectonz/sql-studio/blob/main/docs/app/docs/page.mdx): MDX docs · Feature and database guide pages for the product documentation. · `docs/app/docs/page.mdx`
- [Docs API](https://github.com/frectonz/sql-studio/blob/main/docs/app/api/docs/route.ts): route handler · Documentation route used by the docs site. · `docs/app/api/docs/route.ts`

### Delivery

Build, packaging, and release automation.

- [Build pipeline](https://github.com/frectonz/sql-studio/blob/main/.github/workflows/release.yml): CI/release · Cross-platform build, packaging, image, and release automation for Rust, UI, and docs artifacts. · `.github/workflows/release.yml`
- [Nix flake](https://github.com/frectonz/sql-studio/blob/main/flake.nix): packaging · Reproducible development and build environment for the project. · `flake.nix`

## Connections

- Databases → Rust backend: connects to · Database engines and files are accessed only through the Rust backend.
- Rust backend → UI shell: serves · The Rust binary embeds and serves the browser UI.
- UI shell → API client: uses · The SPA talks to the backend through a central API layer.
- API client → SQL state: hydrates · API responses feed the shared SQL/session store.
- SQL state → Overview: drives · Connection state powers the overview screen.
- SQL state → Tables: drives · Connection state powers the table explorer.
- SQL state → Query: drives · Connection state powers query execution and results.
- SQL state → Schema: drives · Connection state powers schema visualization.
- Query → SQL editor: contains · The query screen embeds the SQL editor.
- Schema → ERD view: renders · The schema screen renders the ERD subsystem.
- SQL editor → UI kit: composes · Editor UI relies on shared interface primitives.
- ERD view → UI kit: composes · Diagram views use shared UI components.
- Docs site → Docs content: contains · The docs app is composed of MDX content pages.
- Docs site → Docs API: uses · The docs app includes a docs API route.
- Build pipeline → Rust backend: builds · CI and release workflows compile the Rust binary.
- Build pipeline → UI shell: packages · CI and release workflows build the frontend bundle for embedding.
- Build pipeline → Docs site: publishes · Documentation assets are built and released separately.
- Build pipeline → Nix flake: uses · Reproducible build inputs are defined through Nix.
