# nicktikhonov/snap-ql architecture

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

- Interactive diagram: https://gitdiagram.com/nicktikhonov/snap-ql
- Repository: https://github.com/nicktikhonov/snap-ql

## Overview

1. **What this repo is**
   - SnapQL is a desktop database assistant built as an **Electron app**.
   - The product focuses on **schema-aware query generation**, **SQL execution**, **charting results**, and **AI chat** for PostgreSQL/MySQL databases.
   - The architecture is intentionally **local-first**: database credentials stay on the user’s machine.

2. **Top-level runtime shape**
   - The app is split into the standard Electron boundaries:
     - **Main process**: app lifecycle, database access, AI integration, persistence.
     - **Preload layer**: the secure IPC bridge between main and renderer.
     - **Renderer process**: the UI built with React.
   - This separation is the core architectural boundary for the diagram.

3. **Main-process responsibilities**
   - `src/main/index.ts` is the Electron entrypoint and likely wires the window, IPC handlers, and app startup.
   - `src/main/lib/db.ts` is the database subsystem for connecting to PostgreSQL/MySQL and executing queries.
   - `src/main/lib/state.ts` manages persisted app state, likely including saved connections, query history, and favorites.
   - `src/main/lib/ai.ts` handles AI interactions for query generation or schema-aware assistance.

4. **Data and control flow**
   - The renderer never talks directly to the database.
   - UI actions go from **React components → preload API → main IPC handlers → db/ai/state modules**.
   - Results flow back the same way: database query results, schema metadata, AI responses, and saved state are returned to the renderer for display.

5. **Renderer/UI subsystem**
   - `src/renderer/src/App.tsx` is the root UI shell.
   - Feature components are organized by capability:
     - `ConnectionDialog.tsx` for managing DB connections.
     - `SQLEditor.tsx` for composing/running SQL.
     - `SchemaViewer.tsx`, `SchemaCard.tsx`, and `TableDetailView.tsx` for browsing database structure.
     - `ResultsTable.tsx` for query output.
     - `Graph.tsx` and `GraphEditDialog.tsx` for charting/visualizing query results.
     - `AIChat.tsx` for conversational query help.
     - `Settings.tsx` and `Sidebar.tsx` for app-wide navigation/configuration.
   - The renderer is a **single-window desktop UI**, not a server-rendered web app.

6. **Schema-driven workflow**
   - A key product loop is: **connect to database → inspect schema → ask AI or write SQL → run query → view table or chart**.
   - The schema viewer components suggest the app pulls metadata from the database and uses it to guide both query generation and the UI.
   - This schema awareness is a functional boundary between raw DB connectivity and higher-level assistance features.

7. **AI subsystem**
   - `src/main/lib/ai.ts` implies AI calls are centralized in the main process rather than the browser UI.
   - The README says the user supplies their own **OpenAI or Claude key**, so the app likely forwards selected context such as schema information and user prompts to external AI services.
   - Architecturally, AI is an optional external service layered on top of local database state and metadata.

8. **Persistence and multi-connection model**
   - The repo emphasizes **multiple database connections**, each with **connection-specific query history and favorites**.
   - That persistence layer appears to be handled in the main process via `state.ts` and possibly `db.ts` depending on storage design.
   - This means state is organized around a connection context rather than as one global query workspace.

9. **Security boundary**
   - The preload layer (`src/preload/index.ts` and its type definitions) is important because it exposes only a controlled API surface to the renderer.
   - This is the security boundary that keeps database credentials and IPC implementation details out of the React layer.
   - In an architecture diagram, this should be drawn as a strict bridge between UI and privileged operations.

10. **Testing and reliability**
   - There is at least one integration test in `src/main/__tests__/state.integration.test.ts`, which suggests state persistence behavior is important enough to validate end-to-end.
   - The `spec/` folder contains product/design specs such as `schema-viewer.md`, `auto-run.md`, and `mult.md`, indicating feature-oriented behavior is documented outside the code.
   - That implies the app’s core complexity is in orchestration and stateful UX, not just isolated UI widgets.

11. **Build and packaging**
   - The project uses **Electron Vite** for development/build tooling (`electron.vite.config.ts`) and **electron-builder** for packaging (`electron-builder.yml`).
   - The `build/` directory includes platform assets like `icon.icns` and macOS entitlements, so desktop distribution is a first-class concern.
   - The `Makefile` supports local dev, installation, linking to PATH, and building distributables.

12. **Frontend stack**
   - The renderer uses **React + TypeScript**, styled with **Tailwind CSS** and a large set of reusable UI primitives under `src/renderer/src/components/ui`.
   - The presence of hooks like `useConnection` and `useConnections` suggests local client state is organized around selected connection context and its available resources.
   - The app is a desktop product, but the renderer is still a modular SPA-like front end.

13. **External services and integration points**
   - Primary external dependencies are:
     - User-provided **PostgreSQL/MySQL databases**
     - User-provided **OpenAI/Claude API keys**
   - No backend service is present in the repo; the desktop app itself is the orchestrator between the local machine, the database, and the AI provider.

