Kumo Development Assistant

Expert assistant for developing Kumo - a comprehensive cross-platform MySQL/MongoDB database management tool built with TypeScript, React, and Electron.

When to Use This Skill

Use this skill when:

Adding new features to Kumo
Understanding the feature-based architecture
Working with database connections (MySQL/MongoDB)
Creating or modifying UI components
Writing API endpoints
Adding tests (Vitest unit tests or Playwright E2E tests)
Working with the Electron desktop app
Understanding project conventions and patterns

Quick Start Guide

Project Overview

Kumo is a cross-platform database management application similar to Navicat, featuring:

Database Support: MySQL and MongoDB with multi-connection management
Query Tools: Monaco editor with SQL syntax highlighting, visual query builder (React Flow)
Data Management: Advanced data viewer with inline editing, import/export (CSV, JSON, SQL, Excel)
Development Tools: API tester, terminal, Playwright integration, Git browser
AI Features: Anthropic Claude integration for query assistance

Tech Stack:

Frontend: React 18, TypeScript, TanStack Query, Tailwind CSS, Monaco Editor
Backend: Node.js, Express, mysql2, mongodb driver, socket.io
Desktop: Electron with secure IPC
Testing: Vitest (unit), Playwright (E2E)
State: Zustand (client), TanStack Query (server)

Architecture Patterns

Three-Tier Architecture:

React Frontend → Node.js API Server → MySQL/MongoDB Database

Key Principles:

