Project Layout & Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
KamehaDB is organized as a local-first monorepo that separates the user interface, backend logic, and shared contracts into distinct packages. The project utilizes a pnpm workspace to manage dependencies across its desktop application, sidecar server, and shared libraries, while maintaining a separate environment for its marketing and documentation site.
The architecture is designed to support a "local-first" philosophy, where all metadata, credentials, and query histories are stored on the user's machine. This is achieved through a multi-layered structure involving a Tauri-based desktop frontend and a Node.js sidecar that serves as the database adapter layer.
Sources: AGENTS.md:7-13, README.md:10-18, PLAN.md:10-23
Monorepo Architecture
The repository is structured around a primary pnpm workspace containing the core application logic and a separate npm-managed directory for the landing site.
Directory Organization
| Path | Description | Management |
|---|---|---|
apps/desktop/ | Tauri v2 + React 19 desktop application. | pnpm workspace |
apps/sidecar/ | Hono HTTP server, DB adapters, and metadata SQLite store. | pnpm workspace |
packages/shared/ | Zod schemas, app state types, and adapter contracts. | pnpm workspace |
packages/ui/ | Shared UI primitives and utility components. | pnpm workspace |
landing/ | Next.js marketing and documentation site. | Separate npm lockfile |
Sources: AGENTS.md:17-26, README.md:58-66, PLAN.md:100-112
Workspace Boundaries
The pnpm workspace includes only the apps/* and packages/* directories. The landing/ directory is managed independently with npm and is not affected by root scripts unless they explicitly target the directory.
Sources: AGENTS.md:30-34, package.json:7-21
System Component Relationships
The system follows a tiered architecture where the desktop frontend communicates with a local sidecar server, which in turn interacts with various database engines.
The diagram above illustrates the data flow from the React UI through the sidecar server to the target databases, highlighting the role of packages/shared as the source of truth for types and schemas.
Sources: AGENTS.md:67-101, PLAN.md:126-140
Package Responsibilities
Desktop Application (apps/desktop)
The frontend is built with Tauri v2 and React 19. It manages the workspace layout, connection navigation, SQL editing (via Monaco), and visual schema representations using ReactFlow. It maintains client-side state using TanStack Store and handles asynchronous data fetching from the sidecar via TanStack Query.
Sources: AGENTS.md:104-114, PLAN.md:126-140, apps/desktop/package.json:11-30
Sidecar Server (apps/sidecar)
The sidecar is a Hono-based HTTP server running on 127.0.0.1 (default port 3170). It is responsible for:
- Executing database queries and managing connection pools.
- Storing metadata (connection profiles, AI settings, chat history) in a local
better-sqlite3database. - Enforcing SQL safety guards and redaction of secrets.
- Providing an AI abstraction layer for various providers (OpenAI, Ollama, etc.).
Sources: AGENTS.md:73-90, PLAN.md:142-152
Shared Contracts (packages/shared)
This package serves as the "source of truth" for the entire monorepo. It contains:
- Zod Schemas: Validation for connection profiles and API DTOs.
- Contracts: Interfaces for
SqlAdapterandRedisAdapter. - State Types: Definitions for app store states and workspace tabs.
Sources: AGENTS.md:67-71, PLAN.md:106-108
Project Scripts & Commands
The root package.json provides scripts to manage the monorepo concurrently.
{
"scripts": {
"dev": "concurrently \"pnpm --filter @kamehadb/sidecar dev\" \"pnpm --filter @kamehadb/desktop dev\"",
"build": "pnpm --filter @kamehadb/sidecar build && pnpm --filter @kamehadb/desktop build",
"typecheck": "pnpm -r typecheck",
"test": "pnpm -r test"
}
}
Sources: package.json:7-21, AGENTS.md:38-64
Implementation Details
The project utilizes a specific stack to maintain consistency across the monorepo:
- Validation: Zod is used for runtime validation and type inference to prevent drift between the sidecar and desktop.
- State Management: TanStack Store is preferred over other libraries like Zustand for local client state.
- Database Connectivity: The sidecar uses standard drivers such as
pg(PostgreSQL),mysql2(MySQL),better-sqlite3(SQLite), andioredis(Redis).
Sources: PLAN.md:31-61, PLAN.md:156-174, AGENTS.md:139-150
Conclusion
The KamehaDB monorepo structure ensures a clean separation between the user interface and the privileged database access layer. By utilizing packages/shared, the project maintains strict type safety across the sidecar and desktop applications, while the "local-first" sidecar architecture guarantees data privacy and security.
Sources: AGENTS.md:7-13, PLAN.md:10-23