How cin12211/orca-q works
1. Product shape
OrcaQ is a desktop database editor, not a pure web app. The architecture centers on an Electron shell wrapping a Nuxt 3/Vue 3 frontend, with a local Node.js backend for database operations and desktop integration.
2. Runtime split
The app is divided into:
- Electron main process for native app lifecycle, menus, window creation, IPC, and local data initialization.
- Electron preload for safe bridge APIs.
- Nuxt renderer for the UI and route-based feature screens.
- Server API layer inside the Nuxt app for database and AI-related operations.
3. Top-level UI routing
The pages/ tree shows the main navigation model: workspaces contain connections, and each connection opens domain views like explorer, quick query, raw query, ERD, instance insights, agent, and user permissions. This route hierarchy is the primary UI boundary for diagramming.
4. Feature modules
Most product functionality lives in components/modules/. Each module is a bounded feature with its own components, hooks, constants, utils, and sometimes docs. Key modules are:
- workspace and connection for app setup and database access
- quick-query and raw-query for data querying/editing
- management for explorer, schemas, export, roles, agents, and ERD
- settings, command-palette, instance-insights, and agent for cross-cutting capabilities
5. Shared UI foundation
components/ui/ is a reusable design-system layer built from many small Vue primitives. components/base/ contains more specialized building blocks such as the SQL editor, tree/file browser, dynamic tables, and context menus. These feed the feature modules rather than containing business logic themselves.
6. State and orchestration
The core/stores/ and core/composables/ directories act as the app’s client-side orchestration layer. Stores hold persistent app state such as workspaces, tab views, schema state, explorer state, and activity bar state. Composables encapsulate behaviors like hotkeys, streaming, clipboard, table actions, appearance, and query builder logic.
7. Persistence boundary
Local app data is persisted separately from database content. The core/persist/ layer and Electron main utilities indicate IndexedDB/NeDB-backed storage for workspaces, connections, tab views, quick-query logs, and workspace state. This is the app’s offline/local state boundary; actual database reads/writes happen through the server API and database adapters.
8. Backend API surface
server/api/ exposes the operation endpoints used by the renderer. The major API groups are:
- query for raw and streamed SQL execution
- tables and views for schema/data operations
- metadata for ERD and schema discovery
- database-roles for user/permission management
- instance-insights for monitoring/diagnostics
- database-export and database-import
- ai for agent/chat integration
9. Database abstraction layer
server/infrastructure/database/ is the backend’s domain adapter layer. It separates database-specific logic into factories and adapters by capability: query, tables, views, metadata, metrics, roles, and instance insights. The current implementation is heavily Postgres-oriented, while server/infrastructure/driver/ defines the lower-level DB connection abstraction and driver selection, including MySQL support scaffolding.
10. AI assistant pipeline
The agent subsystem is split across UI, API, and infrastructure. The frontend components/modules/agent/ renders chat, tool messages, approvals, exports, and reasoning blocks. server/api/ai/* handles requests, while server/infrastructure/agent/ defines prompts, tools, SQL/renderers, and schema translation. This is a distinct pipeline from standard query execution.
11. Desktop-specific integrations
Electron src/main/ owns IPC channels for workspace state, connections, tab views, quick query logs, and row query files, plus window menus and port/server bootstrap. The preload layer exposes a controlled API to the renderer. This boundary is important because several UI features depend on main-process services rather than browser-only code.
12. Support systems
The repo includes strong supporting architecture around the product:
- extensive docs under docs/ and feature-specific docs in modules
- Storybook for isolated component development
- Playwright and Vitest test suites spanning UI, composables, and server infrastructure
- release/build tooling for app packaging, deployment, and an npx-package
- GitHub and .specify automation for spec-driven feature development
13. Primary data flow to diagram
The most important end-to-end flow is: user action in a page/module → composable/store orchestration → Nuxt server API call or Electron IPC → database/desktop persistence layer → response back into feature-specific UI. Query, schema, and admin workflows all follow this pattern, with the agent flow adding a parallel AI/tool-rendering path.
Main entry points: index.vue Route pages · execute.post.ts Server API · BaseCodeEditor.vue Base widgets · QuickQuery.vue Quick query
Components 23
Runtime shells
Electron and Nuxt runtime boundaries
- Nuxt shell · App root, layouts, middleware, and route hosting
app.vue
Renderer app
UI routes, feature modules, shared components, and client orchestration
- Route pages · Workspace and connection route hierarchy for the main UI surfaces
pages/[workspaceId]/[connectionId]/index.vue - App shell · Activity bar, sidebars, tab views, and status bar scaffolding
components/modules/app-shell/index.ts - Workspace · Workspace creation, listing, tour, and entry management
components/modules/workspace/containers/Workspaces.vue - Connection · Connection creation, SSL/SSH config, status, and persistence-facing form logic
components/modules/connection/containers/ManagementConnection.vue - Quick query · Table and view browsing, CRUD-like data editing, filtering, and history
components/modules/quick-query/QuickQuery.vue - Raw query · SQL editor, streaming execution, explain plans, variables, and results
components/modules/raw-query/RawQuery.vue - Management · Explorer, schemas, export, roles, and related database administration views
components/modules/management/index.ts - ERD diagram · Entity-relationship visualization and table graph controls
components/modules/erd-diagram/ErdDiagram.vue - Agent UI · Chat workspace, tool messages, approvals, reasoning, and export previews
components/modules/agent/AgentWorkspace.vue - Settings · Appearance, editor, quick query, agent, and table configuration screens
components/modules/settings/containers/SettingsContainer.vue - UI base · Reusable Vue primitives and shared visual components
components/ui/button/Button.vue - Base widgets · SQL editor, dynamic table, tree browser, and context menu building blocks
components/base/code-editor/BaseCodeEditor.vue - Client state · Pinia stores and composables for tabs, workspaces, hotkeys, streaming, and query behavior
core/stores/useWorkspacesStore.ts
Server backend
Nuxt server API and database/agent infrastructure
- Server API · Endpoint surface for query, tables, views, metadata, roles, export/import, instance insights, and AI
server/api/query/execute.post.ts - DB adapters · Capability-specific adapters and factories for query, tables, views, metadata, roles, metrics, and insights
server/infrastructure/database/adapters/index.ts - Driver layer · Low-level database connection abstraction and driver selection, including Postgres and MySQL scaffolding
server/infrastructure/driver/factory.ts - Agent pipeline · Prompts, tools, renderers, schema translation, and response shaping for AI-assisted database actions
server/infrastructure/agent/core/provider.ts
Desktop integration
Electron main, preload, and persistence bridges
- Electron main · Native app lifecycle, menus, window bootstrap, and IPC coordination
electron/src/main/index.ts - Preload bridge · Controlled APIs exposed to the renderer
electron/src/preload/index.ts - Local persist · IndexedDB-backed workspace, connection, tab view, query log, and workspace state storage
core/persist/workspaceIDBApi.ts - Desktop IPC · IPC channels for workspaces, connections, tab views, logs, and query files plus window/bootstrap utilities
electron/src/main/ipc/index.ts
Tooling
Docs, tests, automation, and release support
- Docs & tests · Architecture docs, feature docs, tests, Playwright, Vitest, and spec-driven development assets
docs/ARCHITECTURE.md
Connections 31
- Nuxt shell → Route pages: hosts · Renderer app serves the route hierarchy
- Route pages → App shell: renders · Main screens are framed by the shell chrome
- Route pages → Workspace: uses · Workspace routes open workspace management views
- Route pages → Connection: uses · Connection routes drive connection setup and editing
- Route pages → Quick query: uses · Quick query routes render data browsing and mutation flows
- Route pages → Raw query: uses · Raw query routes render SQL execution and results flows
- Route pages → Management: uses · Management routes render schema and admin tools
- Route pages → ERD diagram: uses · ERD routes render schema visualization screens
- Route pages → Agent UI: uses · Agent routes render the AI assistant workspace
- Route pages → Settings: uses · Workspace-level settings screens connect here
- Workspace → Client state: orchestrated by · Workspace UI relies on stores and composables for state and behavior
- Connection → Client state: orchestrated by · Connection forms and status flows use shared client orchestration
- Quick query → Base widgets: built on · Table browsing and filters depend on shared editor/table/tree primitives
- Raw query → Base widgets: built on · SQL editing and result views depend on editor and table primitives
- Management → Base widgets: built on · Explorer and schema tools are composed from shared widgets
- Agent UI → Base widgets: built on · Chat and tool blocks reuse shared UI primitives
- Base widgets → UI base: composed from · Specialized widgets are assembled from the design-system layer
- Client state → Local persist: persists to · App state is stored locally separate from database content
- Electron main → Desktop IPC: owns · Main process provides IPC and bootstrap services
- Preload bridge → Desktop IPC: exposes · Preload publishes a controlled bridge to renderer code
- Desktop IPC → Local persist: stores · Desktop services initialize and update local databases
- Server API → DB adapters: delegates to · Endpoints call capability-specific database adapters
- DB adapters → Driver layer: connects through · Adapters use the lower-level connection driver abstraction
- Server API → Agent pipeline: routes ai to · AI endpoints feed the assistant orchestration pipeline
- Agent UI → Server API: calls · Frontend chat and tools invoke AI and database endpoints
- Raw query → Server API: executes via · Query execution and explain flows call server endpoints
- Quick query → Server API: reads/writes via · Structured table and view operations use the API surface
- Management → Server API: admin via · Explorer, roles, export, and schema tools call backend endpoints
- ERD diagram → Server API: loads metadata via · Diagram data is sourced from metadata endpoints
- Electron main → Nuxt shell: boots · Electron hosts the Nuxt renderer application
- Docs & tests → Route pages: covers · Tests and docs mirror the main route and feature structure