Kumo Assistant

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:

1. Create feature folder in src/features/
2. Build React components using functional components + hooks
3. Use Zustand for local feature state if needed
4. Use TanStack Query for server data fetching
5. Follow Tailwind CSS for styling
6. 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

1. Database Connections (src/features/connections/)

   • Multi-database connection management
   • Secure credential storage
   • SSH tunnel support

2. 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

3. Visual Query Builder (src/features/queryBuilder/)

   • Drag-and-drop query construction
   • React Flow for visual representation
   • Smart join suggestions based on foreign keys

4. Data Viewer (src/features/dataViewer/)

   • TanStack Table for virtualized data grid
   • Inline editing with validation
   • Pagination, filtering, sorting

5. Schema Management (src/features/schema/)

   • Visual schema browser
   • Relationship diagrams
   • Index management

6. API Tester (src/features/apiTester/)

   • REST API testing
   • cURL parsing and generation
   • Request/response management

7. 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

1. Check existing features first: Similar functionality may already exist
2. Follow feature structure: Keep features self-contained in src/features/
3. Use path aliases: Import with @/* instead of relative paths
4. Write tests: Add tests when creating new features
5. Update specs: Use OpenSpec for significant changes
6. Security first: Validate input, use parameterized queries
7. Performance aware: Consider virtual scrolling for large data sets
8. 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