Schema Graph Visualization
Relevant source files
The following files were used as context for generating this wiki page:
The Schema Graph Visualization is a core feature of KamehaDB that provides an interactive, auto-generated Entity-Relationship (ER) diagram of database tables and their foreign key relationships. It allows developers to visually explore complex database structures, identify connections between data entities, and navigate directly to specific table views.
This system is built using ReactFlow for the interactive canvas and Dagre for automated graph layout. It leverages schema metadata retrieved from the sidecar to render a live representation of the connected database's architecture. Sources: README.md:14, apps/desktop/src/components/schema-graph.tsx:8-20
Architecture and Data Flow
The visualization follows a decoupled architecture where the desktop frontend requests structured metadata from a local sidecar API, processes that metadata into a graph structure, and renders it using a specialized UI component.
Metadata Retrieval
The graph relies on the "completions" endpoint which provides a comprehensive list of tables, columns, and foreign key definitions. This data is fetched using TanStack Query to ensure efficient caching and state management. Sources: apps/desktop/src/components/schema-graph.tsx:32-41
The diagram shows the synchronous flow of data from the target database through the sidecar to the desktop UI. Sources: apps/desktop/src/components/schema-graph.tsx:32-41, AGENTS.md:117-122
Graph Construction Logic
The buildGraph function transforms raw database metadata into ReactFlow-compatible nodes and edges. It utilizes the dagre library to calculate the optimal positioning (X and Y coordinates) for each table node to minimize edge crossings. Sources: apps/desktop/src/components/schema-graph.tsx:112-115
- Nodes: Each table is represented as a "table" type node containing its schema name and column definitions.
- Edges: Relationship lines are drawn between nodes where foreign key constraints exist. Edges are styled as
smoothsteppaths with arrows indicating the direction of the relationship. Sources: apps/desktop/src/components/schema-graph.tsx:136-146
UI Components and Interaction
The visualization is composed of several specialized React components that handle rendering and user interaction.
Custom Node: TableNode
The TableNode is a custom ReactFlow component that renders a database table as a structured card. It displays:
- The table name (qualified with schema if applicable).
- A list of columns with their data types.
- Visual indicators for Primary Keys (PK) and Foreign Keys (FK).
- Standard handles for incoming (target) and outgoing (source) relationship edges. Sources: apps/desktop/src/components/schema-graph.tsx:43-78
Navigation and Tools
The graph provides several utility features for better accessibility:
- MiniMap: A small overview window in the corner for navigating large schemas.
- Auto Arrange: A button to reset the layout using the Dagre algorithm.
- Direct Navigation: Clicking a table node triggers the
openTabfunction, opening the specific table's data view in the workspace. Sources: apps/desktop/src/components/schema-graph.tsx:173-181, apps/desktop/src/components/schema-graph.tsx:210-222
Data Structures
The following table summarizes the key data structures used to build the Schema Graph:
| Structure | Description | Key Fields |
|---|---|---|
CompletionsData | The root response from the API containing the schema. | tables: Table[] |
ColumnInfo | Detailed metadata for a single database column. | name, type, primaryKey, foreignKey |
Node | ReactFlow node object with position and data. | id, type: 'table', position, data |
Edge | ReactFlow edge object representing a relationship. | id, source, target, markerEnd |
Sources: apps/desktop/src/components/schema-graph.tsx:22-30, packages/shared/src/index.ts:110-120
Foreign Key Metadata
Foreign keys are the primary drivers of the graph's edges. The sidecar ensures that foreign key metadata includes both the target table and the target column. Sources: packages/shared/src/index.ts:116-119
// Example of the Foreign Key structure used for edge generation
// Source: packages/shared/src/index.ts:116-119
foreignKey?: {
table: string;
column: string;
};
Technical Implementation Details
Layout Configuration
The Dagre engine is configured to use a Left-to-Right (LR) layout direction. This is chosen to accommodate the horizontal nature of table-column lists. Sources: apps/desktop/src/components/schema-graph.tsx:118-120
The flow shows the internal logic of the buildGraph function which prepares the data for ReactFlow. Sources: apps/desktop/src/components/schema-graph.tsx:112-162
Dependency Overview
The system relies on a specific set of libraries to manage the visualization:
- @xyflow/react (ReactFlow): Canvas management and node/edge rendering.
- dagre: Directed graph layout algorithm.
- @tanstack/react-query: Metadata fetching and state synchronization.
- lucide-react: Icons used within table headers and control buttons. Sources: apps/desktop/src/components/schema-graph.tsx:2-20, PLAN.md:15-18
The Schema Graph Visualization provides an essential layer of abstraction over raw database schemas, enabling users to perform rapid structural analysis and intuitive navigation within KamehaDB. Its integration with the broader workspace ensures that visual exploration leads directly to data interaction. Sources: PLAN.md:144-147, AGENTS.md:104-106