StockEx User Guide

1. Introduction

StockEx is a comprehensive real-time trading simulation platform inspired by Euronext OPTIQ. It provides a complete electronic trading ecosystem including order entry, matching engine, market data distribution, and live visualization.

    Key Features:
    FIX 4.4 protocol support for institutional order entry
Real-time order matching with price-time priority
Live market data streaming via Kafka
Web-based dashboard with Server-Sent Events (SSE)
Order management (Edit/Cancel) capabilities
Trading analytics and statistics

  

Access URLs:
Dashboard: http://localhost:5005
Frontend (Order Entry): http://localhost:5000
FIX Gateway: localhost:5001
Matcher API: http://localhost:6000

2. System Architecture

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ FIX UI Client │ │ FIX UI Client │ │ Frontend │ │ (Port 5002) │ │ (Port 5003) │ │ (Port 5000) │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ │ FIX 4.4 │ FIX 4.4 │ HTTP ▼ ▼ ▼ ┌────────────────────────────────────────────────────────────────┐ │ FIX OEG (Port 5001) │ │ QuickFIX Order Entry Gateway │ └────────────────────────────────┬───────────────────────────────┘ │ ▼ Kafka [orders] ┌────────────────────────────────────────────────────────────────┐ │ Apache Kafka (Port 9092) │ │ Topics: orders, trades, snapshots │ └───────┬────────────────────┬───────────────────────┬───────────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ Matcher │ │ MD Feeder │ │ Dashboard │ │ (Port 6000) │ │ (MDF) │ │ (Port 5005) │ │ │ │ │ │ │ │ Order Book │ │ Price Sim │ │ Web UI + SSE │ │ Trade Match │ │ BBO Publish │ │ Real-time │ └───────────────┘ └───────────────┘ └───────────────┘

3. Module Descriptions

Zookeeper

Port 2181

Apache Zookeeper provides distributed coordination for the Kafka cluster. It manages broker metadata, topic configurations, and cluster membership.

Function	Kafka cluster coordination
Technology	Confluent Zookeeper 7.5.0
Dependencies	None

Kafka Message Broker

Port 9092 Port 29092 (host)

Apache Kafka serves as the central message backbone for the entire system. All order flow, trade executions, and market data are distributed through Kafka topics.

Function	Message streaming and event distribution
Technology	Confluent Kafka 7.5.0
Topics	`orders`, `trades`, `snapshots`
Dependencies	Zookeeper

FIX Order Entry Gateway (FIX OEG)

Port 5001

The FIX OEG is a QuickFIX/Python acceptor that receives orders via FIX 4.4 protocol from institutional clients. It validates incoming messages, normalizes them to JSON format, and publishes to the Kafka orders topic.

Function	FIX protocol order reception and normalization
Technology	QuickFIX/Python
Protocol	FIX 4.4
Message Types	NewOrderSingle (D), OrderCancelRequest (F), OrderCancelReplaceRequest (G)
Output	Kafka `orders` topic

FIX UI Clients

Port 5002 (Client 1) Port 5003 (Client 2)

Web-based FIX initiator clients that connect to the FIX OEG. They provide a user interface for submitting orders via FIX protocol, simulating institutional trading terminals.

Function	FIX order submission interface
Technology	QuickFIX/Python + Flask
Features	New Order, Cancel, Amend
Connection	FIX 4.4 to FIX OEG

Matcher (Order Matching Engine)

Port 6000

The core matching engine that maintains order books for all securities. It consumes orders from Kafka, attempts to match them using price-time priority, and publishes resulting trades. Provides REST API for order book and trade queries.

Function	Order matching, trade execution, order book management
Technology	Python/Flask with SQLite persistence
Algorithm	Price-Time Priority (FIFO)
Input	Kafka `orders` topic
Output	Kafka `trades` topic
API Endpoints	`/orderbook/<symbol>`, `/trades`, `/health`

Market Data Feeder (MDF)

Internal

Simulates market data by generating random orders and publishing Best Bid/Offer (BBO) snapshots. Creates realistic market activity with configurable order rates and price movements.

Function	Market simulation and BBO publishing
Technology	Python
Output	Kafka `orders` and `snapshots` topics
Order Mix	90% passive (book building), 10% aggressive (trades)
Rate	Configurable (default: 8 orders/minute)

Dashboard

Port 5005

Real-time web dashboard providing comprehensive market visualization. Uses Server-Sent Events (SSE) for live streaming updates without page refresh. Displays orders, trades, market snapshots, order book depth, and trading statistics.

Function	Real-time market visualization and order management
Technology	Python/Flask + JavaScript
Streaming	Server-Sent Events (SSE)
Input	Kafka topics + Matcher REST API
Features	Orders, Trades, BBO, Order Book, Charts, Statistics

Frontend (Manual Order Entry)

Port 5000

Simple web interface for manual order submission. Allows users to enter orders directly without FIX protocol, useful for testing and demonstration.

Function	Manual order entry interface
Technology	Python/Flask
Output	Kafka `orders` topic

Consumer (Debug)

Internal

Debug utility that consumes and logs messages from Kafka topics. Useful for monitoring message flow and troubleshooting.

Snapshot Viewer

Internal

Utility service that subscribes to the snapshots topic and logs BBO updates. Writes to log files for analysis.

4. Dashboard User Interface

4.1 Orders Panel

Displays real-time incoming orders with full management capabilities.

