Local Development

Overview

Local development uses a hybrid approach:

Docker for infrastructure (PostgreSQL, Redis, ChromaDB)
npm + Turbo for application services (hot-reload development)

Prerequisites

Software	Version	Purpose
Docker Desktop	20.x+	Infrastructure containers
Node.js	18+ (LTS recommended)	Runtime
npm	9+	Package management

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

node --version    # Should be 18.x or 20.x
npm --version     # Should be 9.x or 10.x
docker --version  # Should be 20.x or higher

Infrastructure Setup (Docker)

Start Containers

# Start existing containers
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma

# Check status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

You should see three running containers:

Container	Port
brainstormer-postgres	5432
brainstormer-redis	6379
brainstormer-chroma	8000

If containers don’t exist yet, see the Docker Setup guide for initial creation.

Database Migrations

Migrations run automatically on first container start. To run manually:

# Run all migrations
for migration in infrastructure/postgres/migrations/*.sql; do
  echo "Running: $migration"
  docker exec -i brainstormer-postgres psql -U brainstormer -d brainstormer < "$migration"
done

Verify Infrastructure

# PostgreSQL
docker exec brainstormer-postgres pg_isready -U brainstormer

# Redis
docker exec brainstormer-redis redis-cli ping
# Should return: PONG

# ChromaDB
curl http://localhost:8000/api/v1/heartbeat

Environment Configuration

Copy Template

cp .env.docker .env

Set Required Keys

# OpenRouter (REQUIRED for AI features)
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# OpenAI (REQUIRED for Knowledge Base embeddings)
OPENAI_API_KEY=sk-your-key-here

# Database (Docker container)
DATABASE_URL=postgresql://brainstormer:password@localhost:5432/brainstormer

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT Secret
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

Optional Keys

ELEVENLABS_API_KEY=your-key          # Voice cloning
LLAMA_CLOUD_API_KEY=llx-your-key     # Advanced document parsing
PINECONE_API_KEY=your-key            # Production vector storage
CLOUD_STORAGE_ENABLED=false          # S3 file storage

Application Setup

Install Dependencies

npm install

This installs dependencies for all workspace packages: root, services/gateway, services/auth, services/bot, services/realtime-audio, services/knowledge, apps/web, and packages/shared.

Start Development Servers

npm run dev

This starts all services with hot-reload:

Service	URL
API Gateway	http://localhost:4000
Auth Service	http://localhost:4001
Bot Service	http://localhost:4002
Realtime Audio	http://localhost:4003
Knowledge Service	http://localhost:4005
Web App	http://localhost:3000

Verify Services

curl http://localhost:4000/health  # Gateway
curl http://localhost:4001/health  # Auth
curl http://localhost:4002/health  # Bot
curl http://localhost:4005/health  # Knowledge

Development Workflow

Making Changes

Edit code in your editor
Services auto-reload (tsx watch for backend, Turbopack for frontend)
Refresh browser to see frontend changes

Running Individual Services

cd services/auth && npm run dev       # Port 4001
cd services/bot && npm run dev        # Port 4002
cd services/gateway && npm run dev    # Port 4000
cd services/knowledge && npm run dev  # Port 4005
cd apps/web && npm run dev            # Port 3000

Stopping Services

# Stop npm dev: Ctrl+C in terminal

# Stop infrastructure (keeps data)
docker stop brainstormer-postgres brainstormer-redis brainstormer-chroma

Troubleshooting

Containers not running

docker ps -a | grep brainstormer
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma

Database connection errors

docker exec brainstormer-postgres pg_isready -U brainstormer
docker logs brainstormer-postgres

Port conflicts

lsof -ti:3000,4000,4001,4002,4003,4005 | xargs kill -9

Build errors

rm -rf node_modules package-lock.json
npm install
rm -rf .turbo
npm run build

TypeScript errors

npm run typecheck
npm run lint -- --fix

Missing environment variables

ls -la .env
cat .env | grep -E "OPENROUTER_API_KEY|OPENAI_API_KEY"

Quick Reference

# Complete startup
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma
npm install
npm run dev
open http://localhost:3000

# Complete shutdown
# Ctrl+C (stop npm dev)
docker stop brainstormer-postgres brainstormer-redis brainstormer-chroma

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Overview

Prerequisites

Infrastructure Setup (Docker)

Start Containers

Database Migrations

Verify Infrastructure

Environment Configuration

Application Setup

Install Dependencies

Start Development Servers

Verify Services

Development Workflow

Making Changes

Running Individual Services

Stopping Services

Troubleshooting

Quick Reference

​Overview

​Prerequisites

​Infrastructure Setup (Docker)

​Start Containers

​Database Migrations

​Verify Infrastructure

​Environment Configuration

​Application Setup

​Install Dependencies

​Start Development Servers

​Verify Services

​Development Workflow

​Making Changes

​Running Individual Services

​Stopping Services

​Troubleshooting

​Quick Reference

Overview

Prerequisites

Infrastructure Setup (Docker)

Start Containers

Database Migrations

Verify Infrastructure

Environment Configuration

Application Setup

Install Dependencies

Start Development Servers

Verify Services

Development Workflow

Making Changes

Running Individual Services

Stopping Services

Troubleshooting

Quick Reference