How nicktikhonov/snap-ql works
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: App.tsx App shell · preload/index.ts Preload bridge · main/index.ts Main entry · SchemaViewer.tsx Schema viewer
Components 19
Desktop App
Electron runtime and packaging boundary
- Electron shell · App lifecycle and window container
src/main/index.ts - Preload bridge · Secure API surface exposed to the renderer
src/preload/index.ts - Bridge types · Type definitions for the preload API
src/preload/index.d.ts
Main Process
Privileged orchestration and local services
- Main entry · Bootstraps app, IPC, and window setup
src/main/index.ts - Database service · Connects to PostgreSQL/MySQL and runs queries
src/main/lib/db.ts - State store · Saves connections, history, and favorites
src/main/lib/state.ts - AI service · Handles schema-aware prompt and completion calls
src/main/lib/ai.ts
Renderer UI
React-based single-window interface
- App shell · Top-level UI composition
src/renderer/src/App.tsx - Connections · Add and manage database connections
src/renderer/src/components/ConnectionDialog.tsx - SQL editor · Compose and execute queries
src/renderer/src/components/SQLEditor.tsx - Schema viewer · Browse tables, cards, and details
src/renderer/src/components/SchemaViewer.tsx - Results table · Displays query output
src/renderer/src/components/ResultsTable.tsx - Chart view · Visualizes query results as graphs
src/renderer/src/components/Graph.tsx - AI chat · Conversational query help and generation
src/renderer/src/components/AIChat.tsx - Settings · App preferences and configuration
src/renderer/src/components/Settings.tsx - Sidebar · Primary navigation and context switching
src/renderer/src/components/Sidebar.tsx
External Systems
User-owned databases and AI services
- DB servers · User-owned databases queried by the app
- AI provider · External model service used for assistance
- Local profile · Connection-specific state stored on the machine
Connections 25
- 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