Main Workspace Layout
Relevant source files
The following files were used as context for generating this wiki page:
The Main Workspace Layout in KamehaDB is a local-first, multi-tabbed environment designed for cross-platform database administration. It serves as the primary interface for managing connection profiles, browsing schemas, executing queries, and interacting with schema-aware AI. The layout is structured to provide a dense, developer-centric experience that separates navigation, main data operations, and auxiliary AI assistance into distinct regions.
Sources: README.md:1-15, PLAN.md:231-240, AGENTS.md:103-107
Architectural Overview
The workspace follows a "Tauri + React + Node sidecar" architecture. The frontend workspace is managed by React, utilizing TanStack Store for local UI state and TanStack Query for communicating with the local Node.js sidecar. The sidecar handles all direct database interactions, applying safety guards and normalizing results before they are rendered in the workspace tabs.
Sources: PLAN.md:131-158, AGENTS.md:80-87
Component Distribution
| Region | Component | Primary Responsibility |
|---|---|---|
| Left Sidebar | Sidebar | Connection management, schema tree navigation, and quick actions (stats/graph). |
| Center Workspace | Tabs | Hosting specific views like SQL Editor, Table View, Mongo View, or Redis Explorer. |
| Right Panel | AIChatPanel | Providing a resizable, schema-aware AI interface for query generation and debugging. |
| Bottom Panel | Status/Logs | Displaying query results, execution duration, and sidecar logs. |
Sources: PLAN.md:231-240, AGENTS.md:108-115, apps/desktop/src/components/ai-chat-panel.tsx:288-295
Data Flow within the Workspace
The following diagram illustrates how user actions in the workspace interact with the underlying sidecar and shared packages.
Core UI Components
Navigation Sidebar
The sidebar maintains the hierarchical tree of connection profiles. Each connection can be expanded to reveal databases, schemas, and tables. It also hosts quick actions for "Schema Graph" and "Database Stats".
Sources: AGENTS.md:108-110, PLAN.md:242-248
Central Workspace Tabs
The workspace uses a tabbed system to allow multiple concurrent operations. Each tab is typed and stores its own state (such as SQL drafts or pagination settings).
- SQL Editor: A Monaco-based editor providing syntax highlighting and autocomplete.
- Data Grids: Powered by TanStack Table, offering dense, paginated views for SQL tables or MongoDB collections.
- Engine-Specific Views: Dedicated components for MongoDB (
MongoView) and Redis (RedisExplorer).
Sources: PLAN.md:261-274, AGENTS.md:108-115, apps/desktop/src/components/mongo-view.tsx:1-25
AI Chat Panel
The AIChatPanel is a resizable side panel that provides conversational SQL generation. It is "schema-aware," meaning the backend injects the current database structure into the prompt context. It includes features like:
- Resizable width (280px to 600px).
- Contextual suggestions based on the database engine (SQL vs MongoDB vs Redis).
- Integration with the SQL editor to "Run" generated queries directly.
Sources: apps/desktop/src/components/ai-chat-panel.tsx:300-330, apps/desktop/src/components/ai-chat-panel.tsx:430-450
State and Workspace Configuration
The workspace state is synchronized via packages/shared, ensuring that both the frontend and sidecar agree on the structure of tabs and connection profiles.
Workspace Tab Types
Tabs are represented as a discriminated union to handle different data requirements for different database engines.
export type WorkspaceTab =
| { id: string; type: 'table' | 'query' | 'stats'; connectionId: string; sql?: string; }
| { id: string; type: 'mongo'; connectionId: string; database: string; collection: string; }
| { id: string; type: 'redis'; connectionId: string; command?: string; }
// ... other tab types
Sources: packages/shared/src/index.ts:375-408
Global App Store
The AppStoreState defines the overall layout environment, including preferences for density and theme.
| Property | Type | Description |
|---|---|---|
activeTabId | string | null | The ID of the currently focused tab in the center workspace. |
sidebarCollapsed | boolean | Toggle for the left navigation visibility. |
density | 'compact' | 'comfortable' | UI spacing preference for data-heavy views. |
theme | 'light' | 'dark' | 'system' | The visual appearance mode of the application. |
Sources: packages/shared/src/index.ts:413-426, PLAN.md:173-185
Workspace Sequence: Executing a Query
This sequence shows the interaction between workspace components when a user executes a query from the AI Chat Panel.
Summary
The Main Workspace Layout is the central hub of KamehaDB, balancing dense data presentation with resizable auxiliary tools. By utilizing a local sidecar and shared Zod schemas, the layout ensures that complex database operations—ranging from MongoDB aggregations to AI-driven SQL generation—remain performant and type-safe across different platforms.
Sources: README.md:120-135, PLAN.md:364-375