TanStack Store & Workspace State
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The KamehaDB desktop application utilizes TanStack Store as its primary engine for managing local UI and client-side state. This system is responsible for tracking the active workspace configuration, including opened tabs, selected connections, and UI preferences like sidebar visibility and density. By centralizing these concerns, the application ensures a consistent state across various components such as the sidebar, SQL editor, and AI chat panel.
The store acts as the "source of truth" for the current user session, distinguishing between ephemeral UI state (managed here) and remote/cached data (managed via TanStack Query). This architectural split allows for a highly responsive, local-first user experience where workspace layouts persist and react instantaneously to user interactions.
Sources: PLAN.md:144-150, AGENTS.md:104-106
State Architecture and Schema
The workspace state is defined by the AppStoreState interface, which encapsulates the entire navigational and visual context of the application. The state is strongly typed using Zod schemas and TypeScript interfaces defined in the shared package to ensure consistency between the frontend and the underlying data contracts.
Core State Data Model
The state tracks the hierarchy of database objects currently in focus and the structure of the tabbed interface.
| Field | Type | Description |
|---|---|---|
activeConnectionId | string | null | The ID of the currently selected database connection profile. |
activeDatabaseId | string | null | The name of the active database within the connection. |
openedTabs | WorkspaceTab[] | An array of active tabs representing editors, tables, or stats views. |
activeTabId | string | null | The ID of the tab currently displayed in the main workspace. |
sidebarCollapsed | boolean | Controls the visibility of the primary navigation sidebar. |
density | 'compact' | 'comfortable' | UI spacing preference for tables and lists. |
view | 'workspace' | 'api-settings' | The top-level view current being rendered. |
Sources: packages/shared/src/index.ts:384-399, PLAN.md:152-162
Workspace Tab Types
The WorkspaceTab is a discriminated union that allows the store to manage different types of interactive views within the same tabbed interface.
Sources: packages/shared/src/index.ts:352-382
Data Flow and Transitions
The application state flows from the centralized TanStack Store (appStore) to individual React components. Components subscribe to specific slices of state or use actions to trigger transitions.
Workspace State Transition Flow
This diagram illustrates how a user action (selecting a table) triggers a state update that propagates through the UI.
AI Panel Integration
The AI Chat Panel interacts with the store to determine the context for its queries. It retrieves the activeConnectionId and, in the case of MongoDB, the activeMongoDatabase to provide schema-aware assistance.
Implementation Details
The store is implemented in apps/desktop/src/store/index.ts. It provides helper functions to manipulate state without direct mutation, following functional programming principles.
Key Store Operations
openQueryTabWithSql: Creates a new tab of typequeryand populates it with SQL code, used extensively by the AI Assistant to "run" or "insert" generated queries.navigateTo: Switches the top-levelviewstate (e.g., from the main workspace to 'api-settings').appStore.state: The reactive state object used by components via hooks (e.g.,useStore).
Sources: apps/desktop/src/components/ai-chat-panel.tsx:28-29, AGENTS.md:104-105
Connection Status Tracking
The store also maintains a connectionStatus map, which tracks whether specific profiles are currently connected or disconnected based on the latest health checks performed by the sidecar.
Sources: packages/shared/src/index.ts:398, PLAN.md:131-133
Summary
The TanStack Store and Workspace State system provides the structural foundation for KamehaDB's multi-database interface. By utilizing a strictly typed, centralized state model, the application successfully manages complex tabbed navigation, UI preferences, and cross-component communication (such as AI-to-SQL-Editor workflows). This architecture ensures that the user's workspace context is always preserved and consistently represented across the Tauri-based desktop environment.