Column	Description
Symbol	Stock ticker (ALPHA, EXAE, PEIR, QUEST)
Side	BUY (green) or SELL (red)
Qty	Order quantity in shares
Price	Limit price
Source	Order origin (MDF, FIX, Manual)
Time	Order timestamp
Actions	Edit / Cancel buttons

Row Selection: Click any row to select, then use header buttons for bulk actions.

4.2 Market Snapshot

Shows Best Bid/Offer (BBO) for all securities with real-time updates.

Column	Description
Symbol	Security identifier
Best Bid	Highest buy price (green)
Best Ask	Lowest sell price (red)
Spread	Ask - Bid difference
Mid	Midpoint: (Bid + Ask) / 2
Updated	Last update timestamp

Ticker Tape: Scrolling bar at bottom displays recent trades with price direction (▲ green up, ▼ red down).

4.3 Trades Panel

Lists all executed trades with calculated values.

Column	Description
Symbol	Traded security
Qty	Executed quantity
Price	Execution price
Value	Trade value (Qty × Price)
Time	Execution timestamp

4.4 Order Book

Displays full market depth for selected symbol.

Select symbol from dropdown menu
Click Refresh to update (auto-refreshes every 3 seconds)
Bid Qty / Bid Price — Buy orders sorted by price (highest first)
Ask Price / Ask Qty — Sell orders sorted by price (lowest first)
Header shows total bid and ask counts

4.5 Trade Chart

Visual representation of trade activity over time.

Green line — Price trend connecting trade prices
Blue bars — Volume per trade
Dropdown to filter by symbol or view all
Displays last 100 trades

4.6 Trading Statistics

Aggregated metrics calculated from all trades.

Metric	Description
Trades	Number of executed trades
Volume	Total shares traded
Value	Total monetary value (Σ Qty × Price)
Start	First trade price (opening)
Last	Most recent trade price
VWAP	Volume-Weighted Average Price

Bar Charts: Visual comparison showing Volume and Value per symbol side by side.

5. Data Flow & Messaging

5.1 Kafka Topics

Topic	Producers	Consumers	Content
`orders`	FIX OEG, MDF, Frontend	Matcher, Dashboard	New orders, cancels, amends
`trades`	Matcher	Dashboard, Consumer	Executed trades
`snapshots`	MDF	Dashboard, Snapshot Viewer	BBO updates

5.2 Message Formats

Order Message

{ "symbol": "ALPHA", "side": "BUY", "price": 25.50, "quantity": 100, "cl_ord_id": "MDF-1234567890-1", "timestamp": 1234567890.123, "source": "MDF" }

Trade Message

{ "symbol": "ALPHA", "price": 25.50, "quantity": 100, "buy_order_id": "order-123", "sell_order_id": "order-456", "timestamp": 1234567890.123 }

Snapshot Message

{ "symbol": "ALPHA", "best_bid": 25.45, "best_ask": 25.55, "bid_size": 500, "ask_size": 300, "timestamp": 1234567890.123, "source": "MDF" }

6. Configuration

Variable	Default	Description
`KAFKA_BOOTSTRAP`	kafka:9092	Kafka broker address
`MATCHER_URL`	http://matcher:6000	Matcher API endpoint
`TICK_SIZE`	0.05	Minimum price increment
`ORDERS_PER_MIN`	8	MDF order generation rate
`SECURITIES_FILE`	/app/data/securities.txt	Securities configuration

6.1 Supported Securities

Symbol	Start Price	Description
ALPHA	25.00	Test Security A
EXAE	42.00	Test Security B
PEIR	18.50	Test Security C
QUEST	12.75	Test Security D

7. Quick Reference

7.1 Starting the System

docker compose up --build

7.2 Service URLs

Service	URL	Purpose
Dashboard	http://localhost:5005	Main trading view
Frontend	http://localhost:5000	Manual order entry
FIX Client 1	http://localhost:5002	FIX order submission
FIX Client 2	http://localhost:5003	FIX order submission
Matcher API	http://localhost:6000	REST API

7.3 Dashboard Actions

Action	How To
View order book depth	Select symbol from Order Book dropdown
Edit an order	Click Edit button on order row
Cancel an order	Click Cancel button on order row
Filter trade chart	Select symbol from Trade Chart dropdown
Pause ticker tape	Hover mouse over the ticker
Select multiple orders	Click rows, use header Edit/Cancel buttons

7.4 Connection Status Indicators

Status	Indicator	Meaning
Live	● Green	Connected to real-time stream
Connecting	● Yellow	Establishing connection
Disconnected	● Red	Connection lost, auto-reconnecting

StockEx Trading Dashboard

1. Introduction

2. System Architecture

3. Module Descriptions

Zookeeper

Kafka Message Broker

FIX Order Entry Gateway (FIX OEG)

FIX UI Clients

Matcher (Order Matching Engine)

Market Data Feeder (MDF)

Dashboard

Frontend (Manual Order Entry)

Consumer (Debug)

Snapshot Viewer

4. Dashboard User Interface

4.1 Orders Panel

4.2 Market Snapshot

4.3 Trades Panel

4.4 Order Book

4.5 Trade Chart

4.6 Trading Statistics

5. Data Flow & Messaging

5.1 Kafka Topics

5.2 Message Formats

Order Message

Trade Message

Snapshot Message

6. Configuration

6.1 Supported Securities

7. Quick Reference

7.1 Starting the System

7.2 Service URLs

7.3 Dashboard Actions

7.4 Connection Status Indicators