Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
KamehaDB is a local-first, cross-platform database management tool designed to provide a secure environment for browsing schemas and executing queries. The architecture is centered around a desktop application built with Tauri and React, supported by a local Node.js sidecar that handles database connectivity and metadata persistence.
The system emphasizes security by keeping all credentials, connection profiles, and query histories local to the user's machine. It supports multiple database engines including PostgreSQL, MySQL, SQLite, MongoDB, and Redis, while integrating AI capabilities for natural language query generation and schema-aware assistance.
Sources: PLAN.md:5-15, README.md:12-25, AGENTS.md:10-20
System Components
The project is organized as a monorepo with distinct responsibilities divided among different packages and applications.
| Component | Responsibility | Tech Stack |
|---|---|---|
Desktop App (apps/desktop) | User interface, workspace management, and visualization. | Tauri v2, React 19, Vite, Tailwind CSS v4, Monaco Editor. |
Sidecar (apps/sidecar) | Local HTTP server, database adapters, and metadata storage. | Node.js, Hono, better-sqlite3. |
Shared (packages/shared) | Source of truth for Zod schemas, TypeScript types, and adapter contracts. | TypeScript, Zod. |
UI (packages/ui) | Shared UI primitives and utilities. | React, Lucide. |
Sources: PLAN.md:27-60, AGENTS.md:25-35, README.md:106-118
Core Architecture Flow
The following diagram illustrates the runtime data flow between the user interface and the database engines through the sidecar.
The diagram shows the multi-layered approach where the UI communicates with a local Sidecar, which in turn manages database connections and local metadata.
Sources: PLAN.md:105-115, AGENTS.md:75-85
Data Modeling and Shared Contracts
The packages/shared package serves as the foundational contract for the entire system. It defines the schemas for connection profiles, query results, and the interface definitions for database adapters.
Database Adapters
Each supported database engine implements a specific adapter contract. This normalization allows the frontend to interact with diverse engines (SQL, NoSQL, Key-Value) through a consistent API.
The class diagram represents the abstraction layer used to handle different database protocols.
Sources: packages/shared/src/index.ts:133-280, PLAN.md:162-185
AI Integration and Schema Context
KamehaDB features a schema-aware AI assistant. The system injects database-specific metadata (table structures, columns, types) into the AI prompts to enable accurate query generation.
AI Flow and Security
AI interactions are handled via the sidecar, which manages provider configurations (OpenAI, Ollama, 9Router). A critical security feature is the SQL Safety Guard, which blocks destructive commands in read-only mode.
This sequence diagram shows how schema context is retrieved and combined with user intent before reaching the AI provider.
Sources: apps/desktop/src/components/ai-chat-panel.tsx:180-250, packages/shared/src/index.ts:503-535, AGENTS.md:85-90
Workspace and State Management
The application utilizes a sophisticated state management strategy to handle the tabbed interface and connection states.
- TanStack Query: Manages "server" state fetched from the sidecar (connection lists, table data, schema trees).
- TanStack Store: Manages "local" UI state (active tab, sidebar collapse state, current view).
- Persistent Metadata: Connection profiles, AI settings, and chat history are stored in a local
better-sqlite3database managed by the sidecar.
Sources: PLAN.md:130-155, AGENTS.md:95-105
Connection Lifecycle
| Step | Action | Detail |
|---|---|---|
| 1 | Profile Creation | User enters credentials; stored in metadata SQLite. |
| 2 | Secret Storage | Password/Tokens stored in OS Keychain via Tauri bridge. |
| 3 | Connection Pool | Sidecar initializes driver instance (pg, mysql2, etc.). |
| 4 | Metadata Sync | Sidecar crawls schemas/tables for sidebar and AI context. |
Sources: PLAN.md:210-225, AGENTS.md:80-85
Security Implementation
Security is a primary architectural pillar. The system implements several layers of protection:
- Loopback Binding: The Node.js sidecar binds only to
127.0.0.1and uses a random available port. - SQL Safety Guard: A dedicated utility in
@kamehadb/shared(usingisQuerySafe) regex-checks queries for destructive keywords (DROP,TRUNCATE,ALTER, etc.) when in read-only mode. - Local Metadata: No connection data or query results are sent to cloud services, except for the content sent to the user-configured AI provider.
Sources: packages/shared/src/index.ts:503-535, PLAN.md:325-345, AGENTS.md:75-80
Conclusion
KamehaDB's architecture leverages the strengths of Tauri for native desktop capabilities and Node.js for robust database connectivity. By abstracting database protocols into normalized adapters and maintaining a local-first metadata store, the system provides a performant and secure environment for database administration with modern AI enhancements.