# cin12211/orca-q architecture

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

- Interactive diagram: https://gitdiagram.com/cin12211/orca-q
- Repository: https://github.com/cin12211/orca-q

## Overview

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: [`pages/[workspaceId]/[connectionId]/index.vue`](https://github.com/cin12211/orca-q/blob/main/pages/[workspaceId]/[connectionId]/index.vue) (Route pages), [`server/api/query/execute.post.ts`](https://github.com/cin12211/orca-q/blob/main/server/api/query/execute.post.ts) (Server API), [`components/base/code-editor/BaseCodeEditor.vue`](https://github.com/cin12211/orca-q/blob/main/components/base/code-editor/BaseCodeEditor.vue) (Base widgets), [`components/modules/quick-query/QuickQuery.vue`](https://github.com/cin12211/orca-q/blob/main/components/modules/quick-query/QuickQuery.vue) (Quick query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime shells"]
  node_nuxt_shell["Nuxt shell<br/>renderer app<br/>[app.vue]"]
end

subgraph group_frontend["Renderer app"]
  node_route_pages["Route pages<br/>screen routing<br/>[index.vue]"]
  node_app_shell["App shell<br/>workspace chrome<br/>[index.ts]"]
  node_workspace_module["Workspace<br/>[Workspaces.vue]"]
  node_connection_module["Connection<br/>db access setup"]
  node_quick_query_module["Quick query<br/>structured editing<br/>[QuickQuery.vue]"]
  node_raw_query_module["Raw query<br/>sql console<br/>[RawQuery.vue]"]
  node_management_module["Management<br/>admin tools<br/>[index.ts]"]
  node_erd_module["ERD diagram<br/>schema graph<br/>[ErdDiagram.vue]"]
  node_agent_module["Agent UI<br/>ai assistant<br/>[AgentWorkspace.vue]"]
  node_settings_module["Settings<br/>preferences"]
  node_ui_base["UI base<br/>design system<br/>[Button.vue]"]
  node_base_widgets["Base widgets<br/>feature primitives<br/>[BaseCodeEditor.vue]"]
  node_client_state["Client state<br/>stores and composables"]
end

subgraph group_backend["Server backend"]
  node_server_api["Server API<br/>nuxt api<br/>[execute.post.ts]"]
  node_db_adapters["DB adapters<br/>domain adapters<br/>[index.ts]"]
  node_driver_layer["Driver layer<br/>connection drivers<br/>[factory.ts]"]
  node_agent_pipeline["Agent pipeline<br/>ai orchestration<br/>[provider.ts]"]
end

subgraph group_desktop["Desktop integration"]
  node_electron_main["Electron main<br/>desktop lifecycle<br/>[index.ts]"]
  node_electron_preload["Preload bridge<br/>secure bridge<br/>[index.ts]"]
  node_persist_layer[("Local persist<br/>offline state<br/>[workspaceIDBApi.ts]")]
  node_desktop_ipc["Desktop IPC<br/>main-process services<br/>[index.ts]"]
end

subgraph group_support["Tooling"]
  node_docs_tests["Docs & tests<br/>support system<br/>[ARCHITECTURE.md]"]
end

node_nuxt_shell -->|"hosts"| node_route_pages
node_route_pages -->|"renders"| node_app_shell
node_route_pages -->|"uses"| node_workspace_module
node_route_pages -->|"uses"| node_connection_module
node_route_pages -->|"uses"| node_quick_query_module
node_route_pages -->|"uses"| node_raw_query_module
node_route_pages -->|"uses"| node_management_module
node_route_pages -->|"uses"| node_erd_module
node_route_pages -->|"uses"| node_agent_module
node_route_pages -->|"uses"| node_settings_module
node_workspace_module -->|"orchestrated by"| node_client_state
node_connection_module -->|"orchestrated by"| node_client_state
node_quick_query_module -->|"built on"| node_base_widgets
node_raw_query_module -->|"built on"| node_base_widgets
node_management_module -->|"built on"| node_base_widgets
node_agent_module -->|"built on"| node_base_widgets
node_base_widgets -->|"composed from"| node_ui_base
node_client_state -->|"persists to"| node_persist_layer
node_electron_main -->|"owns"| node_desktop_ipc
node_electron_preload -->|"exposes"| node_desktop_ipc
node_desktop_ipc -->|"stores"| node_persist_layer
node_server_api -->|"delegates to"| node_db_adapters
node_db_adapters -->|"connects through"| node_driver_layer
node_server_api -->|"routes ai to"| node_agent_pipeline
node_agent_module -->|"calls"| node_server_api
node_raw_query_module -->|"executes via"| node_server_api
node_quick_query_module -->|"reads/writes via"| node_server_api
node_management_module -->|"admin via"| node_server_api
node_erd_module -->|"loads metadata via"| node_server_api
node_electron_main -->|"boots"| node_nuxt_shell
node_docs_tests -.->|"covers"| node_route_pages

click node_electron_main "https://github.com/cin12211/orca-q/blob/main/electron/src/main/index.ts"
click node_electron_preload "https://github.com/cin12211/orca-q/blob/main/electron/src/preload/index.ts"
click node_nuxt_shell "https://github.com/cin12211/orca-q/blob/main/app.vue"
click node_route_pages "https://github.com/cin12211/orca-q/blob/main/pages/[workspaceId]/[connectionId]/index.vue"
click node_app_shell "https://github.com/cin12211/orca-q/blob/main/components/modules/app-shell/index.ts"
click node_workspace_module "https://github.com/cin12211/orca-q/blob/main/components/modules/workspace/containers/Workspaces.vue"
click node_connection_module "https://github.com/cin12211/orca-q/blob/main/components/modules/connection/containers/ManagementConnection.vue"
click node_quick_query_module "https://github.com/cin12211/orca-q/blob/main/components/modules/quick-query/QuickQuery.vue"
click node_raw_query_module "https://github.com/cin12211/orca-q/blob/main/components/modules/raw-query/RawQuery.vue"
click node_management_module "https://github.com/cin12211/orca-q/blob/main/components/modules/management/index.ts"
click node_erd_module "https://github.com/cin12211/orca-q/blob/main/components/modules/erd-diagram/ErdDiagram.vue"
click node_agent_module "https://github.com/cin12211/orca-q/blob/main/components/modules/agent/AgentWorkspace.vue"
click node_settings_module "https://github.com/cin12211/orca-q/blob/main/components/modules/settings/containers/SettingsContainer.vue"
click node_ui_base "https://github.com/cin12211/orca-q/blob/main/components/ui/button/Button.vue"
click node_base_widgets "https://github.com/cin12211/orca-q/blob/main/components/base/code-editor/BaseCodeEditor.vue"
click node_client_state "https://github.com/cin12211/orca-q/blob/main/core/stores/useWorkspacesStore.ts"
click node_persist_layer "https://github.com/cin12211/orca-q/blob/main/core/persist/workspaceIDBApi.ts"
click node_server_api "https://github.com/cin12211/orca-q/blob/main/server/api/query/execute.post.ts"
click node_db_adapters "https://github.com/cin12211/orca-q/blob/main/server/infrastructure/database/adapters/index.ts"
click node_driver_layer "https://github.com/cin12211/orca-q/blob/main/server/infrastructure/driver/factory.ts"
click node_agent_pipeline "https://github.com/cin12211/orca-q/blob/main/server/infrastructure/agent/core/provider.ts"
click node_desktop_ipc "https://github.com/cin12211/orca-q/blob/main/electron/src/main/ipc/index.ts"
click node_docs_tests "https://github.com/cin12211/orca-q/blob/main/docs/ARCHITECTURE.md"

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_nuxt_shell toneBlue
class node_route_pages,node_app_shell,node_workspace_module,node_connection_module,node_quick_query_module,node_raw_query_module,node_management_module,node_erd_module,node_agent_module,node_settings_module,node_ui_base,node_base_widgets,node_client_state toneAmber
class node_server_api,node_db_adapters,node_driver_layer,node_agent_pipeline toneMint
class node_electron_main,node_electron_preload,node_persist_layer,node_desktop_ipc toneRose
class node_docs_tests toneIndigo
```

## Components

### Runtime shells

Electron and Nuxt runtime boundaries

- [Nuxt shell](https://github.com/cin12211/orca-q/blob/main/app.vue): renderer app · App root, layouts, middleware, and route hosting · `app.vue`

### Renderer app

UI routes, feature modules, shared components, and client orchestration

- [Route pages](https://github.com/cin12211/orca-q/blob/main/pages/[workspaceId]/[connectionId]/index.vue): screen routing · Workspace and connection route hierarchy for the main UI surfaces · `pages/[workspaceId]/[connectionId]/index.vue`
- [App shell](https://github.com/cin12211/orca-q/blob/main/components/modules/app-shell/index.ts): workspace chrome · Activity bar, sidebars, tab views, and status bar scaffolding · `components/modules/app-shell/index.ts`
- [Workspace](https://github.com/cin12211/orca-q/blob/main/components/modules/workspace/containers/Workspaces.vue): workspace setup · Workspace creation, listing, tour, and entry management · `components/modules/workspace/containers/Workspaces.vue`
- [Connection](https://github.com/cin12211/orca-q/blob/main/components/modules/connection/containers/ManagementConnection.vue): db access setup · Connection creation, SSL/SSH config, status, and persistence-facing form logic · `components/modules/connection/containers/ManagementConnection.vue`
- [Quick query](https://github.com/cin12211/orca-q/blob/main/components/modules/quick-query/QuickQuery.vue): structured editing · Table and view browsing, CRUD-like data editing, filtering, and history · `components/modules/quick-query/QuickQuery.vue`
- [Raw query](https://github.com/cin12211/orca-q/blob/main/components/modules/raw-query/RawQuery.vue): sql console · SQL editor, streaming execution, explain plans, variables, and results · `components/modules/raw-query/RawQuery.vue`
- [Management](https://github.com/cin12211/orca-q/blob/main/components/modules/management/index.ts): admin tools · Explorer, schemas, export, roles, and related database administration views · `components/modules/management/index.ts`
- [ERD diagram](https://github.com/cin12211/orca-q/blob/main/components/modules/erd-diagram/ErdDiagram.vue): schema graph · Entity-relationship visualization and table graph controls · `components/modules/erd-diagram/ErdDiagram.vue`
- [Agent UI](https://github.com/cin12211/orca-q/blob/main/components/modules/agent/AgentWorkspace.vue): ai assistant · Chat workspace, tool messages, approvals, reasoning, and export previews · `components/modules/agent/AgentWorkspace.vue`
- [Settings](https://github.com/cin12211/orca-q/blob/main/components/modules/settings/containers/SettingsContainer.vue): preferences · Appearance, editor, quick query, agent, and table configuration screens · `components/modules/settings/containers/SettingsContainer.vue`
- [UI base](https://github.com/cin12211/orca-q/blob/main/components/ui/button/Button.vue): design system · Reusable Vue primitives and shared visual components · `components/ui/button/Button.vue`
- [Base widgets](https://github.com/cin12211/orca-q/blob/main/components/base/code-editor/BaseCodeEditor.vue): feature primitives · SQL editor, dynamic table, tree browser, and context menu building blocks · `components/base/code-editor/BaseCodeEditor.vue`
- [Client state](https://github.com/cin12211/orca-q/blob/main/core/stores/useWorkspacesStore.ts): stores and composables · 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](https://github.com/cin12211/orca-q/blob/main/server/api/query/execute.post.ts): nuxt api · Endpoint surface for query, tables, views, metadata, roles, export/import, instance insights, and AI · `server/api/query/execute.post.ts`
- [DB adapters](https://github.com/cin12211/orca-q/blob/main/server/infrastructure/database/adapters/index.ts): domain adapters · Capability-specific adapters and factories for query, tables, views, metadata, roles, metrics, and insights · `server/infrastructure/database/adapters/index.ts`
- [Driver layer](https://github.com/cin12211/orca-q/blob/main/server/infrastructure/driver/factory.ts): connection drivers · Low-level database connection abstraction and driver selection, including Postgres and MySQL scaffolding · `server/infrastructure/driver/factory.ts`
- [Agent pipeline](https://github.com/cin12211/orca-q/blob/main/server/infrastructure/agent/core/provider.ts): ai orchestration · 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](https://github.com/cin12211/orca-q/blob/main/electron/src/main/index.ts): desktop lifecycle · Native app lifecycle, menus, window bootstrap, and IPC coordination · `electron/src/main/index.ts`
- [Preload bridge](https://github.com/cin12211/orca-q/blob/main/electron/src/preload/index.ts): secure bridge · Controlled APIs exposed to the renderer · `electron/src/preload/index.ts`
- [Local persist](https://github.com/cin12211/orca-q/blob/main/core/persist/workspaceIDBApi.ts): offline state · IndexedDB-backed workspace, connection, tab view, query log, and workspace state storage · `core/persist/workspaceIDBApi.ts`
- [Desktop IPC](https://github.com/cin12211/orca-q/blob/main/electron/src/main/ipc/index.ts): main-process services · 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](https://github.com/cin12211/orca-q/blob/main/docs/ARCHITECTURE.md): support system · Architecture docs, feature docs, tests, Playwright, Vitest, and spec-driven development assets · `docs/ARCHITECTURE.md`

## Connections

- 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