Feature-based folder structure in src/features/
Server-side connection pooling (never direct database access from browser)
RESTful API with WebSocket for streaming operations
Separation of server state (TanStack Query) and client state (Zustand)
TypeScript path aliases: @/* for src/*, @server/* for server/*

For detailed architecture information, see architecture.md.

Common Development Tasks

1. Adding a New Feature

Location: src/features/<feature-name>/

Pattern: Each feature is self-contained with:

src/features/myFeature/
├── MyFeatureComponent.tsx    # Main component
├── components/               # Sub-components
│   ├── SubComponent1.tsx
│   └── SubComponent2.tsx
└── utils/                    # Feature-specific utilities
    └── helpers.ts

Steps:

Create feature folder in src/features/
Build React components using functional components + hooks
Use Zustand for local feature state if needed
Use TanStack Query for server data fetching
Follow Tailwind CSS for styling
Add tests in src/test/ or tests/

See features.md for detailed feature development guide.

2. Creating API Endpoints

Location: server/routes/

Pattern:

// server/routes/myRoute.ts
import { Router } from 'express';

const router = Router();

router.get('/api/my-endpoint', async (req, res) => {
  try {
    // Business logic here
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

export default router;

Register in server/index.ts:

import myRoute from './routes/myRoute';
app.use(myRoute);

3. Database Operations

MySQL Example:

import { query } from '@server/utils/database';

const results = await query(connectionId, 'SELECT * FROM users WHERE id = ?', [userId]);

MongoDB Example:

import { getMongoClient } from '@server/services/mongodb';

const client = await getMongoClient(connectionId);
const db = client.db(databaseName);
const collection = db.collection(collectionName);
const docs = await collection.find({ status: 'active' }).toArray();

Important: Always use parameterized queries to prevent SQL injection.

4. Adding Tests

Unit Tests (Vitest):

npm run test:unit              # Run all unit tests
npm run test:unit:ui           # Run with UI

Location: src/test/components/

E2E Tests (Playwright):

npm run test                   # Run all E2E tests
npm run test:ui                # Run with Playwright UI
npm run test:headed            # Run in headed mode

Location: tests/

See testing.md for comprehensive testing guide.

Project Structure

Kumo/
├── src/                           # Frontend React application
│   ├── features/                  # Feature modules (20+ features)
│   │   ├── apiTester/            # REST API testing
│   │   ├── connections/          # Database connection management
│   │   ├── dataViewer/           # Data grid with inline editing
│   │   ├── mongodb/              # MongoDB features
│   │   ├── query/                # SQL editor and execution
│   │   ├── queryBuilder/         # Visual query builder
│   │   ├── schema/               # Schema exploration
│   │   └── ...                   # 13+ more features
│   ├── components/               # Shared UI components
│   ├── hooks/                    # Custom React hooks
│   ├── services/                 # Frontend API clients
│   ├── store/                    # Zustand state management
│   ├── types/                    # TypeScript type definitions
│   └── utils/                    # Utility functions
├── server/                       # Node.js Express API
│   ├── routes/                   # API route handlers
│   ├── services/                 # Business logic
│   ├── types/                    # Server types
│   └── utils/                    # Server utilities
├── electron/                     # Electron main process
│   ├── main.cjs                  # Entry point
│   └── preload.js                # Preload script
├── tests/                        # E2E tests (Playwright)
├── openspec/                     # Spec-driven development
│   ├── project.md                # Project conventions
│   ├── specs/                    # Feature specifications
│   └── changes/                  # Change proposals
└── .claude/                      # Claude Code configuration
    ├── commands/                 # Slash commands
    └── skills/                   # Agent skills

Code Conventions

TypeScript Style

2-space indentation
Single quotes for strings
Trailing commas in multi-line objects/arrays
PascalCase for components, camelCase for functions/variables
kebab-case for file names

React Patterns

Functional components with hooks (no class components)
Props destructuring in component signatures
Custom hooks for reusable logic (prefix with use)
Memoization with useMemo/useCallback for expensive operations

State Management

Server State: Use TanStack Query (useQuery, useMutation)
Client State: Use Zustand stores for UI state
Form State: Use controlled components with local useState

API Patterns

RESTful endpoints with proper HTTP methods (GET, POST, PUT, DELETE)
Error handling with try-catch and appropriate status codes
Parameterized queries to prevent SQL injection
Connection pooling for database connections

Development Workflow

Running the Application

# Terminal 1: Frontend (Vite dev server)
npm run dev                    # http://localhost:5174

# Terminal 2: Backend API
npm run dev:server             # http://localhost:3001

# Terminal 3 (optional): Electron app
npm run dev:electron

Building for Production

# Build frontend and server
npm run build

# Build Electron app for specific platform
npm run build:electron:win     # Windows
npm run build:electron:mac     # macOS
npm run build:electron:linux   # Linux

Code Quality

npm run format                 # Format code with Prettier
npm run type-check             # TypeScript type checking
npm run lint                   # ESLint code linting
npm run clean                  # Clean build artifacts

Key Features Overview

Database Connections (src/features/connections/)
- Multi-database connection management
- Secure credential storage
- SSH tunnel support
Query Editor (src/features/query/)
- Monaco editor with SQL syntax highlighting
- Query execution and results display
- Query history and saved queries
- AI-powered query suggestions
Visual Query Builder (src/features/queryBuilder/)
- Drag-and-drop query construction
- React Flow for visual representation
- Smart join suggestions based on foreign keys
Data Viewer (src/features/dataViewer/)
- TanStack Table for virtualized data grid
- Inline editing with validation
- Pagination, filtering, sorting
Schema Management (src/features/schema/)
- Visual schema browser
- Relationship diagrams
- Index management
API Tester (src/features/apiTester/)
- REST API testing
- cURL parsing and generation
- Request/response management
Git Integration (src/features/git/)
- Repository browser
- Pull request viewer
- Code diff viewer

Security Considerations

Never expose credentials: Store in OS keychain (desktop) or encrypted (web)
Parameterized queries: Always use placeholders for user input
Connection limits: Max 10 connections per database
Input validation: Validate all user input on both client and server
Secure IPC: Electron preload script for secure communication

Performance Guidelines

Large result sets: Warn at 10k rows, require confirmation for 100k+
Virtual scrolling: Use TanStack Virtual for large lists
Code splitting: Lazy load features with React.lazy()
Streaming: Use streaming for large file imports/exports
Connection pooling: Reuse database connections efficiently

OpenSpec Integration

Kumo uses OpenSpec for spec-driven development. See openspec/AGENTS.md for:

Creating change proposals
Writing spec deltas
Implementing changes
Archiving completed work

Getting Help

Documentation:

architecture.md - Detailed architecture patterns
features.md - Feature development guide
testing.md - Testing strategies and examples
openspec/project.md - Project conventions
README.md - Setup and usage guide

Commands:

openspec list                  # View active changes
openspec list --specs          # View feature specifications
npm run test:report            # View test reports

Tips for AI Assistants

Check existing features first: Similar functionality may already exist
Follow feature structure: Keep features self-contained in src/features/
Use path aliases: Import with @/* instead of relative paths
Write tests: Add tests when creating new features
Update specs: Use OpenSpec for significant changes
Security first: Validate input, use parameterized queries
Performance aware: Consider virtual scrolling for large data sets
Type safety: Leverage TypeScript for better DX

Next Steps

Read architecture.md for in-depth technical patterns
Review features.md before adding new features
Check testing.md for testing best practices
Explore existing features in src/features/ for examples
Review openspec/project.md for project conventions