kumo-assistant

# 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](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](features.md) for detailed feature development guide.

#### 2. Creating API Endpoints

**Location**: `server/routes/`

**Pattern**:
```typescript
// 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`:
```typescript
import myRoute from './routes/myRoute';
app.use(myRoute);
```

#### 3. Database Operations

**MySQL Example**:
```typescript
import { query } from '@server/utils/database';

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

**MongoDB Example**:
```typescript
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)**:
```bash
npm run test:unit              # Run all unit tests
npm run test:unit:ui           # Run with UI
```

Location: `src/test/components/`

**E2E Tests (Playwright)**:
```bash
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](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

```bash
# 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

```bash
# 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

```bash
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](architecture.md) - Detailed architecture patterns
- [features.md](features.md) - Feature development guide
- [testing.md](testing.md) - Testing strategies and examples
- `openspec/project.md` - Project conventions
- `README.md` - Setup and usage guide

**Commands**:
```bash
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](architecture.md) for in-depth technical patterns
- Review [features.md](features.md) before adding new features
- Check [testing.md](testing.md) for testing best practices
- Explore existing features in `src/features/` for examples
- Review `openspec/project.md` for project conventions