Overview

Educational backend reference for a centralized perpetual futures exchange.

The implementation favors explicit TypeScript modules, deterministic tests, and simple service boundaries over heavy abstractions.

Implemented Packages

packages/matching-engine   In-memory orderbook, matching, snapshots, recovery
packages/db                Prisma schema contracts, persistence service, mappers
packages/risk              Positions, margin, funding, liquidation, ADL
packages/websocket         Subscription hub and websocket server factory
packages/runtime           API/worker orchestration and stream bus
apps/api                   Runnable backend API with in-process workers
apps/workers               Local and production worker loop entrypoint
apps/market-data           Binance mark-price ingestion into Redis Streams

Infrastructure

docker compose up -d postgres redis

Environment defaults are documented in .env.example.

Prisma

Schema:

prisma/schema.prisma

Initial migration:

prisma/migrations/20260614000000_phase_2_persistence/migration.sql

Seed data:

prisma/seed.sql

Prisma dependencies are installed at the workspace root. Run package scripts from packages/db when generating, migrating, or seeding the database.

Verification

bun test
bunx tsc --noEmit -p packages/matching-engine/tsconfig.json
bunx tsc --noEmit -p packages/db/tsconfig.json
bunx tsc --noEmit -p packages/risk/tsconfig.json
bunx tsc --noEmit -p packages/websocket/tsconfig.json
bunx tsc --noEmit -p packages/runtime/tsconfig.json
bunx tsc --noEmit -p apps/api/tsconfig.json
bunx tsc --noEmit -p apps/workers/tsconfig.json
bunx tsc --noEmit -p apps/market-data/tsconfig.json
docker compose config
git diff --check

Run Local Backend

bun run apps/api/src/index.ts

The API process runs the matching and persistence workers in-process by default so the local backend is functional without extra services. This keeps the learning setup simple. The stream abstraction mirrors Redis Streams closely enough that a Redis adapter can replace the in-memory stream bus for a multi-process deployment.

Run Production Wiring

Start infrastructure, generate/migrate/seed Prisma, then run the production processes with real PostgreSQL, Redis Streams, and Binance market data:

docker compose up -d postgres redis
cd packages/db
bun run prisma:generate
bun run prisma:deploy
bun run db:seed

Example environment:

DATABASE_URL=postgresql://perp:perp@localhost:5432/perp_v3
REDIS_URL=redis://localhost:6379
JWT_SECRET=dev-secret-change-me
SNAPSHOT_DIR=./snapshots
BINANCE_WS_URL=wss://fstream.binance.com
RUNTIME_MODE=production

Run:

bun run apps/api/src/index.ts
bun run apps/workers/src/index.ts
bun run apps/market-data/src/index.ts

Documentation

docs/ARCHITECTURE.md
docs/API.md
docs/WEBSOCKETS.md
docs/RECOVERY.md
docs/TESTING.md

Phase Status

Phase 1: Core matching engine implemented.
Phase 2: Persistence schema and event persistence contracts implemented.
Phase 3: Positions and cross-margin implemented.
Phase 4: Funding implemented.
Phase 5: Liquidation, insurance fund, and simplified ADL implemented.
Phase 6: WebSocket subscriptions and fanout implemented.
Phase 7: Snapshots and recovery implemented.
Phase 8: Documentation, runtime wiring, and verification pass implemented.

Overview

On this page