Chain Workspace Developer

A comprehensive development guide for building a lightweight, modular workspace application for creating and managing document processing chains with AI agents.

Architecture

The application follows these key patterns:

Tech Stack

Project Structure

```

COD_V01/

├── .claude/agents/ # Sub-agent definitions

├── .memri/ # Memory Bank knowledge files

├── src/ # React frontend source

│ ├── components/ # Reusable UI components

│ ├── pages/ # Route components

│ └── lib/ # Utilities and hooks

├── api/ # Node.js backend source

│ ├── routes/ # Fastify route handlers

│ ├── services/ # Business logic

│ └── db/ # Database utilities

├── schemas/ # Shared Zod schemas

├── tests/ # Test suites

│ ├── unit/ # Unit tests

│ ├── integration/ # Integration tests

│ └── e2e/ # End-to-end tests

├── migrations/ # Database schema migrations

└── docker/ # Container configurations

```

Development Instructions

Environment Setup

1. **Start the local development environment:**

```bash

docker-compose -f docker-compose.dev.yml up -d

```

2. **Install dependencies:**

```bash

npm install

```

3. **Run database migrations:**

```bash

npm run db:migrate

```

4. **Seed development data:**

```bash

npm run db:seed

```

5. **Start development servers:**

```bash

# Both frontend and backend

npm run dev

# Or separately:

npm run dev:ui # Frontend only (port 4000)

npm run dev:api # Backend only (port 4001)

```

Testing Workflow (TDD)

Follow test-driven development principles:

1. **Write failing tests first:**

```bash

npm run test:unit # Unit tests

npm run test:integration # Integration tests (requires DB)

npm run test:e2e # End-to-end tests

npm test # Run all tests

npm run test:watch # Watch mode

```

2. **Implement minimum code to pass tests**

3. **Refactor while keeping tests green**

4. **Generate coverage reports:**

```bash

npm run test:coverage

```

Database Operations

```bash

Create new migration

npm run db:migrate:create

Deploy migrations to database

npm run db:migrate:deploy

Reset database (development only - destroys data)

npm run db:reset

Access database GUI (Adminer)

Navigate to http://localhost:8081

```

Code Quality

Run these before committing:

```bash

npm run lint # Check code quality

npm run lint:fix # Auto-fix issues

npm run typecheck # TypeScript validation

npm run format # Format code with Prettier

```

Docker Operations

```bash

Build containers

docker-compose build

Start services in background

docker-compose up -d

View logs

docker-compose logs -f [service-name]

Stop services

docker-compose down

Clean reset (removes volumes)

docker-compose down -v

```

Sub-Agent Workflow

Use specialized sub-agents in this order:

1. **test-runner**: Creates failing tests first (TDD red phase)

2. **schema-keeper**: Defines/updates Zod data contracts

3. **ui-developer**: Implements React components

4. **backend-developer**: Implements Fastify API endpoints

5. **commit-bot**: Commits code, runs full test suite, updates Memory Bank

Commit Message Format

All commits must reference Task Master task numbers:

```bash

Feature commits

feat(task-3): implement core Zod schemas for API validation

feat(task-X): add [component/endpoint/feature name]

Bug fixes

fix(task-5): resolve canvas pan/zoom boundary calculations

Tests

test(task-4): add integration tests for events API endpoints

Refactoring

refactor(task-11): optimize event sourcing performance

Setup and maintenance

feat(setup): integrate Task Master AI for TDD workflow

docs(memory): update Memory Bank with task progress

ci(deps): update dependencies for security patches

```

Task Completion Template

```bash

feat(task-X): complete [task title]

Closes task-X

```

Memory Bank Files

The `.memri/` directory contains:

**Always update Memory Bank files when completing tasks or making architectural decisions.**

Environment Variables

Create `.env` file with:

```bash

Database connection

DATABASE_URL=postgresql://user:password@localhost:5432/chainworkspace

API Keys (development)

OPENAI_API_KEY=your_openai_key_here

JWT Secret

JWT_SECRET=your_jwt_secret_here

Environment

NODE_ENV=development

```

Service Ports

Key File Patterns

When searching or creating files:

Quick Start Checklist

1. ✅ Start database: `docker-compose -f docker-compose.dev.yml up -d`

2. ✅ Install deps: `npm install`

3. ✅ Run migrations: `npm run db:migrate`

4. ✅ Start servers: `npm run dev`

5. ✅ Verify frontend: http://localhost:4000

6. ✅ Verify backend: http://localhost:4001/health

Important Notes