# Architecture

The Nekuti Matching Engine is built on an event-sourced architecture with several specialized components working together to deliver ultra-low-latency trade execution while maintaining data integrity, determinism, and scalability.

# Components

# Engine

The engine is the core component of the Nekuti Matching Engine. It is an event-sourced Java process, and ensures every command is sequenced and persisted before it's processed.

Location: Can be deployed on an isolated network to reduce cyber-attack surfaces. All communication with the engine is via engine-initiated outbound TCP connections. The engine does not accept any inbound connectivity.

Key characteristics:

• Write-Ahead Logging: Commands are persisted in an append-only command log before processing, ensuring no data loss
• Binary Format: Uses a proprietary binary format for maximum performance
• State Reconstruction: On startup, the engine re-reads commands and reconstructs its state
• Ultra-Low Latency: Spin-waits on several threads handling the hot-path of command processing
• Communication: Uses a proprietary binary protocol over TCP to communicate with gateways

# Snapshotter

The snapshotter is a separate process that runs alongside the engine to optimize startup time and manage storage.

Location: Deployed alongside the engine.

Key responsibilities:

• Periodic Snapshots: At configurable intervals, loads the latest command files and generates a snapshot of the current state
• Fast Startup: Allows the engine to start quickly by reading the most recent snapshot instead of replaying all commands since inception
• Archiving: Moves older snapshots and command files to an archive directory
• Optional Component: The engine can run without the snapshotter, though startup times would be longer as it would need to replay more commands

# Gateways

Gateways handle protocol translation between web-based clients using JSON (REST/WebSockets) and the engine's binary protocol.

All gateway variants are implemented in Java and communicate with the engine via the proprietary binary format over TCP.

# User Gateway

• Location: Sits on a DMZ or other internet-accessible network
• Purpose: Exposes REST and WebSocket APIs directly to users for low-latency access to trading functions (order entry, position queries, etc.)
• Target Clients: Typically web-based user interfaces
• Security Model: Since user gateways and the hosts they run on are exposed to potentially hostile internet traffic, they cannot initiate connections to the engine. Instead, the engine initiates outbound connections to configured user-gateway instances
• APIs: Exposes de-facto industry standard APIs

# Control Gateway

• Location: Runs on the internal network
• Purpose: Exposes administrative endpoints for operators to control the engine
• Connection Model: Initiates connections inward to the engine

# Monitor Gateway

• Location: Runs on the internal network
• Purpose: Provides read-only access to engine state
• Functions: Exposes read-only endpoints that cannot cause any state changes in the engine
• Connection Model: Similar to control gateway

# Janitor

The janitor is a script that handles long-term storage management.

Key responsibilities:

• Compression: Takes command logs and snapshots from the archive directory and compresses them
• Deep Storage: Moves compressed archives to more cost-effective storage solutions
• Rationale: Since these older files are not part of the active running state of the engine, they can be stored on cheaper storage tiers

# Data Flow

1. Command Entry: Commands arrive at gateways as JSON (REST/WebSocket)
2. Protocol Translation: Gateways transform JSON to binary protocol
3. Command Transmission: Binary commands sent to engine via TCP
4. Write-Ahead Log: Engine persists commands to append-only log before processing
5. Command Processing: Engine processes the commands and updates internal state
6. Response: Engine sends binary response back to gateway
7. JSON Transformation: Gateway transforms binary response to JSON
8. Client Response: JSON response delivered to client via REST/WebSocket

# Snapshot and Archive Flow

1. Periodic Snapshot: Snapshotter loads latest command files at configured intervals
2. State Generation: Creates a snapshot of the current engine state
3. Archive: Moves older snapshots and command files to archive directory
4. Compression: Janitor compresses archived files
5. Deep Storage: Janitor moves compressed archives to cost-effective storage

# Deployment Options

All processes can be run in either:

• Docker containers: For easy orchestration and consistent environments
• Native host processes: For maximum performance when required

# Horizontal Scaling

The architecture allows gateways to scale horizontally since they handle the computationally expensive work of translating between JSON and binary formats. Multiple gateway instances can be deployed to handle increased load, while the engine remains as a single, highly-optimized process ensuring sequential consistency of all trades.