High-Performance Orderbook Engine

A bare-metal, low-latency financial orderbook matching engine written in modern C++17. Designed for High-Frequency Trading (HFT) scenarios using a Shared-Nothing Architecture and Lock-Free/Wait-Free data structures.

Now features a Real-time Market Data Service powered by ZeroMQ and DuckDB for high-throughput persistence and analytics, plus a WebSocket Gateway for frontend integration.

🚀 Key Features

• Architecture: Shared-Nothing, Worker-based design using Jump Consistent Hash for stable, localized routing.
• Zero-Lock Hot Path:
  • MPSC Queue: Custom fixed-size ring buffer with user-space SpinLocks (eliminating kernel context switches).
  • Batching: Automatic event batching to amortize cache coherency costs.
• Memory Optimization:
  • Flat Layouts: std::vector and custom flat maps instead of node-based containers.
  • Cache Alignment: Critical structures aligned to 64-byte cache lines.
  • No Allocations: Zero malloc/new on the hot path. All memory pre-allocated.
• Numeric Efficiency: Uses int64_t (PriceTicks) throughout the pipeline. No floating-point operations.
• Market Data System:
  • Broadcasting: Asynchronous ZeroMQ PUB/SUB for real-time snapshot distribution.
  • Persistence: DuckDB integration for high-speed, columnar storage of order book snapshots.
  • Web Gateway: WebSocket server powered by uWebSockets and FlatBuffers for streaming data to web/mobile clients.

🏗 System Components

The system is composed of three main services working in a pipeline:

1. Orderbook Engine (orderbook_engine)

   • Role: The core matching engine.
   • Function: Processes orders, matches trades, and broadcasts binary market data snapshots via ZeroMQ (IPC).
   • Tech: C++17, Lock-Free Queues, RingBuffers.

2. Market Data Service (market_data_service)

   • Role: Data persistence and query core.
   • Function: Ingests real-time data from the engine into DuckDB and provides a ZeroMQ (REP) interface for binary queries (Snapshots/History).
   • Tech: DuckDB, ZeroMQ.

3. WebSocket Gateway (websocket_service)

   • Role: Frontend access point.
   • Function: Handles client connections, "Time Wheel" based batch pushing, and protocol conversion (Binary -> FlatBuffers).
   • Tech: uWebSockets, FlatBuffers, ZeroMQ.

📊 Performance

On a standard commodity machine (Apple M1/M2 or modern Intel/AMD):

• Throughput: ~13.2 Million events/second (End-to-End).
• Latency: Sub-microsecond internal processing (amortized).
• Scalability: Linear scaling with core count (tested with 4 workers).

🛠 Build & Run

Prerequisites

• C++17 Compiler (GCC 9+, Clang 10+, MSVC 2019+)
• CMake 3.10+
• Ninja (Optional, recommended for speed)
• Libraries: ZeroMQ and DuckDB (Pre-compiled for macOS in libs/; falls back to system libraries on Linux/Windows).

Building the Project

# 1. Clone the repository
git clone https://github.com/anjing0524/orderbook-engine.git
cd orderbook-engine

# 2. Create build directory
mkdir build && cd build

# 3. Configure and Build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
ninja

This will produce the main executables:

• orderbook_engine
• market_data_service
• websocket_service

Running the Full System

The services should be started in the following order:

# 1. Start the Data Service (Persistence & Query)
./build/market_data_service &

# 2. Start the Engine (Matching & Production)
# Use the provided script for background execution
./scripts/start.sh

# 3. Start the WebSocket Gateway (Frontend Access)
./build/websocket_service &

Testing with Python Client: A python test client is provided to simulate a web frontend connecting to the WebSocket Gateway.

# Requires: pip install websockets flatbuffers
python3 python/test_client.py

⚙️ Configuration & Operations

The engine is configured via config.properties. Key settings include:

• kafka_brokers: Kafka bootstrap servers.
• wal_path: Directory for Write-Ahead Logs (Persistence).
• worker_count: Number of matching threads.

Operations:

• Start: ./scripts/start.sh
• Stop: ./scripts/stop.sh
• Logs: logs/engine.log (Structured info) & logs/stdout.log (Console output)

⚠️ Status & Roadmap

Current Status: Beta / Functional Prototype

• ✅ Core Matching Engine (Limit/Market orders, Cancel)
• ✅ Shared-Nothing Worker Architecture
• ✅ ZeroMQ IPC Messaging
• ✅ Market Data Persistence (DuckDB)
• 🚧 Unit Tests: Framework in place, coverage pending.
• 🚧 Configuration: Currently hardcoded/mocked in main.cpp. Needs external config support.
• 🚧 Recovery: WAL (Write-Ahead Logging) for engine state recovery is planned.

📂 Project Structure

• docs/: Project documentation.
• include/
  • core: Fundamental types (Price, OrderID) and constants.
  • engine: Core logic (InstrumentEngine, OrderBook, Worker).
  • memory: Memory management (MPSCQueue, RingBuffer, PoolAllocator).
  • service: Network protocols and service interfaces.
  • utils: Helpers (SpinLock, JumpHash).
• src/
  • main.cpp: Engine entry point.
  • service/: Service implementations (market_data_service, websocket_service).
• tests/: Test structure and end-to-end scripts.
• schema/: FlatBuffers schema definitions.

📚 Documentation

Detailed documentation is available in the docs/ directory:

• Architecture Overview
• WebSocket Service Design

📜 License

MIT License.