System Architecture
This document provides an overview of the architecture behind XCHG Lab, including its services, request flow, persistence layer, and communication between components.
A modular exchange architecture.
XCHG Lab is structured as a collection of independent services. Orders flow through the REST API into the matching engine, execution results are persisted in PostgreSQL and TimescaleDB, while Redis distributes events to WebSocket services for real-time market updates.
Independent services.
Every package is responsible for a single concern, allowing the system to remain modular while sharing common types and interfaces.
web
Next.js frontend responsible for authentication, trading interface, charting, and communication with the REST API and WebSocket server.
api
Express API responsible for validating requests, managing accounts, and forwarding orders to the matching engine.
engine
The core matching engine maintaining an in-memory order book with deterministic price-time priority execution.
ws
WebSocket gateway broadcasting market depth, trades, ticker updates, and private user events.
db
Shared Prisma package providing typed access to PostgreSQL and TimescaleDB across every service.
shared
Shared TypeScript types, Redis payloads, WebSocket messages, and protocol definitions used throughout the monorepo.
Life of a trade.
Placement
The client submits an order through the trading interface to the REST API.
Validation
The API validates balances and forwards the request to Redis.
Matching
The engine processes queued orders sequentially using price-time priority.
Persistence
Trades and balances are committed to PostgreSQL and TimescaleDB.
Broadcast
Redis publishes events which are streamed to connected WebSocket clients.
Public endpoints.
The REST API acts as the primary entry point for clients. It handles authentication, order placement, historical market data, and account management before forwarding requests to the matching engine.
/api/v1/orderPlace a new order.
/api/v1/orderCancel an active order.
/api/v1/order/openRetrieve open orders.
/api/v1/depthFetch market depth.
/api/v1/tradesRetrieve recent trades.
/api/v1/klinesRetrieve OHLCV candle data.
/api/v1/tickersRetrieve 24-hour ticker statistics.
Persistent storage.
PostgreSQL stores user accounts, balances, orders, and transaction history, while TimescaleDB extends PostgreSQL with time-series capabilities for efficient trade history and candlestick generation.
Users & Accounts
Authentication and user account management powered by NextAuth.
Wallets
Stores balances and assets available for trading.
Transactions
Maintains a complete audit trail for deposits, withdrawals, and executed trades.
Trades
TimescaleDB hypertable containing every executed trade across all markets.
Klines
Continuous aggregates generate 1m, 1h, 1d, and 1w OHLCV data for charting.
Built with modern tools.
XCHG Lab combines a modern TypeScript stack with real-time messaging, relational storage, and an in-memory matching engine to simulate the architecture of a modern electronic exchange.
Frontend
Next.js (App Router), React, Tailwind CSS, shadcn/ui
Backend
Node.js, Express
Database
PostgreSQL, TimescaleDB, Prisma ORM
Messaging
Redis Pub/Sub and Queues
Realtime
Native WebSockets
Language
TypeScript
Engineering through implementation.
XCHG Lab rebuilds the core systems behind a modern electronic exchange to better understand matching engines, market data distribution, real-time communication, and distributed backend architecture.
Every component is designed and implemented independently to explore the engineering trade-offs involved in building scalable exchange infrastructure from first principles.