Real-Time Order Matching Engine

A high-performance, distributed order matching and settlement system built with TypeScript, Node.js, Redis, and PostgreSQL. Processes 100+ orders per second with millisecond-level latency.

📋 Table of Contents

• Overview
• Architecture
• Features
• Quick Start
• Project Structure
• Performance
• Documentation
• Contributing

Overview

This is a complete real-time trading exchange platform with:

• Backend: High-performance order matching engine with async processing
• Frontend: Interactive trading dashboard with live order books and portfolio management

Key Metrics

• Throughput: 100+ orders/second
• Trade Generation: ~140 orders/sec matched at 75%+ ratio
• Latency: P99 < 1000ms at 100 concurrent users
• Architecture: Async processing with Redis queues and worker threads

Architecture

System Design

Frontend (Next.js)
    ↓
REST API (Express) / WebSocket
    ↓
Redis Queues (order_queue, trade_queue)
    ↓
├─ Matching Worker (Order Processing)
│   └─ Matching Engine (Trade Generation)
│       └─ Redis (trade_queue)
│           ↓
│       Settlement Worker (Trade Settlement)
│           └─ PostgreSQL (Persistence)
│               ↓
│           Metrics Collector
│
└─ WebSocket Server (Real-time Updates)

Components:

• API Layer: RESTful endpoints for orders, authentication, and portfolio
• Matching Engine: Price-time priority matching with side crossing validation
• Settlement Service: ACID-compliant trade settlement with idempotency
• Metrics System: Real-time performance tracking and throughput monitoring
• WebSocket Server: Live order books and trade execution feeds

Data Flow

1. User places order via REST API → 202 ACCEPTED response
2. Order queued to Redis order_queue
3. Matching Worker consumes and processes orders
4. Matched trades generated and published to trade_queue
5. Settlement Worker batches and settles trades (50 trades or 15ms)
6. Metrics and WebSocket updates sent to connected clients

Features

Trading Features

• ✅ Limit orders with price-time priority matching
• ✅ Buy/Sell side crossing validation
• ✅ FIFO queue within same price level
• ✅ ACID-compliant trade settlement
• ✅ Idempotent order processing
• ✅ Trade history and portfolio tracking

System Features

• ✅ Real-time metrics dashboard
• ✅ WebSocket live feeds
• ✅ Rate limiting (API protection)
• ✅ JWT authentication
• ✅ Comprehensive error handling
• ✅ Worker thread isolation

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Redis 7+

Installation

# Clone repository
git clone <repo-url>
cd order-matching-engine

# Backend setup
cd backend
npm install
cp .env.example .env
# Update .env with your database and Redis URLs

# Run migrations
npx prisma migrate dev

# Start backend
npm run dev

# Frontend setup (in new terminal)
cd frontend
pnpm install
npm run dev

Environment Variables

Backend (.env):

DATABASE_URL=postgresql://user:password@localhost:5432/trading_db
REDIS_URL=redis://localhost:6379
NODE_ENV=development
PORT=8000

Frontend (.env.local):

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

Run Load Test

cd backend
npm run loadtest 50 30  # 50 users, 30 seconds

Project Structure

order-matching-engine/
├── backend/
│   ├── src/
│   │   ├── index.ts              # Express server & worker management
│   │   ├── api/                  # REST endpoints
│   │   ├── auth/                 # Authentication
│   │   ├── services/             # Business logic
│   │   ├── worker/               # Worker threads
│   │   ├── queue/                # Redis queue management
│   │   ├── realtime/             # WebSocket server
│   │   ├── middleware/           # Express middleware
│   │   └── monitoring/           # Metrics collection
│   ├── prisma/
│   │   ├── schema.prisma         # Database schema
│   │   └── migrations/           # Database migrations
│   ├── tests/
│   │   └── loadTest.ts           # Load testing script
│   └── package.json
│
├── frontend/
│   ├── app/
│   │   ├── page.tsx              # Home page
│   │   ├── login/                # Authentication
│   │   ├── dashboard/            # Trading dashboard
│   │   └── layout.tsx            # Root layout
│   ├── components/               # React components
│   ├── lib/                      # Utilities
│   └── package.json
│
├── README.md                     # This file
├── ARCHITECTURE.md               # System design details
└── DEVELOPMENT.md                # Developer guide

Performance

Load Test Results (100 users, 30 seconds)

Metric	Value
Orders Placed	3,980
Throughput	100.42 orders/sec
Trades Executed	14,787
Avg Latency	454.92 ms
P95 Latency	751 ms
P99 Latency	993 ms
Success Rate	100%

Performance Characteristics

• Order Processing: 100+ orders/second
• Trade Matching: 75%+ of orders match (depends on price crossing)
• Settlement: Batched every 50 trades or 15ms
• Queue Latency: <50ms average
• Database Writes: Batched for efficiency

Documentation

• ARCHITECTURE.md - System design and component details
• DEVELOPMENT.md - Development setup and contribution guidelines
• backend/API_ROUTES.md - API endpoint documentation
• backend/SETUP.md - Detailed backend setup instructions
• frontend/README.md - Frontend documentation

Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes and test thoroughly
3. Run load tests: npm run loadtest
4. Submit a pull request

Development Commands

Backend:

npm run dev           # Start with ts-node
npm run build         # Build TypeScript
npm run loadtest      # Run load test (default: 50 users, 60s)
npm test              # Run tests
npx prisma studio    # Open database UI

Frontend:

npm run dev           # Start dev server
npm run build         # Build for production
npm run lint          # Run ESLint

API Endpoints

Authentication

• POST /auth/register - User registration
• POST /auth/login - User login
• POST /auth/logout - User logout

Orders

• POST /orders - Place new order
• GET /orders - Get user's orders
• GET /orders/:id - Get specific order

Portfolio

• GET /portfolio - Get user portfolio

Metrics

• GET /metrics - System performance metrics

See API_ROUTES.md for detailed endpoint documentation.

License

MIT

Support

For issues and questions, please open an issue on the repository.