14. **How to draw the architecture**
   - The most accurate diagram would show:
     - A **desktop Electron shell**
     - A **main-process orchestration layer**
     - A **preload IPC boundary**
     - A **React renderer UI**
     - External edges to **database servers** and **AI providers**
     - A local **persistent state store** for connections/history/favorites
   - The dominant flow is user-driven: connect, inspect schema, generate or edit SQL, execute, then visualize results or continue in chat.

Main entry points: [`src/renderer/src/App.tsx`](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/App.tsx) (App shell), [`src/preload/index.ts`](https://github.com/nicktikhonov/snap-ql/blob/main/src/preload/index.ts) (Preload bridge), [`src/main/index.ts`](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/index.ts) (Main entry), [`src/renderer/src/components/SchemaViewer.tsx`](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/SchemaViewer.tsx) (Schema viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop App"]
  node_electron_shell["Electron shell<br/>desktop runtime<br/>[index.ts]"]
  node_preload_bridge["Preload bridge<br/>ipc bridge<br/>[index.ts]"]
  node_preload_types["Bridge types<br/>ipc typings<br/>[index.d.ts]"]
end

subgraph group_main["Main Process"]
  node_main_entry["Main entry<br/>startup<br/>[index.ts]"]
  node_db_service[("Database service<br/>db access<br/>[db.ts]")]
  node_state_store[("State store<br/>persistence<br/>[state.ts]")]
  node_ai_service(("AI service<br/>assistant<br/>[ai.ts]"))
end

subgraph group_renderer["Renderer UI"]
  node_app_shell["App shell<br/>react root<br/>[App.tsx]"]
  node_conn_dialog["Connections<br/>ui feature"]
  node_sql_editor["SQL editor<br/>ui feature<br/>[SQLEditor.tsx]"]
  node_schema_viewer["Schema viewer<br/>schema ui<br/>[SchemaViewer.tsx]"]
  node_results_table["Results table<br/>result ui<br/>[ResultsTable.tsx]"]
  node_graph_view["Chart view<br/>visualization<br/>[Graph.tsx]"]
  node_ai_chat["AI chat<br/>assistant ui<br/>[AIChat.tsx]"]
  node_settings_ui["Settings<br/>ui feature<br/>[Settings.tsx]"]
  node_sidebar_ui["Sidebar<br/>navigation<br/>[Sidebar.tsx]"]
end

subgraph group_external["External Systems"]
  node_local_db[("DB servers<br/>postgres/mysql")]
  node_ai_provider(("AI provider<br/>openai/claude"))
  node_user_store[("Local profile<br/>local persistence")]
end

node_electron_shell -->|"starts"| node_main_entry
node_main_entry -->|"exposes"| node_preload_bridge
node_preload_bridge -->|"types"| node_preload_types
node_preload_bridge -->|"IPC API"| node_app_shell
node_app_shell -->|"navigates"| node_sidebar_ui
node_app_shell -->|"manages"| node_conn_dialog
node_app_shell -->|"queries"| node_sql_editor
node_app_shell -->|"browses"| node_schema_viewer
node_app_shell -->|"renders"| node_results_table
node_app_shell -->|"charts"| node_graph_view
node_app_shell -->|"assists"| node_ai_chat
node_app_shell -->|"configures"| node_settings_ui
node_sql_editor -->|"run SQL"| node_preload_bridge
node_schema_viewer -->|"load schema"| node_preload_bridge
node_ai_chat -->|"ask AI"| node_preload_bridge
node_preload_bridge -->|"ipc"| node_main_entry
node_main_entry -->|"routes queries"| node_db_service
node_main_entry -->|"persists state"| node_state_store
node_main_entry -->|"delegates AI"| node_ai_service
node_db_service -->|"connects"| node_local_db
node_ai_service -->|"calls"| node_ai_provider
node_state_store -->|"saves"| node_user_store
node_conn_dialog -->|"stores connections"| node_state_store
node_results_table -->|"promotes"| node_graph_view
node_schema_viewer -->|"guides prompts"| node_ai_chat

click node_electron_shell "https://github.com/nicktikhonov/snap-ql/blob/main/src/main/index.ts"
click node_main_entry "https://github.com/nicktikhonov/snap-ql/blob/main/src/main/index.ts"
click node_db_service "https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/db.ts"
click node_state_store "https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/state.ts"
click node_ai_service "https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/ai.ts"
click node_preload_bridge "https://github.com/nicktikhonov/snap-ql/blob/main/src/preload/index.ts"
click node_preload_types "https://github.com/nicktikhonov/snap-ql/blob/main/src/preload/index.d.ts"
click node_app_shell "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/App.tsx"
click node_conn_dialog "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/ConnectionDialog.tsx"
click node_sql_editor "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/SQLEditor.tsx"
click node_schema_viewer "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/SchemaViewer.tsx"
click node_results_table "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/ResultsTable.tsx"
click node_graph_view "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Graph.tsx"
click node_ai_chat "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/AIChat.tsx"
click node_settings_ui "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Settings.tsx"
click node_sidebar_ui "https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Sidebar.tsx"

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_electron_shell,node_preload_bridge,node_preload_types toneBlue
class node_main_entry,node_db_service,node_state_store,node_ai_service toneAmber
class node_app_shell,node_conn_dialog,node_sql_editor,node_schema_viewer,node_results_table,node_graph_view,node_ai_chat,node_settings_ui,node_sidebar_ui toneMint
class node_local_db,node_ai_provider,node_user_store toneRose
```

## Components

### Desktop App

Electron runtime and packaging boundary

- [Electron shell](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/index.ts): desktop runtime · App lifecycle and window container · `src/main/index.ts`
- [Preload bridge](https://github.com/nicktikhonov/snap-ql/blob/main/src/preload/index.ts): ipc bridge · Secure API surface exposed to the renderer · `src/preload/index.ts`
- [Bridge types](https://github.com/nicktikhonov/snap-ql/blob/main/src/preload/index.d.ts): ipc typings · Type definitions for the preload API · `src/preload/index.d.ts`

### Main Process

Privileged orchestration and local services

- [Main entry](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/index.ts): startup · Bootstraps app, IPC, and window setup · `src/main/index.ts`
- [Database service](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/db.ts): db access · Connects to PostgreSQL/MySQL and runs queries · `src/main/lib/db.ts`
- [State store](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/state.ts): persistence · Saves connections, history, and favorites · `src/main/lib/state.ts`
- [AI service](https://github.com/nicktikhonov/snap-ql/blob/main/src/main/lib/ai.ts): assistant · Handles schema-aware prompt and completion calls · `src/main/lib/ai.ts`

### Renderer UI

React-based single-window interface

- [App shell](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/App.tsx): react root · Top-level UI composition · `src/renderer/src/App.tsx`
- [Connections](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/ConnectionDialog.tsx): ui feature · Add and manage database connections · `src/renderer/src/components/ConnectionDialog.tsx`
- [SQL editor](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/SQLEditor.tsx): ui feature · Compose and execute queries · `src/renderer/src/components/SQLEditor.tsx`
- [Schema viewer](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/SchemaViewer.tsx): schema ui · Browse tables, cards, and details · `src/renderer/src/components/SchemaViewer.tsx`
- [Results table](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/ResultsTable.tsx): result ui · Displays query output · `src/renderer/src/components/ResultsTable.tsx`
- [Chart view](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Graph.tsx): visualization · Visualizes query results as graphs · `src/renderer/src/components/Graph.tsx`
- [AI chat](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/AIChat.tsx): assistant ui · Conversational query help and generation · `src/renderer/src/components/AIChat.tsx`
- [Settings](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Settings.tsx): ui feature · App preferences and configuration · `src/renderer/src/components/Settings.tsx`
- [Sidebar](https://github.com/nicktikhonov/snap-ql/blob/main/src/renderer/src/components/Sidebar.tsx): navigation · Primary navigation and context switching · `src/renderer/src/components/Sidebar.tsx`

### External Systems

User-owned databases and AI services

- **DB servers**: postgres/mysql · User-owned databases queried by the app
- **AI provider**: openai/claude · External model service used for assistance
- **Local profile**: local persistence · Connection-specific state stored on the machine

## Connections

- Electron shell → Main entry: starts · Launches the main process entrypoint
- Main entry → Preload bridge: exposes · Attaches the secure preload API
- Preload bridge → Bridge types: types · Defines the renderer-facing contract
- Preload bridge → App shell: IPC API · Renderer calls privileged operations through the bridge
- App shell → Sidebar: navigates · Coordinates the main desktop workspace
- App shell → Connections: manages · Opens connection management flows
- App shell → SQL editor: queries · Hosts the query composition and execution workflow
- App shell → Schema viewer: browses · Shows database metadata and schema context
- App shell → Results table: renders · Displays query results to the user
- App shell → Chart view: charts · Visualizes result sets
- App shell → AI chat: assists · Provides conversational query help
- App shell → Settings: configures · Handles app settings and preferences
- SQL editor → Preload bridge: run SQL · Sends query requests through IPC
- Schema viewer → Preload bridge: load schema · Requests schema metadata from privileged code
- AI chat → Preload bridge: ask AI · Sends prompts and context through IPC
- Preload bridge → Main entry: ipc · Routes renderer requests to main-process handlers
- Main entry → Database service: routes queries · Delegates database operations to the DB layer
- Main entry → State store: persists state · Stores connection-specific history and favorites
- Main entry → AI service: delegates AI · Centralizes AI interactions in the main process
- Database service → DB servers: connects · Executes SQL against user databases
- AI service → AI provider: calls · Uses user-provided API keys to reach external models
- State store → Local profile: saves · Keeps local app state on the machine
- Connections → State store: stores connections · Adds and updates connection profiles
- Results table → Chart view: promotes · Result data can be turned into charts
- Schema viewer → AI chat: guides prompts · Schema context supports AI-assisted query generation
