Running Locally

Quick Start

Use the automated startup script to launch all services:

bash scripts/startup.sh

This script will:

1. Start TimescaleDB — Launches Docker container for the database
2. Build WebSocket Service — Compiles TypeScript and starts ws-service on port 8081
3. Start Next.js — Launches the frontend on port 3000
4. Verify Services — Checks all services are running correctly

Manual Startup

Start services manually in separate terminal windows:

# Terminal 1: Database
docker-compose up -d timescaledb

# Terminal 2: WebSocket Service
cd ws-service
npm install
npm run build
HTTP_PORT=8081 npm run start

# Terminal 3: Next.js Frontend
cd /path/to/Polyblock-main
npm install
npm run dev

lsof -ti :3000 :8081 | xargs kill -9

Verify Services

Check all services are running:

# Check database
docker-compose ps timescaledb

# Check WebSocket service
curl http://localhost:8081/health
# Expected: {"status":"ok"}

# Check Next.js
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Expected: 200

Then open http://localhost:3000 in your browser.

Common Issues

WebSocket connection errors in browser

Ensure ws-service is running on port 8081 and .env.local has correct NEXT_PUBLIC_WEBSOCKET_SERVER_URL.

No market data loading

The ws-service needs to be running to fetch market data. Check its logs for connection errors.

Database connection failed

Verify TimescaleDB container is healthy and DATABASE_URL is correct.

TypeScript build errors

Run npm install in ws-service directory to ensure all dependencies are installed.

Day-to-day workflow

Keep three terminals tabbed: database logs, websocket service logs, and Next.js dev. When you change API routes, watch both the browser network panel and the server console. When you change websocket schemas, restart the ws-service before chasing UI bugs.

Use realistic USDC test amounts in staging-like data if you mirror production flows, but never use production keys on localhost. Document any extra ports (admin tools, workers) your branch introduces so reviewers can boot the stack without spelunking.