Initial commit: StockEx trading platform

Kafka-based stock exchange simulation with:
- Order matcher engine with SQLite persistence
- FIX protocol OEG server and UI clients
- Frontend order entry with real-time book/trades
- Trading dashboard with SSE streaming and charts
- Market data feeder, consumer, and snapshot viewer
- Docker Compose orchestration for all services

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# FIX session runtime files
+fix-ui-client/log/
+fix-ui-client/store/
+fix_oeg/log/
+fix_oeg/store/
+
+# Application logs
+logs/
+
+# Runtime state
+shared_data/order_id.txt
+
+# SQLite databases
+*.db
+*.sqlite3
+
+# Docker volumes / local data
+matcher_data/
+
+# Windows artifact
+nul
+
+# Claude Code local config
+.claude/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

Dockerfile.base

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+# Install build tools and deps for QuickFIX
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /opt
+
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt

IMPROVEMENT_PLAN.md

@@ -0,0 +1,271 @@
+# KafkaTradingSystem Improvement Plan
+
+> **Created:** 2026-02-03
+> **Status:** ✅ Core implementation complete (Phases 1-5 done)
+> **Last Updated:** 2026-02-03
+> **Resume:** Share this file with Claude to continue from where we left off
+
+---
+
+## Overview
+
+This plan outlines improvements to transform the trading system from a demo/prototype into a more robust, production-like system. Improvements are organized by priority and complexity.
+
+---
+
+## Phase 1: Real-Time Dashboard (WebSocket/SSE)
+
+**Problem:** Dashboard polls `/data` every 2 seconds (`setInterval(refresh, 2000)`), causing unnecessary load and delayed updates.
+
+**Solution:** Implement Server-Sent Events (SSE) for real-time push updates.
+
+### Tasks
+
+- [x] **1.1** Add SSE endpoint to `dashboard/dashboard.py` ✅
+  - Create `/stream` endpoint using Flask's `Response` with `text/event-stream`
+  - Push events when new orders/trades/snapshots arrive from Kafka
+  - File: `dashboard/dashboard.py`
+
+- [x] **1.2** Update dashboard frontend to use SSE ✅
+  - Replace `setInterval(refresh, 2000)` with `EventSource('/stream')`
+  - Handle reconnection on disconnect
+  - File: `dashboard/templates/index.html`
+
+- [x] **1.3** Add connection status indicator ✅
+  - Show connected/disconnected state in UI
+  - File: `dashboard/templates/index.html`
+
+### Why SSE over WebSocket?
+- Simpler implementation (HTTP-based, no special protocol)
+- One-way server-to-client is sufficient for this use case
+- Better browser support and automatic reconnection
+
+---
+
+## Phase 2: SQLite Persistence
+
+**Problem:** All data is in-memory; order books and trades lost on restart.
+
+**Solution:** Add SQLite database for persistence with in-memory caching.
+
+### Tasks
+
+- [x] **2.1** Create database schema and initialization ✅
+  - Tables: `orders`, `trades`, `order_book_entries`
+  - Add migration/init script
+  - New file: `matcher/database.py`
+
+- [x] **2.2** Modify matcher to persist trades ✅
+  - Write trades to SQLite when matched
+  - Load recent trades on startup
+  - File: `matcher/matcher.py`
+
+- [x] **2.3** Persist order book state ✅
+  - Save resting orders to database
+  - Restore order books on matcher restart
+  - File: `matcher/matcher.py`
+
+- [x] **2.4** Add trade history endpoint ✅
+  - `GET /trades?symbol=X&limit=N&offset=M`
+  - Support filtering and pagination
+  - File: `matcher/matcher.py`
+
+- [x] **2.5** Add Docker volume for database persistence ✅
+  - Mount SQLite file to host
+  - File: `docker-compose.yml`
+
+### Schema Design
+
+```sql
+CREATE TABLE trades (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    symbol TEXT NOT NULL,
+    price REAL NOT NULL,
+    quantity INTEGER NOT NULL,
+    buy_order_id TEXT,
+    sell_order_id TEXT,
+    timestamp REAL NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE order_book (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    cl_ord_id TEXT UNIQUE,
+    symbol TEXT NOT NULL,
+    side TEXT NOT NULL,  -- 'BUY' or 'SELL'
+    price REAL,
+    quantity INTEGER NOT NULL,
+    remaining_qty INTEGER NOT NULL,
+    status TEXT DEFAULT 'OPEN',  -- OPEN, FILLED, CANCELLED
+    timestamp REAL NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_trades_symbol ON trades(symbol);
+CREATE INDEX idx_trades_timestamp ON trades(timestamp);
+CREATE INDEX idx_orderbook_symbol_side ON order_book(symbol, side);
+```
+
+---
+
+## Phase 3: FIX Protocol Improvements
+
+**Problem:** Basic FIX handling with no validation, no execution reports, no order management.
+
+### Tasks
+
+- [x] **3.1** Add FIX message validation ✅
+  - Validate required fields (ClOrdID, Symbol, Side, OrderQty)
+  - Validate field formats and ranges
+  - Return Reject (35=3) for invalid messages
+  - File: `fix_oeg/fix_oeg_server.py`
+
+- [x] **3.2** Send Execution Reports back to clients ✅
+  - Send 35=8 (ExecutionReport) for order acknowledgment
+  - Send fill reports when trades occur
+  - Requires Kafka consumer for trades topic in fix_oeg
+  - File: `fix_oeg/fix_oeg_server.py`
+
+- [x] **3.3** Support Order Cancel Request (35=F) ✅
+  - Parse cancel requests
+  - Publish to orders Kafka topic (with type=cancel)
+  - Files: `fix_oeg/fix_oeg_server.py`
+
+- [x] **3.4** Support Order Cancel/Replace (35=G) ✅
+  - Parse modify requests
+  - Implement price/quantity amendments
+  - Files: `fix_oeg/fix_oeg_server.py`, `matcher/matcher.py`
+
+- [ ] **3.5** Add session-level validation (DEFERRED)
+  - Sequence number checking handled by QuickFIX engine
+  - Heartbeat/TestRequest handled automatically
+  - File: `fix_oeg/fix_oeg_server.py`
+
+### Execution Report Fields (35=8)
+
+```
+Tag 35 = 8 (ExecutionReport)
+Tag 37 = OrderID (exchange-assigned)
+Tag 11 = ClOrdID (client order ID)
+Tag 17 = ExecID
+Tag 20 = ExecTransType (0=New)
+Tag 39 = OrdStatus (0=New, 1=PartialFill, 2=Filled)
+Tag 150 = ExecType (0=New, F=Trade)
+Tag 55 = Symbol
+Tag 54 = Side
+Tag 38 = OrderQty
+Tag 44 = Price
+Tag 32 = LastShares (fill qty)
+Tag 31 = LastPx (fill price)
+Tag 14 = CumQty
+Tag 151 = LeavesQty
+Tag 6 = AvgPx
+```
+
+---
+
+## Phase 4: Enhanced Order Types
+
+**Problem:** Only limit orders supported.
+
+### Tasks
+
+- [x] **4.1** Support Market Orders ✅
+  - Match immediately at best available price
+  - No price field required (OrdType=1)
+  - File: `matcher/matcher.py`
+
+- [x] **4.2** Support IOC (Immediate-or-Cancel) ✅
+  - TimeInForce=3: Fill what's available, cancel rest
+  - File: `matcher/matcher.py`
+
+- [x] **4.3** Support FOK (Fill-or-Kill) ✅
+  - TimeInForce=4: Fill entire order or reject
+  - File: `matcher/matcher.py`
+
+- [x] **4.4** Support GTC (Good-Till-Cancel) ✅
+  - TimeInForce=1: Persist until explicitly cancelled
+  - Implemented via SQLite persistence (Phase 2)
+  - File: `matcher/matcher.py`
+
+---
+
+## Phase 5: Monitoring & Observability
+
+### Tasks
+
+- [x] **5.1** Add health check endpoints ✅
+  - `/health` endpoint for matcher, dashboard, frontend
+  - Check Kafka/DB connectivity and service stats
+  - Files: `matcher/matcher.py`, `dashboard/dashboard.py`, `frontend/frontend.py`
+
+- [x] **5.2** Add structured logging ✅
+  - JSON log format for parsing
+  - Include correlation IDs
+  - New file: `shared/logging_utils.py`
+
+- [x] **5.3** Add metrics endpoint ✅
+  - Order count, trade count, latency stats
+  - Prometheus-compatible format (`/metrics` endpoint)
+  - File: `matcher/matcher.py`
+
+- [ ] **5.4** Add Kafka lag monitoring (OPTIONAL)
+  - Track consumer group lag
+  - Alert on high lag
+  - New file: `shared/monitoring.py`
+
+---
+
+## Phase 6: Testing & Quality
+
+### Tasks
+
+- [x] **6.1** Add unit tests for matcher ✅
+  - Test matching logic (full/partial fills, price-time priority)
+  - Test order types (market, limit, IOC, FOK)
+  - Test cancel and amend operations
+  - New file: `matcher/test_matcher.py`
+
+- [ ] **6.2** Add integration tests (OPTIONAL)
+  - End-to-end order flow tests
+  - FIX client to trade execution
+  - New directory: `tests/`
+
+- [ ] **6.3** Add load testing script (OPTIONAL)
+  - Generate high-volume order flow
+  - Measure latency and throughput
+  - New file: `tests/load_test.py`
+
+---
+
+## Implementation Order (Recommended)
+
+1. **Phase 1** (Real-Time Dashboard) - Quick win, improves UX
+2. **Phase 2** (SQLite Persistence) - Foundation for reliability
+3. **Phase 3.1-3.2** (FIX Validation + Execution Reports) - Core trading functionality
+4. **Phase 5.1** (Health Checks) - Operational necessity
+5. **Phase 4.1** (Market Orders) - Common order type
+6. **Phase 3.3** (Order Cancellation) - Essential for trading
+7. Remaining phases as needed
+
+---
+
+## Quick Reference: Key Files
+
+| Component | Main File | Port |
+|-----------|-----------|------|
+| FIX Gateway | `fix_oeg/fix_oeg_server.py` | 5001 |
+| Matcher | `matcher/matcher.py` | 6000 |
+| Dashboard | `dashboard/dashboard.py` | 5005 |
+| Frontend | `frontend/frontend.py` | 5000 |
+| Config | `shared/config.py` | - |
+
+---
+
+## How to Continue
+
+When resuming work, tell Claude:
+1. Which phase/task to work on (e.g., "Let's implement Phase 1.1")
+2. Or ask Claude to pick the next logical task
+
+Each task is designed to be implementable in a single session.

README_OPTIQ.md

@@ -0,0 +1,73 @@
+# StockEx — Euronext/OPTIQ Trading System Emulator
+
+## Overview
+
+**StockEx** is a real-time trading simulation platform inspired by Euronext OPTIQ. It provides a complete order flow from FIX protocol entry through matching engine to trade execution, with live visualization via a web dashboard.
+
+## Architecture
+
+| Component | Description |
+|-----------|-------------|
+| **FIX OEG** | QuickFIX acceptor receiving FIX 4.4 orders |
+| **Kafka** | Message backbone (topics: `orders`, `snapshots`, `trades`) |
+| **Matcher** | Order matching engine with price-time priority |
+| **MDF** | Market Data Feeder publishing BBO snapshots |
+| **Dashboard** | Real-time web UI with SSE streaming |
+
+## Data Flow
+
+```
+FIX Client → FIX OEG → Kafka [orders] → Matcher → Kafka [trades]
+                                            ↓
+MDF → Kafka [snapshots] ───────────→ Dashboard (Flask)
+```
+
+## Dashboard Features
+
+- **Orders Panel** — Live order feed with Edit/Cancel actions
+- **Market Snapshot** — Best Bid/Ask with spread, mid price, and scrolling ticker
+- **Trades Panel** — Executed trades with value calculation
+- **Order Book** — Depth of book per symbol (bids/asks)
+- **Trade Chart** — Price and volume visualization
+- **Trading Statistics** — Volume, Value, VWAP per symbol with bar charts
+
+![Trading Dashboard](screenshots/dashboard.png)
+
+## Quick Start
+
+```bash
+docker compose up --build
+```
+
+Open dashboard: **http://localhost:5005**
+
+## Directory Structure
+
+```
+StockEx/
+├── docker-compose.yml
+├── fix_oeg/          # FIX Order Entry Gateway
+├── fix-ui-client/    # FIX test clients
+├── matcher/          # Order matching engine
+├── md_feeder/        # Market data simulator
+├── dashboard/        # Flask web dashboard
+├── frontend/         # Manual order entry UI
+├── shared/           # Common config and utilities
+└── shared_data/      # Securities and state files
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KAFKA_BOOTSTRAP` | kafka:9092 | Kafka broker address |
+| `TICK_SIZE` | 0.05 | Minimum price increment |
+| `ORDERS_PER_MIN` | 8 | MDF order generation rate |
+
+## Requirements
+
+- Docker & Docker Compose
+- Ports: 5005 (Dashboard), 6000 (Matcher), 9092 (Kafka)
+
+---
+*StockEx v1.0 — Trading Simulation Platform*

StockEx_Developer_Guide.html

@@ -0,0 +1,569 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>StockEx - Developer Guide</title>
+  <style>
+    @page { margin: 1.5cm; size: A4; }
+    body { font-family: 'Segoe UI', Arial, sans-serif; max-width: 900px; margin: 0 auto; padding: 20px; line-height: 1.5; color: #333; font-size: 11pt; }
+    h1 { color: #1a1a2e; border-bottom: 3px solid #4CAF50; padding-bottom: 10px; font-size: 24pt; }
+    h2 { color: #2e7d32; margin-top: 25px; border-bottom: 1px solid #ddd; padding-bottom: 5px; font-size: 16pt; page-break-after: avoid; }
+    h3 { color: #1565c0; margin-top: 18px; font-size: 13pt; }
+    h4 { color: #555; margin-top: 12px; font-size: 11pt; }
+    table { width: 100%; border-collapse: collapse; margin: 12px 0; font-size: 10pt; }
+    th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
+    th { background: #f5f5f5; font-weight: bold; }
+    tr:nth-child(even) { background: #fafafa; }
+    .header { text-align: center; margin-bottom: 25px; }
+    .subtitle { color: #666; font-size: 14pt; }
+    .version { color: #999; font-size: 10pt; }
+    .section { page-break-inside: avoid; margin-bottom: 20px; }
+    .highlight { background: #e8f5e9; padding: 12px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #4CAF50; }
+    .info { background: #e3f2fd; padding: 12px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #2196F3; }
+    .warning { background: #fff3e0; padding: 12px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #ff9800; }
+    .code-block { background: #263238; color: #aed581; padding: 15px; border-radius: 5px; font-family: 'Consolas', monospace; font-size: 10pt; overflow-x: auto; margin: 10px 0; white-space: pre; }
+    .json { background: #37474f; color: #80cbc4; }
+    code { background: #f5f5f5; padding: 2px 6px; border-radius: 3px; font-family: 'Consolas', monospace; font-size: 10pt; }
+    .green { color: #2e7d32; }
+    .red { color: #c62828; }
+    .blue { color: #1565c0; }
+    hr { border: none; border-top: 1px solid #ddd; margin: 25px 0; }
+    .footer { text-align: center; color: #666; font-size: 9pt; margin-top: 30px; padding-top: 15px; border-top: 1px solid #ddd; }
+    .toc { background: #fafafa; padding: 15px; border-radius: 5px; margin: 15px 0; columns: 2; }
+    .toc ul { margin: 0; padding-left: 20px; }
+    .toc li { margin: 4px 0; font-size: 10pt; }
+    .arch-diagram { background: #f5f5f5; padding: 15px; border-radius: 5px; font-family: 'Consolas', monospace; white-space: pre; font-size: 9pt; overflow-x: auto; line-height: 1.3; }
+    .module-box { border: 1px solid #ddd; border-radius: 6px; padding: 12px; margin: 12px 0; background: #fafafa; page-break-inside: avoid; }
+    .module-box h4 { margin: 0 0 8px 0; color: #1a1a2e; border-bottom: 1px solid #eee; padding-bottom: 5px; }
+    .port { display: inline-block; background: #e3f2fd; padding: 2px 8px; border-radius: 3px; font-family: monospace; font-size: 9pt; margin-right: 5px; }
+    .tech { display: inline-block; background: #f3e5f5; padding: 2px 8px; border-radius: 3px; font-size: 9pt; margin-right: 5px; }
+    .endpoint { font-family: monospace; background: #e8f5e9; padding: 2px 6px; border-radius: 3px; }
+    .two-col { display: flex; gap: 20px; }
+    .two-col > div { flex: 1; }
+    .screenshot { text-align: center; margin: 15px 0; }
+    .screenshot img { max-width: 100%; border: 1px solid #ddd; border-radius: 5px; }
+  </style>
+</head>
+<body>
+
+<div class="header">
+  <h1>StockEx Trading Platform</h1>
+  <p class="subtitle">Developer & Technical Guide</p>
+  <p class="version">Version 1.0 | Euronext OPTIQ Inspired</p>
+</div>
+
+<div class="toc">
+  <strong>Contents</strong>
+  <ul>
+    <li>1. Overview</li>
+    <li>2. Architecture</li>
+    <li>3. Modules</li>
+    <li>4. Database Persistence</li>
+    <li>5. Data Flow Diagrams</li>
+    <li>6. Kafka Topics</li>
+    <li>7. Message Formats</li>
+    <li>8. SSE Events</li>
+    <li>9. Configuration</li>
+    <li>10. Development</li>
+  </ul>
+</div>
+
+<hr>
+
+<div class="section">
+  <h2>1. Overview</h2>
+  <p><strong>StockEx</strong> is a real-time trading simulation platform providing complete order-to-trade lifecycle emulation. Built with microservices architecture using Docker containers.</p>
+
+  <div class="two-col">
+    <div class="highlight">
+      <strong>Core Features</strong>
+      <ul style="margin:5px 0; padding-left:20px;">
+        <li>FIX 4.4 protocol gateway</li>
+        <li>Price-time priority matching</li>
+        <li>Kafka event streaming</li>
+        <li>SSE real-time dashboard</li>
+        <li>SQLite persistence</li>
+      </ul>
+    </div>
+    <div class="info">
+      <strong>Tech Stack</strong>
+      <ul style="margin:5px 0; padding-left:20px;">
+        <li>Python 3.11 / Flask</li>
+        <li>QuickFIX/Python</li>
+        <li>Apache Kafka 7.5</li>
+        <li>Docker Compose</li>
+        <li>SQLite</li>
+      </ul>
+    </div>
+  </div>
+</div>
+
+<div class="section">
+  <h2>2. System Architecture</h2>
+  <div class="arch-diagram">
+┌───────���─────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  FIX UI Client  │     │  FIX UI Client  │     │    Frontend     │
+│    (Port 5002)  │     │    (Port 5003)  │     │   (Port 5000)   │
+└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
+         │ FIX 4.4               │ FIX 4.4               │ HTTP/JSON
+         └───────────────┬───────┴───────────────────────┘
+                         ▼
+         ┌───────────────────────────────┐
+         │     FIX OEG (Port 5001)       │
+         │   QuickFIX Order Gateway      │
+         └───────────────┬───────────────┘
+                         │ JSON
+                         ▼
+┌────────────────────────────────────────────────────────────────────┐
+│                    APACHE KAFKA (Port 9092)                        │
+│  ┌──────────┐      ┌──────────┐      ┌──────────┐                 │
+│  │  orders  │      │  trades  │      │ snapshots│                 │
+│  └──────────┘      └──────────┘      └──────────┘                 │
+└─────┬─────────────────┬─────────────────┬─────────────────────────┘
+      │                 │                 │
+      ▼                 │                 ▼
+┌─────────────┐         │         ┌─────────────┐
+│   Matcher   │─────────┘         │  MD Feeder  │
+│ (Port 6000) │                   │    (MDF)    │
+│             │                   │             │
+│ Order Book  │◄──────────────────│ Price Sim   │
+│ Trade Exec  │                   │ BBO Publish │
+└─────────────┘                   └─────────────┘
+      │
+      ▼ REST API
+┌─────────────────────────────────────────┐
+│         Dashboard (Port 5005)           │
+│  Orders │ Trades │ Book │ Chart │ Stats │
+└─────────────────────────────────────────┘
+  </div>
+</div>
+
+<div class="section">
+  <h2>3. Module Specifications</h2>
+
+  <div class="module-box">
+    <h4>Kafka Message Broker</h4>
+    <span class="port">9092</span> <span class="port">29092 (host)</span> <span class="tech">Confluent 7.5.0</span>
+    <p>Central event bus. All order flow distributed via topics. Zookeeper (port 2181) for coordination.</p>
+  </div>
+
+  <div class="module-box">
+    <h4>FIX Order Entry Gateway</h4>
+    <span class="port">5001</span> <span class="tech">QuickFIX/Python</span>
+    <p>FIX 4.4 acceptor. Receives NewOrderSingle (D), OrderCancelRequest (F), OrderCancelReplaceRequest (G). Normalizes to JSON → Kafka <code>orders</code>.</p>
+  </div>
+
+  <div class="module-box">
+    <h4>Matcher Engine</h4>
+    <span class="port">6000</span> <span class="tech">Python/Flask/SQLite</span>
+    <p>Consumes <code>orders</code>, matches with price-time priority, publishes <code>trades</code>. Maintains order book per symbol. SQLite persistence.</p>
+    <table>
+      <tr><th>Endpoint</th><th>Method</th><th>Description</th></tr>
+      <tr><td><span class="endpoint">/orderbook/&lt;symbol&gt;</span></td><td>GET</td><td>Order book depth</td></tr>
+      <tr><td><span class="endpoint">/trades</span></td><td>GET</td><td>Recent trades</td></tr>
+      <tr><td><span class="endpoint">/health</span></td><td>GET</td><td>Health + stats</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Market Data Feeder (MDF)</h4>
+    <span class="tech">Python</span>
+    <p>Simulates market activity. 90% passive orders (book building), 10% aggressive (trades). Publishes BBO snapshots.</p>
+    <p>Output: <code>orders</code> + <code>snapshots</code> topics</p>
+  </div>
+
+  <div class="module-box">
+    <h4>Dashboard</h4>
+    <span class="port">5005</span> <span class="tech">Flask/SSE/JavaScript</span>
+    <p>Real-time web UI. Consumes Kafka + Matcher API. Server-Sent Events for live streaming. Edit/Cancel order management.</p>
+    <table>
+      <tr><th>Endpoint</th><th>Method</th><th>Description</th></tr>
+      <tr><td><span class="endpoint">/stream</span></td><td>GET</td><td>SSE event stream</td></tr>
+      <tr><td><span class="endpoint">/data</span></td><td>GET</td><td>Polling fallback</td></tr>
+      <tr><td><span class="endpoint">/order/cancel</span></td><td>POST</td><td>Cancel order</td></tr>
+      <tr><td><span class="endpoint">/order/amend</span></td><td>POST</td><td>Amend order</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>FIX UI Clients</h4>
+    <span class="port">5002</span> <span class="port">5003</span> <span class="tech">QuickFIX/Flask</span>
+    <p>Web-based FIX initiators. Connect to FIX OEG for institutional order submission.</p>
+  </div>
+</div>
+
+<div class="section">
+  <h2>4. Database Persistence</h2>
+
+  <div class="info">
+    <strong>Storage:</strong> SQLite database at <code>/app/data/matcher.db</code><br>
+    <strong>Docker Volume:</strong> <code>stockex_matcher_data</code> (survives container restarts)
+  </div>
+
+  <h4>4.1 Database Schema</h4>
+
+  <div class="module-box">
+    <h4>order_book — All Orders</h4>
+    <table>
+      <tr><th>Column</th><th>Type</th><th>Description</th></tr>
+      <tr><td><code>id</code></td><td>INTEGER</td><td>Auto-increment primary key</td></tr>
+      <tr><td><code>cl_ord_id</code></td><td>TEXT</td><td>Unique client order ID</td></tr>
+      <tr><td><code>symbol</code></td><td>TEXT</td><td>Security (ALPHA, EXAE, etc.)</td></tr>
+      <tr><td><code>side</code></td><td>TEXT</td><td>BUY / SELL</td></tr>
+      <tr><td><code>price</code></td><td>REAL</td><td>Limit price</td></tr>
+      <tr><td><code>quantity</code></td><td>INTEGER</td><td>Original order quantity</td></tr>
+      <tr><td><code>remaining_qty</code></td><td>INTEGER</td><td>Unfilled quantity</td></tr>
+      <tr><td><code>status</code></td><td>TEXT</td><td>OPEN / FILLED / CANCELLED</td></tr>
+      <tr><td><code>timestamp</code></td><td>REAL</td><td>Order entry time (Unix)</td></tr>
+      <tr><td><code>created_at</code></td><td>DATETIME</td><td>DB insert timestamp</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>trades — Executed Trades</h4>
+    <table>
+      <tr><th>Column</th><th>Type</th><th>Description</th></tr>
+      <tr><td><code>id</code></td><td>INTEGER</td><td>Auto-increment primary key</td></tr>
+      <tr><td><code>symbol</code></td><td>TEXT</td><td>Traded security</td></tr>
+      <tr><td><code>price</code></td><td>REAL</td><td>Execution price</td></tr>
+      <tr><td><code>quantity</code></td><td>INTEGER</td><td>Traded quantity</td></tr>
+      <tr><td><code>buy_order_id</code></td><td>TEXT</td><td>Buyer's cl_ord_id</td></tr>
+      <tr><td><code>sell_order_id</code></td><td>TEXT</td><td>Seller's cl_ord_id</td></tr>
+      <tr><td><code>timestamp</code></td><td>REAL</td><td>Trade time (Unix)</td></tr>
+      <tr><td><code>created_at</code></td><td>DATETIME</td><td>DB insert timestamp</td></tr>
+    </table>
+  </div>
+
+  <h4>4.2 Database Functions</h4>
+  <table>
+    <tr><th>Function</th><th>Description</th></tr>
+    <tr><td><code>save_order(order)</code></td><td>Insert new order into order_book</td></tr>
+    <tr><td><code>update_order_quantity(id, qty)</code></td><td>Update remaining_qty after partial fill</td></tr>
+    <tr><td><code>cancel_order(cl_ord_id)</code></td><td>Set status = 'CANCELLED'</td></tr>
+    <tr><td><code>save_trade(trade)</code></td><td>Insert executed trade</td></tr>
+    <tr><td><code>get_open_orders(symbol, side)</code></td><td>Query open orders for matching</td></tr>
+    <tr><td><code>load_order_books()</code></td><td>Restore order books on startup</td></tr>
+    <tr><td><code>get_trades(symbol, limit)</code></td><td>Retrieve recent trades</td></tr>
+    <tr><td><code>delete_filled_orders(days)</code></td><td>Cleanup old filled/cancelled orders</td></tr>
+  </table>
+
+  <h4>4.3 Indexes</h4>
+  <div class="code-block">CREATE INDEX idx_trades_symbol ON trades(symbol);
+CREATE INDEX idx_trades_timestamp ON trades(timestamp);
+CREATE INDEX idx_orderbook_symbol_side ON order_book(symbol, side);
+CREATE INDEX idx_orderbook_status ON order_book(status);
+CREATE INDEX idx_orderbook_cl_ord_id ON order_book(cl_ord_id);</div>
+</div>
+
+<div class="section">
+  <h2>5. Data Flow Diagrams</h2>
+
+  <h4>4.1 Order Entry Flow</h4>
+  <div class="arch-diagram">
+   ┌──────────────┐
+   │  FIX Client  │
+   └──────┬───────┘
+          │ FIX 4.4 NewOrderSingle (35=D)
+          ▼
+   ┌──────────────┐
+   │   FIX OEG    │  Validate → Normalize → Generate cl_ord_id
+   └──────┬───────┘
+          │ JSON
+          ▼
+   ┌──────────────┐
+   │    Kafka     │  Topic: orders
+   │   [orders]   │
+   └──────┬───────┘
+          │
+    ┌─────┴─────┐
+    ▼           ▼
+┌────────┐  ┌���──────────┐
+│Matcher │  │ Dashboard │
+└────────┘  └───────────┘
+  </div>
+
+  <h4>4.2 Order Matching Flow</h4>
+  <div class="arch-diagram">
+                    ┌─────────────────┐
+                    │  Incoming Order │
+                    │   (from Kafka)  │
+                    └────────┬────────┘
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │  Parse & Validate│
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              ▼                             ▼
+       ┌────────────┐                ┌────────────┐
+       │  BUY Order │                │ SELL Order │
+       └──────┬─────┘                └──────┬─────┘
+              │                             │
+              ▼                             ▼
+    ┌──────────────────┐         ┌──────────────────┐
+    │ Check SELL book  │         │ Check BUY book   │
+    │ for price ≤ bid  │         │ for price ≥ ask  │
+    └────────┬─────────┘         └────────┬─────────┘
+             │                            │
+      ┌──────┴──────┐              ┌──────┴──────┐
+      ▼             ▼              ▼             ▼
+  ┌───────┐    ┌────────┐     ┌───────┐    ┌────────┐
+  │ Match │    │No Match│     │ Match │    │No Match│
+  │ Found │    │        │     │ Found │    │        │
+  └───┬───┘    └───┬────┘     └───┬───┘    └───┬────┘
+      │            │              │            │
+      ▼            ▼              ▼            ▼
+  ┌───────┐    ┌────────┐     ┌───────┐    ┌────────┐
+  │Execute│    │Add to  │     │Execute│    │Add to  │
+  │ Trade │    │BUY Book│     │ Trade │    │SELLBook│
+  └───┬───┘    └────────┘     └───┬───┘    └────────┘
+      │                           │
+      └───────────┬───────────────┘
+                  ▼
+           ┌────────────┐
+           │Kafka:trades│
+           └────────────┘
+  </div>
+
+  <h4>4.3 Real-time Dashboard Flow</h4>
+  <div class="arch-diagram">
+┌─────────────────────────────────────────────────────────────────┐
+│                         BROWSER                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                    Dashboard UI                          │   │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│   │
+│  │  │ Orders  │ │ Trades  │ │  Book   │ │    Statistics   ││   │
+│  │  └────▲────┘ └────▲────┘ └────▲────┘ └────────▲────────┘│   │
+│  └───────┼───────────┼───────────┼───────────────┼──────────┘   │
+│          │           │           │               │              │
+│          └───────────┴─────┬─────┴───────────────┘              │
+│                            │                                    │
+│                    ┌───────▼────────┐                          │
+│                    │ EventSource    │  SSE Connection          │
+│                    │ /stream        │                          │
+│                    └───────┬────────┘                          │
+└─���──────────────────────────┼────────────────────────────────────┘
+                             │ HTTP (SSE)
+                             ▼
+┌────────────────────────────────────────────────────────────────┐
+│                      DASHBOARD SERVER                          │
+│                                                                │
+│   ┌──────────────┐      ┌──────────────┐     ┌────────────┐   │
+│   │Kafka Consumer│─────▶│ SSE Broadcast│────▶│  Clients   │   │
+│   │ (orders,     │      │   Queue      │     │  Queue[]   │   │
+│   │  trades,     │      └──────────────┘     └────────────┘   │
+│   │  snapshots)  │                                            │
+│   └──────────────┘                                            │
+│                                                                │
+│   ┌──────────────┐      ┌──────────────┐                      │
+│   │  REST API    │◀────▶│   Matcher    │  /orderbook, /trades │
+│   │  /data       │      │   Proxy      │                      │
+│   └──────────────┘      └──────────────┘                      │
+└────────────────────────────────────────────────────────────────┘
+  </div>
+
+  <h4>4.4 Complete System Interaction</h4>
+  <div class="arch-diagram">
+          ┌─────────┐ ┌─────────┐ ┌─────────┐
+          │FIX Cli 1│ │FIX Cli 2│ │Frontend │
+          └────┬────┘ └────┬────┘ └────┬────┘
+               │           │           │
+               └─────┬─────┴───────────┘
+                     │
+                     ▼
+              ┌─────────────┐
+              │   FIX OEG   │◄──── FIX 4.4 Protocol
+              └──────┬──────┘
+                     │
+                     ▼
+    ┌────────────────────────────────────┐
+    │            KAFKA CLUSTER           │
+    │  ┌────────┐┌────────┐┌──────────┐ │
+    │  │orders  ││trades  ││snapshots │ │
+    │  └───┬────┘└───▲────┘└────▲─────┘ │
+    └──────┼─────────┼──────────┼───────┘
+           │         │          │
+     ┌─────┼─────────┼──────────┼─────┐
+     │     ▼         │          │     │
+     │ ┌────────┐    │          │     │
+     │ │MATCHER │────┘          │     │
+     │ │        │               │     │
+     │ │ Book   │               │     │
+     │ │ Match  │               │     │
+     │ │ Trade  │               │     │
+     │ └────────┘               │     │
+     │     ▲                    │     │
+     │     │ REST               │     │
+     │     │                    │     │
+     │ ┌───┴────────────────────┴──┐  │
+     │ │        DASHBOARD          │  │
+     │ │   (SSE + Kafka Consumer)  │  │
+     │ └───────────────────────────┘  │
+     │                                │
+     │ ┌───────────────────────────┐  │
+     │ │      MD FEEDER (MDF)      │──┘
+     │ │   Orders + Snapshots      │
+     │ └───────────────────────────┘
+     │              DOCKER NETWORK
+     └────────────────────────────────┘
+  </div>
+
+  <h4>4.5 Message Sequence: New Order to Trade</h4>
+  <div class="arch-diagram">
+FIX Client    FIX OEG      Kafka       Matcher     Dashboard
+    │            │           │            │            │
+    │──35=D────▶│            │            │            │
+    │NewOrder   │            │            │            │
+    │           │──JSON────▶│            │            │
+    │           │  [orders] │            │            │
+    │           │           │──consume──▶│            │
+    │           │           │            │            │
+    │           │           │            │──match()   │
+    │           │           │            │            │
+    │           │           │◀──trade────│            │
+    │           │           │  [trades]  │            │
+    │           │           │            │            │
+    │           │           │──────────────consume───▶│
+    │           │           │            │            │
+    │           │           │            │     render()
+    │           │           │            │            │
+  </div>
+</div>
+
+<div class="section">
+  <h2>6. Kafka Topics</h2>
+  <table>
+    <tr><th>Topic</th><th>Producers</th><th>Consumers</th><th>Content</th></tr>
+    <tr><td><code>orders</code></td><td>FIX OEG, MDF, Frontend</td><td>Matcher, Dashboard</td><td>New/Cancel/Amend orders</td></tr>
+    <tr><td><code>trades</code></td><td>Matcher</td><td>Dashboard, Consumer</td><td>Executed trades</td></tr>
+    <tr><td><code>snapshots</code></td><td>MDF</td><td>Dashboard</td><td>BBO updates</td></tr>
+  </table>
+</div>
+
+<div class="section">
+  <h2>7. Message Formats</h2>
+
+  <h4>Order (New)</h4>
+  <div class="code-block json">{
+  "symbol": "ALPHA",
+  "side": "BUY",
+  "price": 25.50,
+  "quantity": 100,
+  "cl_ord_id": "MDF-1234567890-1",
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}</div>
+
+  <h4>Order (Cancel)</h4>
+  <div class="code-block json">{
+  "type": "cancel",
+  "orig_cl_ord_id": "MDF-1234567890-1",
+  "symbol": "ALPHA",
+  "timestamp": 1234567890.456
+}</div>
+
+  <h4>Order (Amend)</h4>
+  <div class="code-block json">{
+  "type": "amend",
+  "orig_cl_ord_id": "MDF-1234567890-1",
+  "cl_ord_id": "amend-1234567890",
+  "symbol": "ALPHA",
+  "quantity": 150,
+  "price": 25.45,
+  "timestamp": 1234567890.789
+}</div>
+
+  <h4>Trade</h4>
+  <div class="code-block json">{
+  "symbol": "ALPHA",
+  "price": 25.50,
+  "quantity": 100,
+  "buy_order_id": "order-123",
+  "sell_order_id": "order-456",
+  "timestamp": 1234567890.123
+}</div>
+
+  <h4>Snapshot (BBO)</h4>
+  <div class="code-block json">{
+  "symbol": "ALPHA",
+  "best_bid": 25.45,
+  "best_ask": 25.55,
+  "bid_size": 500,
+  "ask_size": 300,
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}</div>
+</div>
+
+<div class="section">
+  <h2>8. SSE Events</h2>
+  <table>
+    <tr><th>Event</th><th>Data</th><th>Trigger</th></tr>
+    <tr><td><code>connected</code></td><td>{status}</td><td>Client connects</td></tr>
+    <tr><td><code>init</code></td><td>{orders, bbos, trades}</td><td>Initial state dump</td></tr>
+    <tr><td><code>order</code></td><td>Order JSON</td><td>New order received</td></tr>
+    <tr><td><code>trade</code></td><td>Trade JSON</td><td>Trade executed</td></tr>
+    <tr><td><code>snapshot</code></td><td>BBO JSON</td><td>Price update</td></tr>
+  </table>
+</div>
+
+<div class="section">
+  <h2>9. Configuration</h2>
+  <table>
+    <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+    <tr><td><code>KAFKA_BOOTSTRAP</code></td><td>kafka:9092</td><td>Broker address</td></tr>
+    <tr><td><code>MATCHER_URL</code></td><td>http://matcher:6000</td><td>Matcher API</td></tr>
+    <tr><td><code>TICK_SIZE</code></td><td>0.05</td><td>Min price increment</td></tr>
+    <tr><td><code>ORDERS_PER_MIN</code></td><td>8</td><td>MDF rate</td></tr>
+    <tr><td><code>KAFKA_RETRIES</code></td><td>30</td><td>Connection retries</td></tr>
+  </table>
+
+  <h4>Securities (shared_data/securities.txt)</h4>
+  <div class="code-block">#SYMBOL  start_price  current_price
+ALPHA    25.00        25.00
+EXAE     42.00        42.00
+PEIR     18.50        18.50
+QUEST    12.75        12.75</div>
+</div>
+
+<div class="section">
+  <h2>10. Development Commands</h2>
+
+  <h4>Build & Run</h4>
+  <div class="code-block">docker compose up --build        # Start all
+docker compose up -d --build     # Background
+docker compose logs -f dashboard # Follow logs
+docker compose down              # Stop all</div>
+
+  <h4>Reset Data</h4>
+  <div class="code-block">docker compose down
+docker volume rm stockex_matcher_data
+docker compose up -d</div>
+
+  <h4>Container Access</h4>
+  <div class="code-block">docker exec -it matcher bash
+docker exec -it dashboard bash
+docker logs matcher --tail 50</div>
+
+  <h4>API Testing</h4>
+  <div class="code-block">curl http://localhost:6000/orderbook/ALPHA
+curl http://localhost:6000/trades
+curl http://localhost:5005/data</div>
+</div>
+
+<div class="screenshot">
+  <img src="screenshots/dashboard.png" alt="StockEx Dashboard">
+  <p style="font-size:10pt; color:#666;"><em>StockEx Trading Dashboard - Real-time Market View</em></p>
+</div>
+
+<hr>
+
+<div class="footer">
+  <strong>StockEx Trading Platform v1.0</strong><br>
+  Developer Guide | Euronext OPTIQ Inspired<br>
+  <p style="margin-top:10px;">Print to PDF: Ctrl+P → Save as PDF</p>
+</div>
+
+</body>
+</html>

StockEx_Technical_Guide.md

@@ -0,0 +1,814 @@
+# StockEx Trading Platform
+## Complete Technical & Developer Guide v1.0
+
+---
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)
+2. [System Architecture](#2-system-architecture)
+3. [Module Descriptions](#3-module-descriptions)
+4. [Dashboard User Interface](#4-dashboard-user-interface)
+5. [Data Flow & Messaging](#5-data-flow--messaging)
+6. [Configuration](#6-configuration)
+7. [Quick Reference](#7-quick-reference)
+8. [Troubleshooting](#8-troubleshooting)
+
+---
+
+## 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 via FIX protocol, order matching engine, market data distribution, and live visualization through a web dashboard.
+
+### Key Features
+
+- **FIX 4.4 Protocol Support** — Institutional-grade order entry via QuickFIX
+- **Real-time Order Matching** — Price-time priority matching engine with SQLite persistence
+- **Live Market Data Streaming** — Kafka-based event distribution
+- **Web Dashboard with SSE** — Real-time updates without page refresh
+- **Order Management** — Edit and Cancel capabilities from the UI
+- **Trading Analytics** — Volume, Value, VWAP statistics with visualizations
+
+### Access 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 for order book/trades |
+
+---
+
+## 2. System Architecture
+
+### High-Level Architecture Diagram
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  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     │
+└───────────────┘    └───────────────┘      └───────────────┘
+```
+
+### Component Summary
+
+| Component | Technology | Port | Function |
+|-----------|------------|------|----------|
+| Zookeeper | Confluent 7.5.0 | 2181 | Kafka coordination |
+| Kafka | Confluent 7.5.0 | 9092, 29092 | Message streaming |
+| FIX OEG | QuickFIX/Python | 5001 | FIX protocol gateway |
+| Matcher | Python/Flask/SQLite | 6000 | Order matching engine |
+| MDF | Python | - | Market data simulation |
+| Dashboard | Flask/SSE | 5005 | Real-time web UI |
+| Frontend | Flask | 5000 | Manual order entry |
+| FIX Clients | QuickFIX/Flask | 5002, 5003 | FIX order UI |
+
+---
+
+## 3. Module Descriptions
+
+### 3.1 Zookeeper
+
+**Port:** 2181
+
+Apache Zookeeper provides distributed coordination for the Kafka cluster. It manages broker metadata, topic configurations, and cluster membership.
+
+- **Image:** confluentinc/cp-zookeeper:7.5.0
+- **Dependencies:** None
+- **Environment:** `ZOOKEEPER_CLIENT_PORT=2181`
+
+---
+
+### 3.2 Apache Kafka
+
+**Ports:** 9092 (internal), 29092 (host access)
+
+Apache Kafka serves as the central message backbone for the entire trading system. All order flow, trade executions, and market data are distributed through Kafka topics.
+
+- **Image:** confluentinc/cp-kafka:7.5.0
+- **Dependencies:** Zookeeper
+
+**Topics:**
+
+| Topic | Purpose | Producers | Consumers |
+|-------|---------|-----------|-----------|
+| `orders` | Order flow | FIX OEG, MDF, Frontend | Matcher, Dashboard |
+| `trades` | Executed trades | Matcher | Dashboard, Consumer |
+| `snapshots` | BBO updates | MDF | Dashboard, Snapshot Viewer |
+
+---
+
+### 3.3 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 FIX messages, normalizes them to JSON format, and publishes to the Kafka `orders` topic.
+
+**Supported FIX Messages:**
+
+| Message Type | Tag 35 | Description |
+|--------------|--------|-------------|
+| NewOrderSingle | D | New order submission |
+| OrderCancelRequest | F | Cancel existing order |
+| OrderCancelReplaceRequest | G | Modify existing order |
+
+**Key Functions:**
+- FIX session management (logon, heartbeat, logout)
+- Message validation and normalization
+- Order ID generation
+- Kafka publishing
+
+---
+
+### 3.4 FIX UI Clients
+
+**Ports:** 5002 (Client 1), 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.
+
+**Features:**
+- New Order Single submission
+- Order cancellation
+- Order amendment
+- Real-time execution reports
+
+**Configuration Files:**
+- `client1.cfg` — FIX session config for Client 1
+- `client2.cfg` — FIX session config for Client 2
+
+---
+
+### 3.5 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.
+
+**Matching Algorithm:** Price-Time Priority (FIFO)
+- Buy orders sorted by price descending (highest first)
+- Sell orders sorted by price ascending (lowest first)
+- Within same price level, earlier orders have priority
+
+**Persistence:** SQLite database (`/app/data/matcher.db`)
+- Order book survives container restarts
+- Volume-mapped for data durability
+
+**REST API Endpoints:**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/orderbook/<symbol>` | GET | Get order book depth for symbol |
+| `/trades` | GET | Get recent trades |
+| `/health` | GET | Health check with statistics |
+
+**Order Book Response Example:**
+```json
+{
+  "symbol": "ALPHA",
+  "bids": [
+    {"price": 25.45, "quantity": 100, "cl_ord_id": "MDF-123"},
+    {"price": 25.40, "quantity": 200, "cl_ord_id": "MDF-124"}
+  ],
+  "asks": [
+    {"price": 25.55, "quantity": 150, "cl_ord_id": "MDF-125"},
+    {"price": 25.60, "quantity": 100, "cl_ord_id": "MDF-126"}
+  ]
+}
+```
+
+---
+
+### 3.6 Market Data Feeder (MDF)
+
+**Port:** Internal only
+
+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.
+
+**Order Generation:**
+- **90% Passive Orders** — Placed away from mid price to build order book
+- **10% Aggressive Orders** — Cross the spread to generate trades
+
+**Price Simulation:**
+- Small random drift (±2 ticks) with 10% probability
+- Prices bounded by minimum (1.00)
+- Half spread: 0.10 (10 cents)
+
+**Output:**
+- Orders → Kafka `orders` topic
+- Snapshots → Kafka `snapshots` topic
+
+**Configuration:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORDERS_PER_MIN` | 8 | Order generation rate |
+| `TICK_SIZE` | 0.05 | Minimum price increment |
+
+---
+
+### 3.7 Dashboard
+
+**Port:** 5005
+
+Real-time web dashboard providing comprehensive market visualization. Uses Server-Sent Events (SSE) for live streaming updates without page refresh.
+
+**Technology Stack:**
+- Backend: Python/Flask
+- Frontend: HTML5/CSS3/JavaScript
+- Streaming: Server-Sent Events (SSE)
+- Data: Kafka consumer + REST API calls to Matcher
+
+**Features:**
+
+| Panel | Description |
+|-------|-------------|
+| Orders | Live order feed with Edit/Cancel actions |
+| Market Snapshot | BBO table with scrolling ticker tape |
+| Trades | Executed trades with value calculation |
+| Order Book | Depth of book per symbol |
+| Trade Chart | Price line + volume bars visualization |
+| Trading Statistics | Aggregated metrics with bar charts |
+
+**SSE Events:**
+
+| Event | Data | Trigger |
+|-------|------|---------|
+| `connected` | Status | Initial connection |
+| `init` | Full state | On connect |
+| `order` | Order JSON | New order received |
+| `trade` | Trade JSON | Trade executed |
+| `snapshot` | BBO JSON | Price update |
+
+---
+
+### 3.8 Frontend (Manual Order Entry)
+
+**Port:** 5000
+
+Simple web interface for manual order submission. Allows users to enter orders directly without FIX protocol.
+
+**Features:**
+- Symbol selection dropdown
+- Side selection (BUY/SELL)
+- Price and quantity input
+- Submit order to Kafka
+
+---
+
+### 3.9 Consumer (Debug Utility)
+
+**Port:** Internal only
+
+Debug utility that consumes and logs messages from Kafka `trades` topic. Outputs trade information to console for monitoring.
+
+**Output Format:**
+```
+TRADE: ALPHA - 100 @ 25.50
+TRADE: EXAE - 50 @ 42.10
+```
+
+---
+
+### 3.10 Snapshot Viewer
+
+**Port:** Internal only
+
+Utility service that subscribes to the `snapshots` topic and logs BBO updates. Writes to log files in `/app/logs` 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 |
+
+**Order Actions:**
+- **Edit** — Opens modal to modify quantity and/or price (sends amend to Kafka)
+- **Cancel** — Sends cancel request to Kafka
+- **Row Selection** — Click row to select, use header buttons for 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 shows recent trades
+- ▲ Green: Price up from previous
+- ▼ Red: Price down from previous
+- ● Yellow: No change
+- Hover to pause scrolling
+
+---
+
+### 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.
+
+**Controls:**
+- **Symbol Dropdown** — Select security to view
+- **Refresh Button** — Manual refresh (auto-refreshes every 3 seconds)
+
+**Display:**
+- **Left Side:** Bid Qty | Bid Price (green, sorted price descending)
+- **Right Side:** Ask Price | Ask Qty (red, sorted price ascending)
+- **Header:** Shows count of bids and asks
+
+---
+
+### 4.5 Trade Chart
+
+Visual representation of trade activity over time.
+
+**Elements:**
+- **Green Line** — Price trend connecting trade execution prices
+- **Blue Bars** — Volume per trade
+- **Y-Axis** — Price scale
+- **X-Axis** — Trade sequence (last 100 trades)
+
+**Controls:**
+- Symbol dropdown to filter by security or view all
+
+---
+
+### 4.6 Trading Statistics
+
+Aggregated metrics calculated from all trades.
+
+| Metric | Description | Formula |
+|--------|-------------|---------|
+| Trades | Count of executed trades | COUNT(*) |
+| Volume | Total shares traded | Σ Quantity |
+| Value | Total monetary value | Σ (Qty × Price) |
+| Start | First trade price | First price in session |
+| Last | Most recent price | Latest price |
+| VWAP | Volume-Weighted Average Price | Σ(Qty × Price) / Σ Qty |
+
+**Bar Charts:**
+- Grouped by symbol showing Volume (green) and Value (blue) side by side
+- Normalized to maximum value in dataset
+
+---
+
+## 5. Data Flow & Messaging
+
+### 5.1 Order Entry Flow
+
+```
+   ┌──────────────┐
+   │  FIX Client  │
+   └──────┬───────┘
+          │ FIX 4.4 NewOrderSingle (35=D)
+          ▼
+   ┌──────────────┐
+   │   FIX OEG    │  Validate → Normalize → Generate cl_ord_id
+   └──────┬───────┘
+          │ JSON
+          ▼
+   ┌──────────────┐
+   │    Kafka     │  Topic: orders
+   │   [orders]   │
+   └──────┬───────┘
+          │
+    ┌─────┴─────┐
+    ▼           ▼
+┌────────┐  ┌───────────┐
+│Matcher │  │ Dashboard │
+└────────┘  └───────────┘
+```
+
+### 5.2 Order Matching Flow
+
+```
+                    ┌─────────────────┐
+                    │  Incoming Order │
+                    │   (from Kafka)  │
+                    └────────┬────────┘
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │  Parse & Validate│
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              ▼                             ▼
+       ┌────────────┐                ┌────────────┐
+       │  BUY Order │                │ SELL Order │
+       └──────┬─────┘                └──────┬─────┘
+              │                             │
+              ▼                             ▼
+    ┌──────────────────┐         ┌──────────────────┐
+    │ Check SELL book  │         │ Check BUY book   │
+    │ for price ≤ bid  │         │ for price ≥ ask  │
+    └────────┬─────────┘         └────────┬─────────┘
+             │                            │
+      ┌──────┴──────┐              ┌──────┴──────┐
+      ▼             ▼              ▼             ▼
+  ┌───────┐    ┌────────┐     ┌───────┐    ┌────────┐
+  │ Match │    │No Match│     │ Match │    │No Match│
+  │ Found │    │        │     │ Found │    │        │
+  └───┬───┘    └───┬────┘     └───┬───┘    └───┬────┘
+      │            │              │            │
+      ▼            ▼              ▼            ▼
+  ┌───────┐    ┌────────┐     ┌───────┐    ┌────────┐
+  │Execute│    │Add to  │     │Execute│    │Add to  │
+  │ Trade │    │BUY Book│     │ Trade │    │SELLBook│
+  └───┬───┘    └────────┘     └───┬───┘    └────────┘
+      │                           │
+      └───────────┬───────────────┘
+                  ▼
+           ┌────────────┐
+           │Kafka:trades│
+           └────────────┘
+```
+
+### 5.3 Real-time Dashboard Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         BROWSER                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                    Dashboard UI                          │   │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│   │
+│  │  │ Orders  │ │ Trades  │ │  Book   │ │    Statistics   ││   │
+│  │  └────▲────┘ └────▲────┘ └────▲────┘ └────────▲────────┘│   │
+│  └───────┼───────────┼───────────┼───────────────┼──────────┘   │
+│          └───────────┴─────┬─────┴───────────────┘              │
+│                    ┌───────▼────────┐                          │
+│                    │ EventSource    │  SSE Connection          │
+│                    │ /stream        │                          │
+│                    └───────┬────────┘                          │
+└────────────────────────────┼────────────────────────────────────┘
+                             │ HTTP (SSE)
+                             ▼
+┌────────────────────────────────────────────────────────────────┐
+│                      DASHBOARD SERVER                          ��
+│   ┌──────────────┐      ┌──────────────┐     ┌────────────┐   │
+│   │Kafka Consumer│─────▶│ SSE Broadcast│────▶│  Clients   │   │
+│   │ (orders,     │      │   Queue      │     │  Queue[]   │   │
+│   │  trades,     │      └──────────────┘     └────────────┘   │
+│   │  snapshots)  │                                            │
+│   └──────────────┘                                            │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### 5.4 Complete System Interaction
+
+```
+          ┌─────────┐ ┌─────────┐ ┌─────────┐
+          │FIX Cli 1│ │FIX Cli 2│ │Frontend │
+          └────┬────┘ └────┬────┘ └────┬────┘
+               └─────┬─────┴───────────┘
+                     ▼
+              ┌─────────────┐
+              │   FIX OEG   │◄──── FIX 4.4 Protocol
+              └──────┬──────┘
+                     ▼
+    ┌────────────────────────────────────┐
+    │            KAFKA CLUSTER           │
+    │  ┌────────┐┌────────┐┌──────────┐ │
+    │  │orders  ││trades  ││snapshots │ │
+    │  └───┬────┘└───▲────┘└────▲─────┘ │
+    └──────┼─────────┼──────────┼───────┘
+           │         │          │
+     ┌─────┼─────────┼──────────┼─────┐
+     │     ▼         │          │     │
+     │ ┌────────┐    │          │     │
+     │ │MATCHER │────┘          │     │
+     │ │ Book   │               │     │
+     │ │ Match  │               │     │
+     │ └────────┘               │     │
+     │     ▲                    │     │
+     │     │ REST               │     │
+     │ ┌───┴────────────────────┴──┐  │
+     │ │        DASHBOARD          │  │
+     │ │   (SSE + Kafka Consumer)  │  │
+     │ └───────────────────────────┘  │
+     │ ┌───────────────────────────┐  │
+     │ │      MD FEEDER (MDF)      │──┘
+     │ │   Orders + Snapshots      │
+     │ └───────────────────────────┘
+     └────────────────────────────────┘
+```
+
+### 5.5 Message Sequence: New Order to Trade
+
+```
+FIX Client    FIX OEG      Kafka       Matcher     Dashboard
+    │            │           │            │            │
+    │──35=D────▶│            │            │            │
+    │NewOrder   │            │            │            │
+    │           │──JSON────▶│            │            │
+    │           │  [orders] │            │            │
+    │           │           │──consume──▶│            │
+    │           │           │            │──match()   │
+    │           │           │◀──trade────│            │
+    │           │           │  [trades]  │            │
+    │           │           │──────────────consume───▶│
+    │           │           │            │     render()
+```
+
+---
+
+### 5.6 Message Formats
+
+**Order Message:**
+```json
+{
+  "symbol": "ALPHA",
+  "side": "BUY",
+  "price": 25.50,
+  "quantity": 100,
+  "cl_ord_id": "MDF-1234567890-1",
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}
+```
+
+**Cancel Message:**
+```json
+{
+  "type": "cancel",
+  "orig_cl_ord_id": "MDF-1234567890-1",
+  "symbol": "ALPHA",
+  "timestamp": 1234567890.456
+}
+```
+
+**Amend Message:**
+```json
+{
+  "type": "amend",
+  "orig_cl_ord_id": "MDF-1234567890-1",
+  "cl_ord_id": "amend-1234567890",
+  "symbol": "ALPHA",
+  "quantity": 150,
+  "price": 25.45,
+  "timestamp": 1234567890.789
+}
+```
+
+**Trade Message:**
+```json
+{
+  "symbol": "ALPHA",
+  "price": 25.50,
+  "quantity": 100,
+  "buy_order_id": "order-123",
+  "sell_order_id": "order-456",
+  "timestamp": 1234567890.123
+}
+```
+
+**Snapshot Message:**
+```json
+{
+  "symbol": "ALPHA",
+  "best_bid": 25.45,
+  "best_ask": 25.55,
+  "bid_size": 500,
+  "ask_size": 300,
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}
+```
+
+---
+
+## 6. Configuration
+
+### 6.1 Environment Variables
+
+| 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 |
+| `KAFKA_RETRIES` | 30 | Connection retry attempts |
+| `KAFKA_RETRY_DELAY` | 2 | Seconds between retries |
+
+### 6.2 Securities Configuration
+
+File: `shared_data/securities.txt`
+
+```
+#SYMBOL	<start_price>	<current_price>
+ALPHA	25.00	25.00
+PEIR	18.50	18.50
+EXAE	42.00	42.00
+QUEST	12.75	12.75
+```
+
+| 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 |
+
+### 6.3 Docker Volumes
+
+| Volume | Path | Purpose |
+|--------|------|---------|
+| `matcher_data` | /app/data | SQLite database persistence |
+| `shared_data` | /app/data | Securities and order ID files |
+| `logs` | /app/logs | Snapshot viewer logs |
+
+---
+
+## 7. Quick Reference
+
+### 7.1 Starting the System
+
+```bash
+# Start all services
+docker compose up --build
+
+# Start in background
+docker compose up -d --build
+
+# View logs
+docker compose logs -f dashboard
+docker compose logs -f matcher
+
+# Stop all services
+docker compose down
+
+# Reset matcher database
+docker volume rm stockex_matcher_data
+```
+
+### 7.2 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 order row | Click on the row |
+| Bulk actions | Select row, use header Edit/Cancel buttons |
+
+### 7.3 Connection Status
+
+| Status | Indicator | Meaning |
+|--------|-----------|---------|
+| Live | ● Green | Connected to SSE stream |
+| Connecting | ● Yellow | Establishing connection |
+| Disconnected | ● Red | Connection lost, auto-reconnecting |
+
+### 7.4 API Endpoints
+
+**Matcher API (Port 6000):**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/orderbook/<symbol>` | GET | Order book for symbol |
+| `/trades` | GET | Recent trades list |
+| `/health` | GET | Service health status |
+
+**Dashboard API (Port 5005):**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Main dashboard page |
+| `/data` | GET | Current state (polling fallback) |
+| `/stream` | GET | SSE event stream |
+| `/orderbook/<symbol>` | GET | Proxy to matcher |
+| `/order/cancel` | POST | Cancel order request |
+| `/order/amend` | POST | Amend order request |
+
+---
+
+## 8. Troubleshooting
+
+### Orders/Trades Panel Empty
+
+1. Check Kafka connection:
+   ```bash
+   docker logs dashboard | grep "Kafka"
+   ```
+2. Verify MDF is producing:
+   ```bash
+   docker logs stockex-md_feeder-1 --tail 10
+   ```
+3. Restart dashboard:
+   ```bash
+   docker restart dashboard
+   ```
+
+### Order Book Empty
+
+1. Check matcher is receiving orders:
+   ```bash
+   docker logs matcher | grep "received"
+   ```
+2. Verify matcher Kafka consumer connected:
+   ```bash
+   docker logs matcher | grep "consumer connected"
+   ```
+3. Reset matcher database if corrupted:
+   ```bash
+   docker compose down
+   docker volume rm stockex_matcher_data
+   docker compose up -d
+   ```
+
+### Connection Status Shows Disconnected
+
+1. SSE stream timeout — will auto-reconnect after 3 seconds
+2. Check dashboard container is running:
+   ```bash
+   docker ps | grep dashboard
+   ```
+3. Check browser console for errors (F12)
+
+### Prices Going Negative or Extreme
+
+1. Old bug in MDF — update to latest version
+2. Reset securities file:
+   ```
+   #SYMBOL	<start_price>	<current_price>
+   ALPHA	25.00	25.00
+   PEIR	18.50	18.50
+   EXAE	42.00	42.00
+   QUEST	12.75	12.75
+   ```
+3. Restart MDF and matcher:
+   ```bash
+   docker restart stockex-md_feeder-1 matcher
+   ```
+
+---
+
+## Document Information
+
+- **Version:** 1.0
+- **Platform:** StockEx Trading Simulation
+- **Inspired by:** Euronext OPTIQ
+
+---
+
+*StockEx v1.0 — Trading Simulation Platform*

StockEx_User_Guide.html

@@ -0,0 +1,428 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>StockEx User Guide</title>
+  <style>
+    @page { margin: 2cm; }
+    body { font-family: Arial, sans-serif; max-width: 900px; margin: 0 auto; padding: 20px; line-height: 1.6; color: #333; }
+    h1 { color: #1a1a2e; border-bottom: 3px solid #4CAF50; padding-bottom: 10px; }
+    h2 { color: #2e7d32; margin-top: 30px; border-bottom: 1px solid #ddd; padding-bottom: 5px; page-break-after: avoid; }
+    h3 { color: #1565c0; margin-top: 20px; }
+    h4 { color: #555; margin-top: 15px; }
+    table { width: 100%; border-collapse: collapse; margin: 15px 0; font-size: 14px; }
+    th, td { border: 1px solid #ddd; padding: 10px; text-align: left; }
+    th { background: #f5f5f5; font-weight: bold; }
+    .header { text-align: center; margin-bottom: 30px; }
+    .subtitle { color: #666; font-size: 18px; }
+    .section { page-break-inside: avoid; margin-bottom: 25px; }
+    .highlight { background: #e8f5e9; padding: 15px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #4CAF50; }
+    .info { background: #e3f2fd; padding: 15px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #2196F3; }
+    .warning { background: #fff3e0; padding: 15px; border-radius: 5px; margin: 10px 0; border-left: 4px solid #ff9800; }
+    .green { color: #2e7d32; }
+    .red { color: #c62828; }
+    .blue { color: #1565c0; }
+    .screenshot { text-align: center; margin: 20px 0; }
+    .screenshot img { max-width: 100%; border: 1px solid #ddd; border-radius: 5px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+    hr { border: none; border-top: 1px solid #ddd; margin: 30px 0; }
+    .footer { text-align: center; color: #666; font-size: 12px; margin-top: 40px; padding-top: 20px; border-top: 1px solid #ddd; }
+    .toc { background: #fafafa; padding: 20px; border-radius: 5px; margin: 20px 0; }
+    .toc ul { margin: 0; padding-left: 20px; }
+    .toc li { margin: 5px 0; }
+    .arch-diagram { background: #f5f5f5; padding: 20px; border-radius: 5px; font-family: monospace; white-space: pre; font-size: 12px; overflow-x: auto; }
+    code { background: #f5f5f5; padding: 2px 6px; border-radius: 3px; font-family: monospace; }
+    .module-box { border: 1px solid #ddd; border-radius: 8px; padding: 15px; margin: 15px 0; background: #fafafa; }
+    .module-box h4 { margin-top: 0; color: #1a1a2e; }
+    .port { display: inline-block; background: #e3f2fd; padding: 2px 8px; border-radius: 3px; font-family: monospace; font-size: 12px; }
+  </style>
+</head>
+<body>
+
+<div class="header">
+  <h1>StockEx Trading Dashboard</h1>
+  <p class="subtitle">Complete User & Technical Guide v1.0</p>
+</div>
+
+<div class="toc">
+  <strong>Table of Contents</strong>
+  <ul>
+    <li>1. Introduction</li>
+    <li>2. System Architecture</li>
+    <li>3. Module Descriptions</li>
+    <li>4. Dashboard User Interface</li>
+    <li>5. Data Flow & Messaging</li>
+    <li>6. Configuration</li>
+    <li>7. Quick Reference</li>
+  </ul>
+</div>
+
+<hr>
+
+<div class="section">
+  <h2>1. Introduction</h2>
+  <p><strong>StockEx</strong> 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.</p>
+
+  <div class="highlight">
+    <strong>Key Features:</strong>
+    <ul>
+      <li>FIX 4.4 protocol support for institutional order entry</li>
+      <li>Real-time order matching with price-time priority</li>
+      <li>Live market data streaming via Kafka</li>
+      <li>Web-based dashboard with Server-Sent Events (SSE)</li>
+      <li>Order management (Edit/Cancel) capabilities</li>
+      <li>Trading analytics and statistics</li>
+    </ul>
+  </div>
+
+  <div class="info">
+    <strong>Access URLs:</strong><br>
+    Dashboard: <code>http://localhost:5005</code><br>
+    Frontend (Order Entry): <code>http://localhost:5000</code><br>
+    FIX Gateway: <code>localhost:5001</code><br>
+    Matcher API: <code>http://localhost:6000</code>
+  </div>
+</div>
+
+<div class="screenshot">
+  <img src="screenshots/dashboard.png" alt="Trading Dashboard">
+  <p><em>StockEx Trading Dashboard - Real-time Market View</em></p>
+</div>
+
+<div class="section">
+  <h2>2. System Architecture</h2>
+
+  <div class="arch-diagram">
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  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     │
+└───────────────┘    └───────────────┘      └───────────────┘
+  </div>
+</div>
+
+<div class="section">
+  <h2>3. Module Descriptions</h2>
+
+  <div class="module-box">
+    <h4>Zookeeper</h4>
+    <p><span class="port">Port 2181</span></p>
+    <p>Apache Zookeeper provides distributed coordination for the Kafka cluster. It manages broker metadata, topic configurations, and cluster membership.</p>
+    <table>
+      <tr><th>Function</th><td>Kafka cluster coordination</td></tr>
+      <tr><th>Technology</th><td>Confluent Zookeeper 7.5.0</td></tr>
+      <tr><th>Dependencies</th><td>None</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Kafka Message Broker</h4>
+    <p><span class="port">Port 9092</span> <span class="port">Port 29092 (host)</span></p>
+    <p>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.</p>
+    <table>
+      <tr><th>Function</th><td>Message streaming and event distribution</td></tr>
+      <tr><th>Technology</th><td>Confluent Kafka 7.5.0</td></tr>
+      <tr><th>Topics</th><td><code>orders</code>, <code>trades</code>, <code>snapshots</code></td></tr>
+      <tr><th>Dependencies</th><td>Zookeeper</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>FIX Order Entry Gateway (FIX OEG)</h4>
+    <p><span class="port">Port 5001</span></p>
+    <p>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 <code>orders</code> topic.</p>
+    <table>
+      <tr><th>Function</th><td>FIX protocol order reception and normalization</td></tr>
+      <tr><th>Technology</th><td>QuickFIX/Python</td></tr>
+      <tr><th>Protocol</th><td>FIX 4.4</td></tr>
+      <tr><th>Message Types</th><td>NewOrderSingle (D), OrderCancelRequest (F), OrderCancelReplaceRequest (G)</td></tr>
+      <tr><th>Output</th><td>Kafka <code>orders</code> topic</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>FIX UI Clients</h4>
+    <p><span class="port">Port 5002 (Client 1)</span> <span class="port">Port 5003 (Client 2)</span></p>
+    <p>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.</p>
+    <table>
+      <tr><th>Function</th><td>FIX order submission interface</td></tr>
+      <tr><th>Technology</th><td>QuickFIX/Python + Flask</td></tr>
+      <tr><th>Features</th><td>New Order, Cancel, Amend</td></tr>
+      <tr><th>Connection</th><td>FIX 4.4 to FIX OEG</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Matcher (Order Matching Engine)</h4>
+    <p><span class="port">Port 6000</span></p>
+    <p>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.</p>
+    <table>
+      <tr><th>Function</th><td>Order matching, trade execution, order book management</td></tr>
+      <tr><th>Technology</th><td>Python/Flask with SQLite persistence</td></tr>
+      <tr><th>Algorithm</th><td>Price-Time Priority (FIFO)</td></tr>
+      <tr><th>Input</th><td>Kafka <code>orders</code> topic</td></tr>
+      <tr><th>Output</th><td>Kafka <code>trades</code> topic</td></tr>
+      <tr><th>API Endpoints</th><td><code>/orderbook/&lt;symbol&gt;</code>, <code>/trades</code>, <code>/health</code></td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Market Data Feeder (MDF)</h4>
+    <p><span class="port">Internal</span></p>
+    <p>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.</p>
+    <table>
+      <tr><th>Function</th><td>Market simulation and BBO publishing</td></tr>
+      <tr><th>Technology</th><td>Python</td></tr>
+      <tr><th>Output</th><td>Kafka <code>orders</code> and <code>snapshots</code> topics</td></tr>
+      <tr><th>Order Mix</th><td>90% passive (book building), 10% aggressive (trades)</td></tr>
+      <tr><th>Rate</th><td>Configurable (default: 8 orders/minute)</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Dashboard</h4>
+    <p><span class="port">Port 5005</span></p>
+    <p>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.</p>
+    <table>
+      <tr><th>Function</th><td>Real-time market visualization and order management</td></tr>
+      <tr><th>Technology</th><td>Python/Flask + JavaScript</td></tr>
+      <tr><th>Streaming</th><td>Server-Sent Events (SSE)</td></tr>
+      <tr><th>Input</th><td>Kafka topics + Matcher REST API</td></tr>
+      <tr><th>Features</th><td>Orders, Trades, BBO, Order Book, Charts, Statistics</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Frontend (Manual Order Entry)</h4>
+    <p><span class="port">Port 5000</span></p>
+    <p>Simple web interface for manual order submission. Allows users to enter orders directly without FIX protocol, useful for testing and demonstration.</p>
+    <table>
+      <tr><th>Function</th><td>Manual order entry interface</td></tr>
+      <tr><th>Technology</th><td>Python/Flask</td></tr>
+      <tr><th>Output</th><td>Kafka <code>orders</code> topic</td></tr>
+    </table>
+  </div>
+
+  <div class="module-box">
+    <h4>Consumer (Debug)</h4>
+    <p><span class="port">Internal</span></p>
+    <p>Debug utility that consumes and logs messages from Kafka topics. Useful for monitoring message flow and troubleshooting.</p>
+  </div>
+
+  <div class="module-box">
+    <h4>Snapshot Viewer</h4>
+    <p><span class="port">Internal</span></p>
+    <p>Utility service that subscribes to the <code>snapshots</code> topic and logs BBO updates. Writes to log files for analysis.</p>
+  </div>
+</div>
+
+<div class="section">
+  <h2>4. Dashboard User Interface</h2>
+
+  <h3>4.1 Orders Panel</h3>
+  <p>Displays real-time incoming orders with full management capabilities.</p>
+  <table>
+    <tr><th>Column</th><th>Description</th></tr>
+    <tr><td>Symbol</td><td>Stock ticker (ALPHA, EXAE, PEIR, QUEST)</td></tr>
+    <tr><td>Side</td><td><span class="green">BUY</span> (green) or <span class="red">SELL</span> (red)</td></tr>
+    <tr><td>Qty</td><td>Order quantity in shares</td></tr>
+    <tr><td>Price</td><td>Limit price</td></tr>
+    <tr><td>Source</td><td>Order origin (MDF, FIX, Manual)</td></tr>
+    <tr><td>Time</td><td>Order timestamp</td></tr>
+    <tr><td>Actions</td><td><span class="blue">Edit</span> / <span class="red">Cancel</span> buttons</td></tr>
+  </table>
+  <p><strong>Row Selection:</strong> Click any row to select, then use header buttons for bulk actions.</p>
+
+  <h3>4.2 Market Snapshot</h3>
+  <p>Shows Best Bid/Offer (BBO) for all securities with real-time updates.</p>
+  <table>
+    <tr><th>Column</th><th>Description</th></tr>
+    <tr><td>Symbol</td><td>Security identifier</td></tr>
+    <tr><td>Best Bid</td><td>Highest buy price <span class="green">(green)</span></td></tr>
+    <tr><td>Best Ask</td><td>Lowest sell price <span class="red">(red)</span></td></tr>
+    <tr><td>Spread</td><td>Ask - Bid difference</td></tr>
+    <tr><td>Mid</td><td>Midpoint: (Bid + Ask) / 2</td></tr>
+    <tr><td>Updated</td><td>Last update timestamp</td></tr>
+  </table>
+  <p><strong>Ticker Tape:</strong> Scrolling bar at bottom displays recent trades with price direction (▲ green up, ▼ red down).</p>
+
+  <h3>4.3 Trades Panel</h3>
+  <p>Lists all executed trades with calculated values.</p>
+  <table>
+    <tr><th>Column</th><th>Description</th></tr>
+    <tr><td>Symbol</td><td>Traded security</td></tr>
+    <tr><td>Qty</td><td>Executed quantity</td></tr>
+    <tr><td>Price</td><td>Execution price</td></tr>
+    <tr><td>Value</td><td>Trade value (Qty × Price)</td></tr>
+    <tr><td>Time</td><td>Execution timestamp</td></tr>
+  </table>
+
+  <h3>4.4 Order Book</h3>
+  <p>Displays full market depth for selected symbol.</p>
+  <ul>
+    <li>Select symbol from dropdown menu</li>
+    <li>Click <strong>Refresh</strong> to update (auto-refreshes every 3 seconds)</li>
+    <li><span class="green">Bid Qty / Bid Price</span> — Buy orders sorted by price (highest first)</li>
+    <li><span class="red">Ask Price / Ask Qty</span> — Sell orders sorted by price (lowest first)</li>
+    <li>Header shows total bid and ask counts</li>
+  </ul>
+
+  <h3>4.5 Trade Chart</h3>
+  <p>Visual representation of trade activity over time.</p>
+  <ul>
+    <li><span class="green">Green line</span> — Price trend connecting trade prices</li>
+    <li><span class="blue">Blue bars</span> — Volume per trade</li>
+    <li>Dropdown to filter by symbol or view all</li>
+    <li>Displays last 100 trades</li>
+  </ul>
+
+  <h3>4.6 Trading Statistics</h3>
+  <p>Aggregated metrics calculated from all trades.</p>
+  <table>
+    <tr><th>Metric</th><th>Description</th></tr>
+    <tr><td>Trades</td><td>Number of executed trades</td></tr>
+    <tr><td>Volume</td><td>Total shares traded</td></tr>
+    <tr><td>Value</td><td>Total monetary value (Σ Qty × Price)</td></tr>
+    <tr><td>Start</td><td>First trade price (opening)</td></tr>
+    <tr><td>Last</td><td>Most recent trade price</td></tr>
+    <tr><td>VWAP</td><td>Volume-Weighted Average Price</td></tr>
+  </table>
+  <p><strong>Bar Charts:</strong> Visual comparison showing <span class="green">Volume</span> and <span class="blue">Value</span> per symbol side by side.</p>
+</div>
+
+<div class="section">
+  <h2>5. Data Flow & Messaging</h2>
+
+  <h3>5.1 Kafka Topics</h3>
+  <table>
+    <tr><th>Topic</th><th>Producers</th><th>Consumers</th><th>Content</th></tr>
+    <tr><td><code>orders</code></td><td>FIX OEG, MDF, Frontend</td><td>Matcher, Dashboard</td><td>New orders, cancels, amends</td></tr>
+    <tr><td><code>trades</code></td><td>Matcher</td><td>Dashboard, Consumer</td><td>Executed trades</td></tr>
+    <tr><td><code>snapshots</code></td><td>MDF</td><td>Dashboard, Snapshot Viewer</td><td>BBO updates</td></tr>
+  </table>
+
+  <h3>5.2 Message Formats</h3>
+
+  <h4>Order Message</h4>
+  <div class="arch-diagram" style="font-size: 11px;">{
+  "symbol": "ALPHA",
+  "side": "BUY",
+  "price": 25.50,
+  "quantity": 100,
+  "cl_ord_id": "MDF-1234567890-1",
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}</div>
+
+  <h4>Trade Message</h4>
+  <div class="arch-diagram" style="font-size: 11px;">{
+  "symbol": "ALPHA",
+  "price": 25.50,
+  "quantity": 100,
+  "buy_order_id": "order-123",
+  "sell_order_id": "order-456",
+  "timestamp": 1234567890.123
+}</div>
+
+  <h4>Snapshot Message</h4>
+  <div class="arch-diagram" style="font-size: 11px;">{
+  "symbol": "ALPHA",
+  "best_bid": 25.45,
+  "best_ask": 25.55,
+  "bid_size": 500,
+  "ask_size": 300,
+  "timestamp": 1234567890.123,
+  "source": "MDF"
+}</div>
+</div>
+
+<div class="section">
+  <h2>6. Configuration</h2>
+
+  <table>
+    <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+    <tr><td><code>KAFKA_BOOTSTRAP</code></td><td>kafka:9092</td><td>Kafka broker address</td></tr>
+    <tr><td><code>MATCHER_URL</code></td><td>http://matcher:6000</td><td>Matcher API endpoint</td></tr>
+    <tr><td><code>TICK_SIZE</code></td><td>0.05</td><td>Minimum price increment</td></tr>
+    <tr><td><code>ORDERS_PER_MIN</code></td><td>8</td><td>MDF order generation rate</td></tr>
+    <tr><td><code>SECURITIES_FILE</code></td><td>/app/data/securities.txt</td><td>Securities configuration</td></tr>
+  </table>
+
+  <h3>6.1 Supported Securities</h3>
+  <table>
+    <tr><th>Symbol</th><th>Start Price</th><th>Description</th></tr>
+    <tr><td>ALPHA</td><td>25.00</td><td>Test Security A</td></tr>
+    <tr><td>EXAE</td><td>42.00</td><td>Test Security B</td></tr>
+    <tr><td>PEIR</td><td>18.50</td><td>Test Security C</td></tr>
+    <tr><td>QUEST</td><td>12.75</td><td>Test Security D</td></tr>
+  </table>
+</div>
+
+<div class="section">
+  <h2>7. Quick Reference</h2>
+
+  <h3>7.1 Starting the System</h3>
+  <div class="highlight">
+    <code>docker compose up --build</code>
+  </div>
+
+  <h3>7.2 Service URLs</h3>
+  <table>
+    <tr><th>Service</th><th>URL</th><th>Purpose</th></tr>
+    <tr><td>Dashboard</td><td>http://localhost:5005</td><td>Main trading view</td></tr>
+    <tr><td>Frontend</td><td>http://localhost:5000</td><td>Manual order entry</td></tr>
+    <tr><td>FIX Client 1</td><td>http://localhost:5002</td><td>FIX order submission</td></tr>
+    <tr><td>FIX Client 2</td><td>http://localhost:5003</td><td>FIX order submission</td></tr>
+    <tr><td>Matcher API</td><td>http://localhost:6000</td><td>REST API</td></tr>
+  </table>
+
+  <h3>7.3 Dashboard Actions</h3>
+  <table>
+    <tr><th>Action</th><th>How To</th></tr>
+    <tr><td>View order book depth</td><td>Select symbol from Order Book dropdown</td></tr>
+    <tr><td>Edit an order</td><td>Click <span class="blue">Edit</span> button on order row</td></tr>
+    <tr><td>Cancel an order</td><td>Click <span class="red">Cancel</span> button on order row</td></tr>
+    <tr><td>Filter trade chart</td><td>Select symbol from Trade Chart dropdown</td></tr>
+    <tr><td>Pause ticker tape</td><td>Hover mouse over the ticker</td></tr>
+    <tr><td>Select multiple orders</td><td>Click rows, use header Edit/Cancel buttons</td></tr>
+  </table>
+
+  <h3>7.4 Connection Status Indicators</h3>
+  <table>
+    <tr><th>Status</th><th>Indicator</th><th>Meaning</th></tr>
+    <tr><td>Live</td><td><span class="green">● Green</span></td><td>Connected to real-time stream</td></tr>
+    <tr><td>Connecting</td><td><span style="color:#ffc107;">● Yellow</span></td><td>Establishing connection</td></tr>
+    <tr><td>Disconnected</td><td><span class="red">● Red</span></td><td>Connection lost, auto-reconnecting</td></tr>
+  </table>
+</div>
+
+<hr>
+
+<div class="footer">
+  <p><strong>StockEx v1.0</strong> — Trading Simulation Platform</p>
+  <p>Inspired by Euronext OPTIQ</p>
+  <p style="margin-top: 15px; font-size: 11px;">To create PDF: Open in browser → Print (Ctrl+P) → Save as PDF</p>
+</div>
+
+</body>
+</html>

consumer/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY consumer.py .
+CMD ["python", "consumer.py"]

consumer/consumer.py

@@ -0,0 +1,22 @@
+import sys
+sys.path.insert(0, "/app")
+
+import json
+from shared.config import Config
+from shared.kafka_utils import create_consumer
+
+
+consumer = create_consumer(
+    topics=Config.TRADES_TOPIC,
+    group_id="order-group",
+    auto_offset_reset="earliest",
+    component_name="Consumer"
+)
+
+print("Listening for trades...")
+
+for msg in consumer:
+    trade = msg.value
+    qty = trade.get("quantity") or trade.get("qty") or "-"
+    price = trade.get("price", "-")
+    print(f"TRADE: {trade.get('symbol', '?')} - {qty} @ {price}")

consumer/requirements.txt

@@ -0,0 +1,2 @@
+kafka-python==2.0.2
+

dashboard/Dockerfile

@@ -0,0 +1,10 @@
+FROM fix-base
+
+WORKDIR /app
+
+# Install dashboard-specific deps
+RUN pip install --no-cache-dir kafka-python requests
+
+COPY . /app
+
+CMD ["python", "dashboard.py"]

dashboard/dashboard.py

@@ -0,0 +1,249 @@
+import sys
+sys.path.insert(0, "/app")
+
+from flask import Flask, render_template, jsonify, Response, request
+import threading, json, os, time, requests
+from queue import Queue, Empty
+
+from shared.config import Config
+from shared.kafka_utils import create_consumer, create_producer
+
+app = Flask(__name__, template_folder="templates")
+app.config["TEMPLATES_AUTO_RELOAD"] = True
+
+# Shared state
+orders, bbos, trades_cache = [], {}, []
+lock = threading.Lock()
+
+# SSE: list of queues for connected clients
+sse_clients = []
+sse_clients_lock = threading.Lock()
+
+def broadcast_event(event_type, data):
+    """Send an event to all connected SSE clients."""
+    message = f"event: {event_type}\ndata: {json.dumps(data)}\n\n"
+    with sse_clients_lock:
+        dead_clients = []
+        for q in sse_clients:
+            try:
+                q.put_nowait(message)
+            except:
+                dead_clients.append(q)
+        for q in dead_clients:
+            sse_clients.remove(q)
+
+# Kafka consumer thread
+def consume_kafka():
+    consumer = create_consumer(
+        topics=[Config.ORDERS_TOPIC, Config.SNAPSHOTS_TOPIC, Config.TRADES_TOPIC],
+        group_id="dashboard",
+        component_name="Dashboard"
+    )
+    for msg in consumer:
+        with lock:
+            if msg.topic == "orders":
+                order = msg.value
+                orders.insert(0, order)
+                orders[:] = orders[:50]  # keep last 50
+                broadcast_event("order", order)
+
+            elif msg.topic == "snapshots":
+                snap = msg.value
+                # Handle both simple snapshots and MDF snapshots
+                symbol = snap.get("symbol")
+                if not symbol:
+                    continue
+
+                bbo_data = {
+                    "best_bid": snap.get("best_bid"),
+                    "best_ask": snap.get("best_ask"),
+                    "bid_size": snap.get("bid_size"),
+                    "ask_size": snap.get("ask_size"),
+                    "timestamp": snap.get("timestamp", time.time()),
+                    "source": snap.get("source", "unknown")
+                }
+                bbos[symbol] = bbo_data
+                broadcast_event("snapshot", {"symbol": symbol, **bbo_data})
+
+            elif msg.topic == "trades":
+                trade = msg.value
+                trades_cache.insert(0, trade)
+                trades_cache[:] = trades_cache[:200]  # keep last 200
+                broadcast_event("trade", trade)
+
+threading.Thread(target=consume_kafka, daemon=True).start()
+
+@app.route("/")
+def index():
+    return render_template("index.html")
+
+@app.route("/health")
+def health():
+    """Health check endpoint."""
+    status = {
+        "status": "healthy",
+        "service": "dashboard",
+        "timestamp": time.time(),
+        "stats": {
+            "orders_cached": len(orders),
+            "trades_cached": len(trades_cache),
+            "symbols_tracked": len(bbos),
+            "sse_clients": len(sse_clients)
+        }
+    }
+    # Check matcher connectivity
+    try:
+        r = requests.get(f"{Config.MATCHER_URL}/health", timeout=2)
+        if r.status_code == 200:
+            status["matcher"] = "connected"
+        else:
+            status["matcher"] = f"error: status {r.status_code}"
+            status["status"] = "degraded"
+    except Exception as e:
+        status["matcher"] = f"error: {e}"
+        status["status"] = "degraded"
+
+    return jsonify(status)
+
+@app.route("/data")
+def data():
+    """Fallback polling endpoint (still useful for initial load or SSE fallback)."""
+    # Always fetch trades from matcher (more reliable)
+    try:
+        r = requests.get(f"{Config.MATCHER_URL}/trades", timeout=2)
+        resp = r.json()
+        trades = resp.get('trades', []) if isinstance(resp, dict) else resp
+    except Exception as e:
+        print("Cannot fetch trades:", e)
+        with lock:
+            trades = list(trades_cache)
+
+    # Order book for dropdown (fetch latest for all symbols)
+    try:
+        r = requests.get(f"{Config.MATCHER_URL}/orderbook/ALPHA", timeout=2)
+        book = r.json()
+    except Exception as e:
+        print("Cannot fetch orderbook:", e)
+        book = {"bids": [], "asks": []}
+
+    with lock:
+        return jsonify({
+            "orders": list(orders),
+            "bbos": dict(bbos),
+            "trades": trades,
+            "book": book
+        })
+
+@app.route("/orderbook/<symbol>")
+def orderbook(symbol):
+    """Proxy to matcher orderbook API."""
+    try:
+        r = requests.get(f"{Config.MATCHER_URL}/orderbook/{symbol}", timeout=2)
+        return (r.text, r.status_code, {"Content-Type": "application/json"})
+    except Exception as e:
+        return jsonify({"error": str(e), "bids": [], "asks": []}), 500
+
+# Kafka producer for order management (lazy init)
+_producer = None
+def get_producer():
+    global _producer
+    if _producer is None:
+        _producer = create_producer(component_name="Dashboard")
+    return _producer
+
+@app.route("/order/cancel", methods=["POST"])
+def cancel_order():
+    """Send cancel request to matcher via Kafka."""
+    try:
+        data = request.get_json()
+        orig_cl_ord_id = data.get("orig_cl_ord_id")
+        symbol = data.get("symbol")
+
+        if not orig_cl_ord_id:
+            return jsonify({"status": "error", "error": "Missing orig_cl_ord_id"}), 400
+
+        cancel_msg = {
+            "type": "cancel",
+            "orig_cl_ord_id": orig_cl_ord_id,
+            "symbol": symbol,
+            "timestamp": time.time()
+        }
+
+        producer = get_producer()
+        producer.send(Config.ORDERS_TOPIC, cancel_msg)
+        producer.flush()
+
+        return jsonify({"status": "ok", "message": f"Cancel request sent for {orig_cl_ord_id}"})
+    except Exception as e:
+        return jsonify({"status": "error", "error": str(e)}), 500
+
+@app.route("/order/amend", methods=["POST"])
+def amend_order():
+    """Send amend request to matcher via Kafka."""
+    try:
+        data = request.get_json()
+        orig_cl_ord_id = data.get("orig_cl_ord_id")
+        symbol = data.get("symbol")
+        quantity = data.get("quantity")
+        price = data.get("price")
+
+        if not orig_cl_ord_id:
+            return jsonify({"status": "error", "error": "Missing orig_cl_ord_id"}), 400
+
+        amend_msg = {
+            "type": "amend",
+            "orig_cl_ord_id": orig_cl_ord_id,
+            "cl_ord_id": f"amend-{int(time.time()*1000)}",
+            "symbol": symbol,
+            "quantity": quantity,
+            "price": price,
+            "timestamp": time.time()
+        }
+
+        producer = get_producer()
+        producer.send(Config.ORDERS_TOPIC, amend_msg)
+        producer.flush()
+
+        return jsonify({"status": "ok", "message": f"Amend request sent for {orig_cl_ord_id}"})
+    except Exception as e:
+        return jsonify({"status": "error", "error": str(e)}), 500
+
+@app.route("/stream")
+def stream():
+    """SSE endpoint for real-time updates."""
+    def event_stream():
+        q = Queue(maxsize=100)
+        with sse_clients_lock:
+            sse_clients.append(q)
+        try:
+            # Send initial connection event
+            yield f"event: connected\ndata: {json.dumps({'status': 'connected'})}\n\n"
+
+            # Send current state on connect (including trades)
+            with lock:
+                yield f"event: init\ndata: {json.dumps({'orders': list(orders), 'bbos': dict(bbos), 'trades': list(trades_cache)})}\n\n"
+
+            while True:
+                try:
+                    message = q.get(timeout=30)  # 30s timeout for keepalive
+                    yield message
+                except Empty:
+                    # Send keepalive comment
+                    yield ": keepalive\n\n"
+        finally:
+            with sse_clients_lock:
+                if q in sse_clients:
+                    sse_clients.remove(q)
+
+    return Response(
+        event_stream(),
+        mimetype="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",  # Disable nginx buffering
+            "Connection": "keep-alive"
+        }
+    )
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True, use_reloader=False)

dashboard/templates/index - Copy (6).html

@@ -0,0 +1,198 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8"/>
+  <title>Trading Dashboard</title>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; background: #f7f7f7; }
+    h2 { margin: 5px 0; }
+    .container { display: grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; }
+    .panel {
+      background: #fff;
+      border-radius: 8px;
+      padding: 10px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      height: 400px;
+      display: flex;
+      flex-direction: column;
+    }
+    .panel pre {
+      flex-grow: 1;
+      overflow-y: scroll;
+      background: #fafafa;
+      padding: 10px;
+      margin: 0;
+      border-radius: 6px;
+      font-size: 13px;
+      white-space: pre;
+      font-family: monospace;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13px;
+    }
+    th, td {
+      border: 1px solid #ccc;
+      padding: 4px;
+      text-align: center;
+    }
+    .updated {
+      animation: flash 1s ease-in-out;
+    }
+    @keyframes flash {
+      from { background: yellow; }
+      to   { background: transparent; }
+    }
+  </style>
+</head>
+<body>
+  <h1>📊 Trading Dashboard</h1>
+  <div class="container">
+    <div class="panel">
+      <h2>📝 Orders</h2>
+      <pre id="orders"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>💹 BBOs (from Order Book API)</h2>
+      <pre id="book"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>🤝 Trades</h2>
+      <pre id="trades"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>📖 Full Order Book</h2>
+      <label for="symbol-select">Select symbol:</label>
+      <select id="symbol-select" onchange="refresh()"></select>
+      <div id="full-book" style="flex-grow:1; overflow-y:scroll;"></div>
+    </div>
+
+    <div class="panel">
+      <h2>📊 Market Snapshots (BBO)</h2>
+      <table id="bbos-table">
+        <thead>
+          <tr>
+            <th>Symbol</th>
+            <th>Best Bid</th>
+            <th>Best Ask</th>
+            <th>Timestamp</th>
+            <th>Source</th>
+          </tr>
+        </thead>
+        <tbody id="bbos-body"></tbody>
+      </table>
+    </div>
+  </div>
+
+  <script>
+    function fmtOrder(o) {
+      const sym = (o.symbol ?? "?").padEnd(6);
+      const side = (o.type ?? o.side ?? "?").padEnd(6);
+      const qty = String(o.quantity ?? o.qty ?? "?").padStart(6);
+      const price = o.price !== undefined ? Number(o.price).toFixed(2).padStart(8) : "   -   ";
+      const src = (o.source ?? "?").padEnd(5);
+      const ts = o.timestamp ? new Date(o.timestamp * 1000).toLocaleTimeString() : "-";
+      return `${sym} | ${side} | ${qty} @ ${price} | ${src} | ${ts}\n`;
+    }
+
+    function fmtTrade(t) {
+      const sym = (t.symbol ?? "?").padEnd(6);
+      const qty = String(t.quantity ?? t.qty ?? "-").padStart(6);
+      const price = t.price !== undefined ? Number(t.price).toFixed(2).padStart(8) : "   -   ";
+      const ts = t.timestamp ? new Date(t.timestamp * 1000).toLocaleTimeString() : "-";
+      return `${sym} | ${qty} x ${price} | ${ts}\n`;
+    }
+
+    function renderOrderBook(book) {
+      const bids = (book.buy || []).sort((a,b) => b.price - a.price);
+      const asks = (book.sell || []).sort((a,b) => a.price - b.price);
+      const maxRows = Math.max(bids.length, asks.length);
+      let html = "<table><tr><th>Bid Size</th><th>Bid Price</th><th>Ask Price</th><th>Ask Size</th></tr>";
+      for (let i=0; i<maxRows; i++) {
+        const b = bids[i] || {};
+        const a = asks[i] || {};
+        html += `<tr>
+          <td>${b.quantity ?? ""}</td>
+          <td>${b.price !== undefined ? Number(b.price).toFixed(2) : ""}</td>
+          <td>${a.price !== undefined ? Number(a.price).toFixed(2) : ""}</td>
+          <td>${a.quantity ?? ""}</td>
+        </tr>`;
+      }
+      html += "</table>";
+      return html;
+    }
+
+    async function refresh() {
+      try {
+        const r = await fetch("/data");
+        const data = await r.json();
+
+        // Orders
+        document.getElementById("orders").textContent =
+          data.orders.slice().reverse().map(fmtOrder).join("");
+
+        // Trades
+        document.getElementById("trades").textContent =
+          data.trades.slice().reverse().map(fmtTrade).join("");
+
+        // Book JSON dump
+        document.getElementById("book").textContent =
+          JSON.stringify(data.book ?? {}, null, 2);
+
+        // Snapshots → fill table
+        const tbody = document.getElementById("bbos-body");
+        tbody.innerHTML = "";
+        for (const [symbol, snap] of Object.entries(data.bbos)) {
+          const row = document.createElement("tr");
+          row.innerHTML = `
+            <td>${symbol}</td>
+            <td>${snap.best_bid !== null ? Number(snap.best_bid).toFixed(2) : "-"}</td>
+            <td>${snap.best_ask !== null ? Number(snap.best_ask).toFixed(2) : "-"}</td>
+            <td>${snap.timestamp ? new Date(snap.timestamp*1000).toLocaleTimeString() : "-"}</td>
+            <td>${snap.source ?? "-"}</td>
+          `;
+          row.classList.add("updated");
+          setTimeout(() => row.classList.remove("updated"), 1000);
+          tbody.appendChild(row);
+        }
+
+        // Populate dropdown once
+        const sel = document.getElementById("symbol-select");
+        if (!sel.options.length) {
+          const symbols = [...new Set([
+            ...Object.keys(data.bbos),
+            ...(data.book?.buy || []).map(o => o.symbol),
+            ...(data.book?.sell || []).map(o => o.symbol)
+          ])];
+          symbols.forEach(sym => {
+            const opt = document.createElement("option");
+            opt.value = sym;
+            opt.textContent = sym;
+            sel.appendChild(opt);
+          });
+        }
+
+        // Render order book for selected symbol
+        const sym = sel.value;
+        if (sym) {
+          const bookForSymbol = {
+            buy: (data.book?.buy || []).filter(o => o.symbol === sym),
+            sell: (data.book?.sell || []).filter(o => o.symbol === sym),
+          };
+          document.getElementById("full-book").innerHTML = renderOrderBook(bookForSymbol);
+        }
+
+      } catch(e) {
+        console.error("Refresh error", e);
+      }
+    }
+
+    setInterval(refresh, 2000);
+    refresh();
+  </script>
+</body>
+</html>

dashboard/templates/index.html

@@ -0,0 +1,964 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8"/>
+  <title>Trading Dashboard</title>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; background: #f7f7f7; }
+    h1 { display: flex; align-items: center; gap: 15px; }
+    h2 { margin: 5px 0; }
+    .container { display: grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; }
+    .panel {
+      background: #fff;
+      border-radius: 8px;
+      padding: 10px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      height: 400px;
+      display: flex;
+      flex-direction: column;
+      min-width: 0;
+      overflow: hidden;
+    }
+    .panel pre {
+      flex-grow: 1;
+      overflow-y: scroll;
+      background: #fafafa;
+      padding: 10px;
+      margin: 0;
+      border-radius: 6px;
+      font-size: 13px;
+      white-space: pre;
+      font-family: monospace;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13px;
+    }
+    th, td {
+      border: 1px solid #ccc;
+      padding: 4px;
+      text-align: center;
+    }
+    .updated {
+      animation: flash 1s ease-in-out;
+    }
+    @keyframes flash {
+      from { background: yellow; }
+      to   { background: transparent; }
+    }
+    /* Connection status indicator */
+    .status {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 12px;
+      border-radius: 20px;
+      font-size: 12px;
+      font-weight: bold;
+    }
+    .status .dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+    }
+    .status.connected { background: #d4edda; color: #155724; }
+    .status.connected .dot { background: #28a745; }
+    .status.disconnected { background: #f8d7da; color: #721c24; }
+    .status.disconnected .dot { background: #dc3545; }
+    .status.connecting { background: #fff3cd; color: #856404; }
+    .status.connecting .dot { background: #ffc107; animation: pulse 1s infinite; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.4; }
+    }
+    .new-item {
+      animation: highlight 2s ease-out;
+    }
+    @keyframes highlight {
+      from { background: #c8e6c9; }
+      to { background: transparent; }
+    }
+    /* Selectable rows */
+    .selectable-row { cursor: pointer; }
+    .selectable-row:hover { background: #f5f5f5; }
+    .selectable-row.selected { background: #e3f2fd !important; }
+
+    /* Ticker tape */
+    .ticker-container {
+      background: #1a1a2e;
+      overflow: hidden;
+      padding: 8px 0;
+      border-radius: 4px;
+      margin-top: 10px;
+    }
+    .ticker-tape {
+      display: flex;
+      animation: ticker-scroll 30s linear infinite;
+      white-space: nowrap;
+    }
+    .ticker-tape:hover {
+      animation-play-state: paused;
+    }
+    @keyframes ticker-scroll {
+      0% { transform: translateX(0); }
+      100% { transform: translateX(-50%); }
+    }
+    .ticker-item {
+      display: inline-flex;
+      align-items: center;
+      padding: 0 20px;
+      font-size: 13px;
+      font-weight: bold;
+    }
+    .ticker-symbol {
+      color: #fff;
+      margin-right: 8px;
+    }
+    .ticker-price {
+      margin-right: 5px;
+    }
+    .ticker-price.up { color: #4caf50; }
+    .ticker-price.down { color: #f44336; }
+    .ticker-price.neutral { color: #ffc107; }
+    .ticker-change {
+      font-size: 11px;
+    }
+    .ticker-change.up { color: #4caf50; }
+    .ticker-change.down { color: #f44336; }
+    .ticker-arrow { margin-right: 3px; }
+  </style>
+</head>
+<body>
+  <h1>Trading Dashboard <span id="status" class="status connecting"><span class="dot"></span><span id="status-text">Connecting...</span></span></h1>
+  <div class="container">
+
+    <div class="panel">
+      <h2>Orders <span id="order-count" style="font-size:22px;color:#333;font-weight:bold;"></span>
+        <button id="edit-selected-btn" onclick="editSelectedOrder()" style="display:none; margin-left:10px; padding:4px 10px; background:#2196F3; color:#fff; border:none; border-radius:4px; cursor:pointer;">Edit</button>
+        <button id="cancel-selected-btn" onclick="cancelSelectedOrder()" style="display:none; margin-left:5px; padding:4px 10px; background:#f44336; color:#fff; border:none; border-radius:4px; cursor:pointer;">Cancel</button>
+      </h2>
+      <div style="flex-grow:1; overflow-y:auto;">
+        <table id="orders-table">
+          <thead>
+            <tr style="background:#f0f0f0;">
+              <th>Symbol</th>
+              <th>Side</th>
+              <th>Qty</th>
+              <th>Price</th>
+              <th>Source</th>
+              <th>Time</th>
+              <th>Actions</th>
+            </tr>
+          </thead>
+          <tbody id="orders-body"></tbody>
+        </table>
+      </div>
+    </div>
+
+    <!-- Order Edit Modal -->
+    <div id="order-modal" style="display:none; position:fixed; top:0; left:0; width:100%; height:100%; background:rgba(0,0,0,0.5); z-index:1000;">
+      <div style="position:absolute; top:50%; left:50%; transform:translate(-50%,-50%); background:#fff; padding:20px; border-radius:8px; min-width:300px;">
+        <h3 style="margin:0 0 15px;">Edit Order</h3>
+        <input type="hidden" id="edit-order-id">
+        <input type="hidden" id="edit-order-symbol">
+        <div style="margin-bottom:10px;">
+          <label style="display:block; font-size:12px; color:#666;">Quantity:</label>
+          <input type="number" id="edit-qty" style="width:100%; padding:8px; border:1px solid #ccc; border-radius:4px;">
+        </div>
+        <div style="margin-bottom:15px;">
+          <label style="display:block; font-size:12px; color:#666;">Price:</label>
+          <input type="number" step="0.01" id="edit-price" style="width:100%; padding:8px; border:1px solid #ccc; border-radius:4px;">
+        </div>
+        <div style="display:flex; gap:10px;">
+          <button onclick="submitAmend()" style="flex:1; padding:8px; background:#2196F3; color:#fff; border:none; border-radius:4px; cursor:pointer;">Update</button>
+          <button onclick="closeModal()" style="flex:1; padding:8px; background:#ccc; border:none; border-radius:4px; cursor:pointer;">Cancel</button>
+        </div>
+      </div>
+    </div>
+
+    <div class="panel">
+      <h2>Market Snapshot</h2>
+      <div style="flex-grow:1; overflow-y:auto;">
+        <table id="bbos-table">
+          <thead>
+            <tr>
+              <th>Symbol</th>
+              <th>Best Bid</th>
+              <th>Best Ask</th>
+              <th>Spread</th>
+              <th>Mid</th>
+              <th>Updated</th>
+            </tr>
+          </thead>
+          <tbody id="bbos-body"></tbody>
+        </table>
+      </div>
+      <div class="ticker-container">
+        <div class="ticker-tape" id="ticker-tape">
+          <span class="ticker-item"><span class="ticker-symbol">Loading trades...</span></span>
+        </div>
+      </div>
+    </div>
+
+    <div class="panel">
+      <h2>Trades <span id="trade-count" style="font-size:22px;color:#333;font-weight:bold;"></span></h2>
+      <div style="flex-grow:1; overflow-y:auto;">
+        <table id="trades-table">
+          <thead>
+            <tr style="background:#f0f0f0;">
+              <th>Symbol</th>
+              <th>Qty</th>
+              <th>Price</th>
+              <th>Value</th>
+              <th>Time</th>
+            </tr>
+          </thead>
+          <tbody id="trades-body"></tbody>
+        </table>
+      </div>
+    </div>
+
+    <div class="panel">
+      <h2>Trade Chart
+        <select id="chart-symbol" onchange="renderPriceChart()" style="margin-left:10px; padding:2px 5px;">
+          <option value="">All Symbols</option>
+        </select>
+      </h2>
+      <canvas id="price-chart" style="width:100%; flex-grow:1;"></canvas>
+    </div>
+
+    <div class="panel">
+      <h2>Order Book
+        <select id="bbo-symbol-select" onchange="renderOrderBookPanel()" style="margin-left:10px; padding:2px 5px;">
+        </select>
+        <button onclick="renderOrderBookPanel()" style="margin-left:5px; padding:2px 8px; cursor:pointer;">Refresh</button>
+      </h2>
+      <div id="full-bbo-container" style="flex-grow:1; overflow-y:auto; padding:5px;">
+        <p style="color:#666; text-align:center;">Select a symbol</p>
+      </div>
+    </div>
+
+    <div class="panel">
+      <h2>Trading Statistics</h2>
+      <div id="stats-container" style="flex-grow:1; overflow-y:auto; padding: 10px;">
+        <table id="stats-table" style="width:100%; margin-bottom:10px; font-size:12px;">
+          <thead>
+            <tr>
+              <th>Symbol</th>
+              <th>Trades</th>
+              <th>Volume</th>
+              <th>Value</th>
+              <th>Start</th>
+              <th>Last</th>
+              <th>VWAP</th>
+            </tr>
+          </thead>
+          <tbody id="stats-body"></tbody>
+        </table>
+        <div style="display:flex; gap:4px; justify-content:center; margin-top:5px;">
+          <div style="font-size:10px; color:#4CAF50; margin-right:10px;">■ Volume</div>
+          <div style="font-size:10px; color:#2196F3;">■ Value</div>
+        </div>
+        <div id="stats-chart" style="display:flex; align-items:flex-end; justify-content:center; gap:15px; height:120px; margin-top:5px;"></div>
+      </div>
+    </div>
+
+  </div>
+
+  <script>
+    // State
+    const state = {
+      orders: [],
+      trades: [],
+      bbos: {},
+      connected: false,
+      lastPrices: {}  // Track last price per symbol for ticker
+    };
+
+    function setStatus(status, text) {
+      const el = document.getElementById("status");
+      const textEl = document.getElementById("status-text");
+      el.className = "status " + status;
+      textEl.textContent = text;
+    }
+
+    function fmtOrder(o) {
+      const sym = (o.symbol ?? "?").padEnd(6);
+      const side = (o.type ?? o.side ?? "?").padEnd(4);
+      const price = o.price !== undefined ? Number(o.price).toFixed(2).padStart(8) : "   ?   ";
+      const qty = String(o.quantity ?? o.qty ?? "?").padStart(6);
+      const src = (o.source ?? "?").padEnd(8);
+      const ts = o.timestamp ? new Date(o.timestamp * 1000).toLocaleTimeString() : "-";
+      return `${sym} ${side} ${qty} @ ${price} | ${src} | ${ts}`;
+    }
+
+    function fmtTrade(t) {
+      const sym = (t.symbol ?? "?").padEnd(6);
+      const qty = String(t.quantity ?? t.qty ?? "-").padStart(6);
+      const price = t.price !== undefined ? Number(t.price).toFixed(2).padStart(8) : "   -   ";
+      const ts = t.timestamp ? new Date(t.timestamp * 1000).toLocaleTimeString() : "-";
+      return `${sym} ${qty} x ${price} | ${ts}`;
+    }
+
+    // Selected order state
+    let selectedOrder = null;
+
+    function renderOrders() {
+      const tbody = document.getElementById("orders-body");
+      tbody.innerHTML = "";
+      for (let i = 0; i < state.orders.length; i++) {
+        const o = state.orders[i];
+        const row = document.createElement("tr");
+        const side = o.type ?? o.side ?? "?";
+        const isBuy = side.toLowerCase().includes("buy");
+        const orderId = o.cl_ord_id || o.order_id || o.id || "";
+
+        row.className = "selectable-row";
+        row.dataset.index = i;
+        row.dataset.orderId = orderId;
+        row.dataset.symbol = o.symbol || "";
+        row.dataset.qty = o.quantity || o.qty || 0;
+        row.dataset.price = o.price || 0;
+
+        if (selectedOrder && selectedOrder.index === i) {
+          row.classList.add("selected");
+        }
+
+        row.onclick = () => selectOrder(i, orderId, o.symbol, o.quantity || o.qty || 0, o.price || 0);
+
+        row.innerHTML = `
+          <td><strong>${o.symbol ?? "?"}</strong></td>
+          <td style="color:${isBuy ? '#2e7d32' : '#c62828'}; font-weight:bold;">${side}</td>
+          <td>${o.quantity ?? o.qty ?? "-"}</td>
+          <td>${o.price !== undefined ? Number(o.price).toFixed(2) : "-"}</td>
+          <td style="font-size:11px;">${o.source ?? "-"}</td>
+          <td style="font-size:11px;">${o.timestamp ? new Date(o.timestamp * 1000).toLocaleTimeString() : "-"}</td>
+          <td>
+            ${orderId ? `
+              <button onclick="event.stopPropagation(); editOrder('${orderId}', '${o.symbol}', ${o.quantity || o.qty || 0}, ${o.price || 0})"
+                      style="padding:2px 6px; font-size:11px; cursor:pointer; background:#2196F3; color:#fff; border:none; border-radius:3px; margin-right:3px;">Edit</button>
+              <button onclick="event.stopPropagation(); cancelOrder('${orderId}', '${o.symbol}')"
+                      style="padding:2px 6px; font-size:11px; cursor:pointer; background:#f44336; color:#fff; border:none; border-radius:3px;">Cancel</button>
+            ` : '<span style="color:#999; font-size:10px;">N/A</span>'}
+          </td>
+        `;
+        tbody.appendChild(row);
+      }
+      document.getElementById("order-count").textContent = `(${state.orders.length})`;
+      updateSelectionButtons();
+    }
+
+    function selectOrder(index, orderId, symbol, qty, price) {
+      // Toggle selection
+      if (selectedOrder && selectedOrder.index === index) {
+        selectedOrder = null;
+      } else {
+        selectedOrder = { index, orderId, symbol, qty, price };
+      }
+      // Update row highlighting
+      document.querySelectorAll("#orders-body tr").forEach((row, i) => {
+        row.classList.toggle("selected", selectedOrder && selectedOrder.index === i);
+      });
+      updateSelectionButtons();
+    }
+
+    function updateSelectionButtons() {
+      const editBtn = document.getElementById("edit-selected-btn");
+      const cancelBtn = document.getElementById("cancel-selected-btn");
+      if (selectedOrder && selectedOrder.orderId) {
+        editBtn.style.display = "inline-block";
+        cancelBtn.style.display = "inline-block";
+      } else {
+        editBtn.style.display = "none";
+        cancelBtn.style.display = "none";
+      }
+    }
+
+    function editSelectedOrder() {
+      if (selectedOrder && selectedOrder.orderId) {
+        editOrder(selectedOrder.orderId, selectedOrder.symbol, selectedOrder.qty, selectedOrder.price);
+      }
+    }
+
+    function cancelSelectedOrder() {
+      if (selectedOrder && selectedOrder.orderId) {
+        cancelOrder(selectedOrder.orderId, selectedOrder.symbol);
+      }
+    }
+
+    function renderTrades() {
+      const tbody = document.getElementById("trades-body");
+      tbody.innerHTML = "";
+      for (const t of state.trades) {
+        const row = document.createElement("tr");
+        const qty = t.quantity ?? t.qty ?? 0;
+        const price = t.price ?? 0;
+        const value = (qty * price).toFixed(2);
+        row.innerHTML = `
+          <td><strong>${t.symbol ?? "?"}</strong></td>
+          <td>${qty}</td>
+          <td>${price.toFixed(2)}</td>
+          <td style="color:#666;">${value}</td>
+          <td style="font-size:11px;">${t.timestamp ? new Date(t.timestamp * 1000).toLocaleTimeString() : "-"}</td>
+        `;
+        tbody.appendChild(row);
+      }
+      document.getElementById("trade-count").textContent = `(${state.trades.length})`;
+      renderTicker();
+    }
+
+    function renderTicker() {
+      const ticker = document.getElementById("ticker-tape");
+      if (state.trades.length === 0) {
+        ticker.innerHTML = '<span class="ticker-item"><span class="ticker-symbol">Waiting for trades...</span></span>';
+        return;
+      }
+
+      // Get last 20 trades and build ticker items
+      const recentTrades = state.trades.slice(0, 20);
+      let tickerHTML = "";
+
+      for (const t of recentTrades) {
+        const symbol = t.symbol || "?";
+        const price = t.price || 0;
+        const qty = t.quantity || t.qty || 0;
+        const lastPrice = state.lastPrices[symbol];
+
+        // Determine direction
+        let direction = "neutral";
+        let arrow = "●";
+        if (lastPrice !== undefined) {
+          if (price > lastPrice) {
+            direction = "up";
+            arrow = "▲";
+          } else if (price < lastPrice) {
+            direction = "down";
+            arrow = "▼";
+          }
+        }
+
+        // Update last price
+        state.lastPrices[symbol] = price;
+
+        tickerHTML += `
+          <span class="ticker-item">
+            <span class="ticker-symbol">${symbol}</span>
+            <span class="ticker-price ${direction}">${price.toFixed(2)}</span>
+            <span class="ticker-change ${direction}">
+              <span class="ticker-arrow">${arrow}</span>${qty}
+            </span>
+          </span>
+        `;
+      }
+
+      // Duplicate for seamless scroll
+      ticker.innerHTML = tickerHTML + tickerHTML;
+    }
+
+    // Order management functions
+    function editOrder(orderId, symbol, qty, price) {
+      document.getElementById("edit-order-id").value = orderId;
+      document.getElementById("edit-order-symbol").value = symbol;
+      document.getElementById("edit-qty").value = qty;
+      document.getElementById("edit-price").value = price;
+      document.getElementById("order-modal").style.display = "block";
+    }
+
+    function closeModal() {
+      document.getElementById("order-modal").style.display = "none";
+    }
+
+    async function submitAmend() {
+      const orderId = document.getElementById("edit-order-id").value;
+      const symbol = document.getElementById("edit-order-symbol").value;
+      const qty = parseInt(document.getElementById("edit-qty").value);
+      const price = parseFloat(document.getElementById("edit-price").value);
+
+      try {
+        const r = await fetch("/order/amend", {
+          method: "POST",
+          headers: {"Content-Type": "application/json"},
+          body: JSON.stringify({
+            orig_cl_ord_id: orderId,
+            symbol: symbol,
+            quantity: qty,
+            price: price
+          })
+        });
+        const result = await r.json();
+        if (result.status === "ok") {
+          alert("Order amended successfully");
+          closeModal();
+          renderOrderBookPanel();
+        } else {
+          alert("Amend failed: " + (result.error || "Unknown error"));
+        }
+      } catch (e) {
+        alert("Error: " + e.message);
+      }
+    }
+
+    async function cancelOrder(orderId, symbol) {
+      if (!confirm(`Cancel order ${orderId}?`)) return;
+
+      try {
+        const r = await fetch("/order/cancel", {
+          method: "POST",
+          headers: {"Content-Type": "application/json"},
+          body: JSON.stringify({
+            orig_cl_ord_id: orderId,
+            symbol: symbol
+          })
+        });
+        const result = await r.json();
+        if (result.status === "ok") {
+          alert("Order cancelled");
+          renderOrderBookPanel();
+        } else {
+          alert("Cancel failed: " + (result.error || "Unknown error"));
+        }
+      } catch (e) {
+        alert("Error: " + e.message);
+      }
+    }
+
+    function renderBBOs() {
+      const tbody = document.getElementById("bbos-body");
+      tbody.innerHTML = "";
+      for (const [symbol, snap] of Object.entries(state.bbos).sort()) {
+        const row = document.createElement("tr");
+        row.id = "bbo-" + symbol;
+        const spread = (snap.best_ask && snap.best_bid) ? (snap.best_ask - snap.best_bid).toFixed(2) : "-";
+        const mid = (snap.best_ask && snap.best_bid) ? ((snap.best_ask + snap.best_bid) / 2).toFixed(2) : "-";
+        row.innerHTML = `
+          <td><strong>${symbol}</strong></td>
+          <td style="color:green;">${snap.best_bid !== null ? Number(snap.best_bid).toFixed(2) : "-"}</td>
+          <td style="color:red;">${snap.best_ask !== null ? Number(snap.best_ask).toFixed(2) : "-"}</td>
+          <td>${spread}</td>
+          <td>${mid}</td>
+          <td>${snap.timestamp ? new Date(snap.timestamp*1000).toLocaleTimeString() : "-"}</td>
+        `;
+        tbody.appendChild(row);
+      }
+      updateSymbolDropdown();
+    }
+
+    function updateBBO(symbol, data) {
+      state.bbos[symbol] = data;
+      const row = document.getElementById("bbo-" + symbol);
+      if (row) {
+        const spread = (data.best_ask && data.best_bid) ? (data.best_ask - data.best_bid).toFixed(2) : "-";
+        const mid = (data.best_ask && data.best_bid) ? ((data.best_ask + data.best_bid) / 2).toFixed(2) : "-";
+        row.innerHTML = `
+          <td><strong>${symbol}</strong></td>
+          <td style="color:green;">${data.best_bid !== null ? Number(data.best_bid).toFixed(2) : "-"}</td>
+          <td style="color:red;">${data.best_ask !== null ? Number(data.best_ask).toFixed(2) : "-"}</td>
+          <td>${spread}</td>
+          <td>${mid}</td>
+          <td>${data.timestamp ? new Date(data.timestamp*1000).toLocaleTimeString() : "-"}</td>
+        `;
+        row.classList.add("updated");
+        setTimeout(() => row.classList.remove("updated"), 1000);
+      } else {
+        renderBBOs();
+      }
+    }
+
+    function updateSymbolDropdown() {
+      const symbols = Object.keys(state.bbos).sort();
+
+      // Update BBO symbol select
+      const bboSel = document.getElementById("bbo-symbol-select");
+      const bboCurrent = bboSel.value;
+      if (symbols.length > 0 && bboSel.options.length !== symbols.length) {
+        bboSel.innerHTML = "";
+        symbols.forEach(sym => {
+          const opt = document.createElement("option");
+          opt.value = sym;
+          opt.textContent = sym;
+          bboSel.appendChild(opt);
+        });
+        if (bboCurrent && symbols.includes(bboCurrent)) {
+          bboSel.value = bboCurrent;
+        }
+        renderOrderBookPanel();
+      }
+
+      // Update chart symbol select
+      const chartSel = document.getElementById("chart-symbol");
+      const chartCurrent = chartSel.value;
+      const existingOpts = Array.from(chartSel.options).map(o => o.value);
+      symbols.forEach(sym => {
+        if (!existingOpts.includes(sym)) {
+          const opt = document.createElement("option");
+          opt.value = sym;
+          opt.textContent = sym;
+          chartSel.appendChild(opt);
+        }
+      });
+      if (chartCurrent) chartSel.value = chartCurrent;
+    }
+
+    async function renderOrderBookPanel() {
+      const sel = document.getElementById("bbo-symbol-select");
+      const symbol = sel.value;
+      const container = document.getElementById("full-bbo-container");
+
+      if (!symbol) {
+        container.innerHTML = "<p style='color:#666; text-align:center;'>Select a symbol</p>";
+        return;
+      }
+
+      container.innerHTML = "<p style='color:#666; text-align:center;'>Loading...</p>";
+
+      try {
+        const r = await fetch(`/orderbook/${symbol}`);
+        const book = await r.json();
+        const bids = (book.bids || []).sort((a,b) => (b.price || 0) - (a.price || 0));
+        const asks = (book.asks || []).sort((a,b) => (a.price || 0) - (b.price || 0));
+
+        let html = `<div style="text-align:center; margin-bottom:10px; font-size:12px; color:#666;">
+          ${bids.length} bids | ${asks.length} asks
+        </div>`;
+
+        html += `<table style="width:100%; font-size:12px; border-collapse:collapse;">
+          <thead>
+            <tr style="background:#f0f0f0;">
+              <th style="padding:6px; border:1px solid #ddd; color:#2e7d32;">Bid Qty</th>
+              <th style="padding:6px; border:1px solid #ddd; color:#2e7d32;">Bid Price</th>
+              <th style="padding:6px; border:1px solid #ddd; color:#c62828;">Ask Price</th>
+              <th style="padding:6px; border:1px solid #ddd; color:#c62828;">Ask Qty</th>
+            </tr>
+          </thead>
+          <tbody>`;
+
+        const maxRows = Math.max(bids.length, asks.length, 1);
+        for (let i = 0; i < Math.min(maxRows, 20); i++) {
+          const b = bids[i] || {};
+          const a = asks[i] || {};
+          html += `<tr>
+            <td style="padding:4px 6px; border:1px solid #eee; color:#2e7d32; font-weight:bold; text-align:right;">${b.quantity ?? ""}</td>
+            <td style="padding:4px 6px; border:1px solid #eee; color:#2e7d32; text-align:right;">${b.price !== undefined ? Number(b.price).toFixed(2) : ""}</td>
+            <td style="padding:4px 6px; border:1px solid #eee; color:#c62828; text-align:left;">${a.price !== undefined ? Number(a.price).toFixed(2) : ""}</td>
+            <td style="padding:4px 6px; border:1px solid #eee; color:#c62828; font-weight:bold; text-align:left;">${a.quantity ?? ""}</td>
+          </tr>`;
+        }
+
+        html += `</tbody></table>`;
+
+        if (bids.length === 0 && asks.length === 0) {
+          html = "<p style='color:#666; text-align:center; margin-top:20px;'>No resting orders</p>";
+        }
+
+        container.innerHTML = html;
+      } catch (e) {
+        container.innerHTML = `<p style='color:red; text-align:center;'>Error: ${e.message}</p>`;
+      }
+    }
+
+    // Alias for backward compatibility
+    function renderFullBBO() { renderOrderBookPanel(); }
+
+    function renderPriceChart() {
+      const canvas = document.getElementById("price-chart");
+      const ctx = canvas.getContext("2d");
+      const selectedSymbol = document.getElementById("chart-symbol").value;
+
+      // Filter trades
+      let trades = state.trades.filter(t => !selectedSymbol || t.symbol === selectedSymbol);
+      trades = trades.slice(0, 100).reverse(); // Last 100, oldest first
+
+      if (trades.length === 0) {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.fillStyle = "#666";
+        ctx.font = "14px Arial";
+        ctx.textAlign = "center";
+        ctx.fillText("No trade data available", canvas.width / 2, canvas.height / 2);
+        return;
+      }
+
+      // Set canvas size
+      canvas.width = canvas.offsetWidth || 400;
+      canvas.height = canvas.offsetHeight || 300;
+
+      const padding = { top: 20, right: 60, bottom: 50, left: 60 };
+      const chartWidth = canvas.width - padding.left - padding.right;
+      const chartHeight = canvas.height - padding.top - padding.bottom;
+
+      // Calculate ranges
+      const prices = trades.map(t => t.price);
+      const volumes = trades.map(t => t.quantity || t.qty || 0);
+      const minPrice = Math.min(...prices) * 0.995;
+      const maxPrice = Math.max(...prices) * 1.005;
+      const maxVolume = Math.max(...volumes);
+
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+      // Draw grid
+      ctx.strokeStyle = "#eee";
+      ctx.lineWidth = 1;
+      for (let i = 0; i <= 5; i++) {
+        const y = padding.top + (chartHeight * i / 5);
+        ctx.beginPath();
+        ctx.moveTo(padding.left, y);
+        ctx.lineTo(canvas.width - padding.right, y);
+        ctx.stroke();
+      }
+
+      // Draw volume bars
+      const barWidth = Math.max(2, chartWidth / trades.length - 2);
+      ctx.fillStyle = "rgba(33, 150, 243, 0.3)";
+      trades.forEach((t, i) => {
+        const x = padding.left + (i / trades.length) * chartWidth;
+        const vol = t.quantity || t.qty || 0;
+        const barHeight = maxVolume > 0 ? (vol / maxVolume) * (chartHeight * 0.3) : 0;
+        ctx.fillRect(x, canvas.height - padding.bottom - barHeight, barWidth, barHeight);
+      });
+
+      // Draw price line
+      ctx.strokeStyle = "#4CAF50";
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      trades.forEach((t, i) => {
+        const x = padding.left + (i / trades.length) * chartWidth + barWidth / 2;
+        const y = padding.top + chartHeight - ((t.price - minPrice) / (maxPrice - minPrice)) * chartHeight;
+        if (i === 0) ctx.moveTo(x, y);
+        else ctx.lineTo(x, y);
+      });
+      ctx.stroke();
+
+      // Draw price points
+      ctx.fillStyle = "#4CAF50";
+      trades.forEach((t, i) => {
+        const x = padding.left + (i / trades.length) * chartWidth + barWidth / 2;
+        const y = padding.top + chartHeight - ((t.price - minPrice) / (maxPrice - minPrice)) * chartHeight;
+        ctx.beginPath();
+        ctx.arc(x, y, 3, 0, Math.PI * 2);
+        ctx.fill();
+      });
+
+      // Y-axis labels (price)
+      ctx.fillStyle = "#333";
+      ctx.font = "11px Arial";
+      ctx.textAlign = "right";
+      for (let i = 0; i <= 5; i++) {
+        const price = minPrice + (maxPrice - minPrice) * (5 - i) / 5;
+        const y = padding.top + (chartHeight * i / 5);
+        ctx.fillText(price.toFixed(2), padding.left - 5, y + 4);
+      }
+
+      // Legend
+      ctx.font = "12px Arial";
+      ctx.textAlign = "left";
+      ctx.fillStyle = "#4CAF50";
+      ctx.fillText("Price", padding.left, 12);
+      ctx.fillStyle = "rgba(33, 150, 243, 0.6)";
+      ctx.fillText("Volume", padding.left + 60, 12);
+      ctx.fillStyle = "#666";
+      ctx.fillText(`(${trades.length} trades${selectedSymbol ? " for " + selectedSymbol : ""})`, padding.left + 130, 12);
+    }
+
+    function renderOrderBook(book) {
+      const bids = (book.bids || []).sort((a,b) => (b.price || 0) - (a.price || 0));
+      const asks = (book.asks || []).sort((a,b) => (a.price || 0) - (b.price || 0));
+      const maxRows = Math.max(bids.length, asks.length, 1);
+      let html = "<table><tr><th>Bid Qty</th><th>Bid Price</th><th>Ask Price</th><th>Ask Qty</th></tr>";
+      for (let i = 0; i < maxRows; i++) {
+        const b = bids[i] || {};
+        const a = asks[i] || {};
+        html += `<tr>
+          <td style="color:green;">${b.quantity ?? ""}</td>
+          <td style="color:green;">${b.price !== undefined ? Number(b.price).toFixed(2) : ""}</td>
+          <td style="color:red;">${a.price !== undefined ? Number(a.price).toFixed(2) : ""}</td>
+          <td style="color:red;">${a.quantity ?? ""}</td>
+        </tr>`;
+      }
+      html += "</table>";
+      if (bids.length === 0 && asks.length === 0) {
+        html = "<p style='color:#666;text-align:center;margin-top:20px;'>No orders in book</p>";
+      }
+      return html;
+    }
+
+    function renderStats() {
+      // Calculate statistics from trades
+      const stats = {};
+      let maxVolume = 0;
+      let maxValue = 0;
+
+      for (const trade of state.trades) {
+        const sym = trade.symbol || "?";
+        if (!stats[sym]) {
+          stats[sym] = { trades: 0, volume: 0, totalValue: 0, startPrice: null, lastPrice: 0 };
+        }
+        const qty = trade.quantity || trade.qty || 0;
+        const price = trade.price || 0;
+        stats[sym].trades++;
+        stats[sym].volume += qty;
+        stats[sym].totalValue += qty * price;
+        if (stats[sym].startPrice === null) stats[sym].startPrice = price;
+        stats[sym].lastPrice = price;
+        if (stats[sym].volume > maxVolume) maxVolume = stats[sym].volume;
+        if (stats[sym].totalValue > maxValue) maxValue = stats[sym].totalValue;
+      }
+
+      // Render stats table
+      const tbody = document.getElementById("stats-body");
+      tbody.innerHTML = "";
+      const symbols = Object.keys(stats).sort();
+
+      for (const sym of symbols) {
+        const s = stats[sym];
+        const vwap = s.volume > 0 ? (s.totalValue / s.volume).toFixed(2) : "-";
+        const row = document.createElement("tr");
+        row.innerHTML = `
+          <td><strong>${sym}</strong></td>
+          <td>${s.trades}</td>
+          <td>${s.volume.toLocaleString()}</td>
+          <td>${s.totalValue.toLocaleString(undefined, {minimumFractionDigits:0, maximumFractionDigits:0})}</td>
+          <td>${s.startPrice !== null ? s.startPrice.toFixed(2) : "-"}</td>
+          <td>${s.lastPrice.toFixed(2)}</td>
+          <td>${vwap}</td>
+        `;
+        tbody.appendChild(row);
+      }
+
+      // Render grouped bar chart (Volume + Value side by side per symbol)
+      const statsChart = document.getElementById("stats-chart");
+      statsChart.innerHTML = "";
+
+      if (symbols.length === 0) {
+        statsChart.innerHTML = "<p style='color:#666; text-align:center; font-size:11px;'>No data</p>";
+        return;
+      }
+
+      for (const sym of symbols) {
+        const s = stats[sym];
+        const volPct = maxVolume > 0 ? (s.volume / maxVolume * 100) : 0;
+        const valPct = maxValue > 0 ? (s.totalValue / maxValue * 100) : 0;
+
+        const group = document.createElement("div");
+        group.style.cssText = "display:flex; flex-direction:column; align-items:center; gap:2px;";
+        group.innerHTML = `
+          <div style="display:flex; gap:2px; align-items:flex-end; height:80px;">
+            <div style="display:flex; flex-direction:column; align-items:center;">
+              <span style="font-size:9px; color:#4CAF50;">${s.volume >= 1000 ? (s.volume/1000).toFixed(1)+'k' : s.volume}</span>
+              <div style="width:20px; height:70px; background:#eee; border-radius:2px; display:flex; align-items:flex-end; overflow:hidden;">
+                <div style="width:100%; height:${volPct}%; background:linear-gradient(0deg, #4CAF50, #8BC34A);"></div>
+              </div>
+            </div>
+            <div style="display:flex; flex-direction:column; align-items:center;">
+              <span style="font-size:9px; color:#2196F3;">${s.totalValue >= 1000 ? (s.totalValue/1000).toFixed(1)+'k' : s.totalValue.toFixed(0)}</span>
+              <div style="width:20px; height:70px; background:#eee; border-radius:2px; display:flex; align-items:flex-end; overflow:hidden;">
+                <div style="width:100%; height:${valPct}%; background:linear-gradient(0deg, #2196F3, #64B5F6);"></div>
+              </div>
+            </div>
+          </div>
+          <span style="font-size:11px; font-weight:bold;">${sym}</span>
+        `;
+        statsChart.appendChild(group);
+      }
+    }
+
+    async function fetchOrderBook() {
+      // Deprecated - now using stats panel
+      renderStats();
+    }
+
+    // SSE Connection
+    let eventSource = null;
+    let reconnectTimeout = null;
+
+    function connectSSE() {
+      if (eventSource) {
+        eventSource.close();
+      }
+
+      setStatus("connecting", "Connecting...");
+      eventSource = new EventSource("/stream");
+
+      eventSource.addEventListener("connected", (e) => {
+        setStatus("connected", "Live");
+        state.connected = true;
+      });
+
+      eventSource.addEventListener("init", (e) => {
+        const data = JSON.parse(e.data);
+        state.orders = data.orders || [];
+        state.bbos = data.bbos || {};
+        state.trades = data.trades || [];
+        renderOrders();
+        renderTrades();
+        renderBBOs();
+        renderStats();
+        renderPriceChart();
+      });
+
+      eventSource.addEventListener("order", (e) => {
+        const order = JSON.parse(e.data);
+        state.orders.unshift(order);
+        if (state.orders.length > 50) state.orders.pop();
+        renderOrders();
+      });
+
+      eventSource.addEventListener("trade", (e) => {
+        const trade = JSON.parse(e.data);
+        state.trades.unshift(trade);
+        if (state.trades.length > 200) state.trades.pop();
+        renderTrades();
+        renderStats();
+        renderPriceChart();
+      });
+
+      eventSource.addEventListener("snapshot", (e) => {
+        const snap = JSON.parse(e.data);
+        updateBBO(snap.symbol, snap);
+      });
+
+      eventSource.onerror = () => {
+        setStatus("disconnected", "Disconnected");
+        state.connected = false;
+        eventSource.close();
+        // Reconnect after 3 seconds
+        reconnectTimeout = setTimeout(connectSSE, 3000);
+      };
+    }
+
+    // Fetch data from REST API
+    async function fetchData() {
+      try {
+        const r = await fetch("/data");
+        const data = await r.json();
+        state.orders = data.orders || [];
+        state.trades = data.trades || [];
+        state.bbos = data.bbos || {};
+        renderOrders();
+        renderTrades();
+        renderBBOs();
+        renderStats();
+        renderPriceChart();
+      } catch (e) {
+        console.error("Fetch data failed:", e);
+      }
+    }
+
+    // Initial load: fetch data via REST, then connect SSE
+    async function init() {
+      await fetchData();
+      connectSSE();
+
+      // Refresh order book panel every 3 seconds
+      setInterval(() => {
+        const sym = document.getElementById("bbo-symbol-select").value;
+        if (sym) renderOrderBookPanel();
+      }, 3000);
+
+      // Fallback: poll data every 5 seconds in case SSE fails
+      setInterval(fetchData, 5000);
+    }
+
+    init();
+  </script>
+</body>
+</html>

dashboard/templates/index_Matcher.html

@@ -0,0 +1,194 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8"/>
+  <title>Trading Dashboard</title>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; background: #f7f7f7; }
+    h2 { margin: 5px 0; }
+    .container { display: grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; }
+    .panel {
+      background: #fff;
+      border-radius: 8px;
+      padding: 10px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      height: 400px;
+      display: flex;
+      flex-direction: column;
+    }
+    .panel pre {
+      flex-grow: 1;
+      overflow-y: scroll;
+      background: #fafafa;
+      padding: 10px;
+      margin: 0;
+      border-radius: 6px;
+      font-size: 13px;
+      white-space: pre;
+      font-family: monospace;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13px;
+    }
+    th, td {
+      border: 1px solid #ccc;
+      padding: 4px;
+      text-align: center;
+    }
+    .updated {
+      animation: flash 1s ease-in-out;
+    }
+    @keyframes flash {
+      from { background: yellow; }
+      to   { background: transparent; }
+    }
+  </style>
+</head>
+<body>
+  <h1>📊 Trading Dashboard</h1>
+  <div class="container">
+    <div class="panel">
+      <h2>📝 Orders</h2>
+      <pre id="orders"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>💹 BBOs (from Order Book API)</h2>
+      <pre id="book"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>🤝 Trades</h2>
+      <pre id="trades"></pre>
+    </div>
+
+    <div class="panel">
+      <h2>📖 Full Order Book</h2>
+      <label for="symbol-select">Select symbol:</label>
+      <select id="symbol-select" onchange="refresh()"></select>
+      <div id="full-book" style="flex-grow:1; overflow-y:scroll;"></div>
+    </div>
+
+    <div class="panel">
+      <h2>📊 Market Snapshots (BBO)</h2>
+      <table id="bbos-table">
+        <thead>
+          <tr>
+            <th>Symbol</th>
+            <th>Best Bid</th>
+            <th>Best Ask</th>
+            <th>Timestamp</th>
+          </tr>
+        </thead>
+        <tbody id="bbos-body"></tbody>
+      </table>
+    </div>
+  </div>
+
+  <script>
+    function fmtOrder(o) {
+      const sym = o.symbol ?? "?";
+      const side = o.type ?? o.side ?? "?";
+      const price = o.price !== undefined ? Number(o.price).toFixed(2) : "?";
+      const qty = o.quantity ?? o.qty ?? "?";
+      return `${sym} | ${side} | ${qty} @ ${price}\n`;
+    }
+
+    function fmtTrade(t) {
+      const sym = (t.symbol ?? "?").padEnd(6);
+      const qty = String(t.quantity ?? t.qty ?? "-").padStart(6);
+      const price = t.price !== undefined ? Number(t.price).toFixed(2).padStart(8) : "   -   ";
+      const ts = t.timestamp ? new Date(t.timestamp * 1000).toLocaleTimeString() : "-";
+      return `${sym} | ${qty} x ${price} | ${ts}\n`;
+    }
+
+    function renderOrderBook(book) {
+      const bids = (book.buy || []).sort((a,b) => b.price - a.price);
+      const asks = (book.sell || []).sort((a,b) => a.price - b.price);
+      const maxRows = Math.max(bids.length, asks.length);
+      let html = "<table><tr><th>Bid Size</th><th>Bid Price</th><th>Ask Price</th><th>Ask Size</th></tr>";
+      for (let i=0; i<maxRows; i++) {
+        const b = bids[i] || {};
+        const a = asks[i] || {};
+        html += `<tr>
+          <td>${b.quantity ?? ""}</td>
+          <td>${b.price !== undefined ? Number(b.price).toFixed(2) : ""}</td>
+          <td>${a.price !== undefined ? Number(a.price).toFixed(2) : ""}</td>
+          <td>${a.quantity ?? ""}</td>
+        </tr>`;
+      }
+      html += "</table>";
+      return html;
+    }
+
+    async function refresh() {
+      try {
+        const r = await fetch("/data");
+        const data = await r.json();
+
+        // Orders
+        document.getElementById("orders").textContent =
+          data.orders.slice().reverse().map(fmtOrder).join("");
+
+        // Trades
+        document.getElementById("trades").textContent =
+          data.trades.slice().reverse().map(fmtTrade).join("");
+
+        // Book JSON dump
+        document.getElementById("book").textContent =
+          JSON.stringify(data.book, null, 2);
+
+        // Snapshots → fill table
+        const tbody = document.getElementById("bbos-body");
+        tbody.innerHTML = "";
+        for (const [symbol, snap] of Object.entries(data.bbos)) {
+          const row = document.createElement("tr");
+          row.innerHTML = `
+            <td>${symbol}</td>
+            <td>${snap.best_bid !== null ? Number(snap.best_bid).toFixed(2) : "-"}</td>
+            <td>${snap.best_ask !== null ? Number(snap.best_ask).toFixed(2) : "-"}</td>
+            <td>${snap.timestamp ? new Date(snap.timestamp*1000).toLocaleTimeString() : "-"}</td>
+          `;
+          row.classList.add("updated");
+          setTimeout(() => row.classList.remove("updated"), 1000);
+          tbody.appendChild(row);
+        }
+
+        // Populate dropdown once
+        const sel = document.getElementById("symbol-select");
+        if (!sel.options.length) {
+          const symbols = [...new Set([
+            ...Object.keys(data.bbos),
+            ...(data.book.buy || []).map(o => o.symbol),
+            ...(data.book.sell || []).map(o => o.symbol)
+          ])];
+          symbols.forEach(sym => {
+            const opt = document.createElement("option");
+            opt.value = sym;
+            opt.textContent = sym;
+            sel.appendChild(opt);
+          });
+        }
+
+        // Render order book for selected symbol
+        const sym = sel.value;
+        if (sym) {
+          const bookForSymbol = {
+            buy: (data.book.buy || []).filter(o => o.symbol === sym),
+            sell: (data.book.sell || []).filter(o => o.symbol === sym),
+          };
+          document.getElementById("full-book").innerHTML = renderOrderBook(bookForSymbol);
+        }
+
+      } catch(e) {
+        console.error("Refresh error", e);
+      }
+    }
+
+    setInterval(refresh, 2000);
+    refresh();
+  </script>
+</body>
+</html>

docker-compose.yml

@@ -0,0 +1,164 @@
+
+services:
+  # Build-only base image
+  fix-base:
+    build:
+      context: .
+      dockerfile: Dockerfile.base
+    image: fix-base
+    # No need to run a container for base
+    deploy:
+      replicas: 0
+
+  zookeeper:
+    image: confluentinc/cp-zookeeper:7.5.0
+    container_name: zookeeper
+    environment:
+      ZOOKEEPER_CLIENT_PORT: 2181
+      ZOOKEEPER_TICK_TIME: 2000
+    ports:
+      - "2181:2181"
+
+  kafka:
+    image: confluentinc/cp-kafka:7.5.0
+    container_name: kafka
+    depends_on:
+      - zookeeper
+    ports:
+      - "9092:9092"   # for containers & optionally host
+      - "29092:29092" # for host access
+    environment:
+      KAFKA_BROKER_ID: 1
+      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
+      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,PLAINTEXT_HOST://0.0.0.0:29092
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092
+      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+
+  matcher:
+    build: ./matcher
+    container_name: matcher
+    depends_on:
+      - kafka
+    ports:
+      - "6000:6000"
+    volumes:
+      - ./shared:/app/shared
+      - matcher_data:/app/data  # SQLite database persistence
+
+  frontend:
+    build: ./frontend
+    container_name: frontend
+    depends_on:
+      - matcher
+      - kafka
+    ports:
+      - "5000:5000"
+    volumes:
+      - ./shared:/app/shared
+    environment:
+      - MATCHER_URL=http://matcher:6000
+
+  consumer:
+    build: ./consumer
+    container_name: consumer
+    depends_on:
+      - kafka
+    volumes:
+      - ./shared:/app/shared
+
+  md_feeder:
+    build:
+      context: ./md_feeder
+      dockerfile: Dockerfile
+    volumes:
+      - ./shared_data:/app/data   # shared volume for global order IDs
+      - ./shared:/app/shared
+
+  oeg:
+    build: ./oeg
+    container_name: oeg
+    environment:
+      - FRONTEND_URL=http://frontend:5000
+    command: ["python","oeg_simulator.py"]
+    depends_on:
+      - frontend
+    networks:
+      - default
+
+  fix_oeg:
+    build: ./fix_oeg
+    container_name: fix_oeg
+    depends_on:
+      - kafka
+    ports:
+      - "5001:5001"
+    volumes:
+      - ./shared:/app/shared
+    networks:
+      - default
+
+  snapshot_viewer:
+    build: ./snapshot_viewer
+    #dockerfile: snapshot_viewer/Dockerfile
+    volumes:
+      - ./logs:/app/logs   # logs will appear in ./logs folder on your host
+      - ./shared:/app/shared
+    depends_on:
+      - kafka
+      - md_feeder
+    networks:
+      - default
+          
+  fix-ui-client-1:
+    build:
+      context: ./fix-ui-client
+    container_name: fix-ui-client-1
+    ports:
+      - "5002:5002"
+    volumes:
+      - ./fix-ui-client/client1.cfg:/app/client.cfg
+      - ./fix-ui-client/log:/app/log
+      - ./fix-ui-client/store:/app/store
+      - ./shared_data:/app/data   # shared volume for global order IDs
+      - ./shared:/app/shared
+    environment:
+      FIX_CFG: client.cfg
+    depends_on:
+      - fix_oeg
+
+  fix-ui-client-2:
+    build:
+      context: ./fix-ui-client
+    container_name: fix-ui-client-2
+    ports:
+      - "5003:5002"
+    volumes:
+      - ./fix-ui-client/client2.cfg:/app/client.cfg
+      - ./fix-ui-client/log:/app/log
+      - ./fix-ui-client/store:/app/store
+      - ./shared_data:/app/data   # shared volume for global order IDs
+      - ./shared:/app/shared
+    environment:
+      FIX_CFG: client.cfg
+    depends_on:
+      - fix_oeg
+
+  dashboard:
+    build:
+      context: ./dashboard
+    container_name: dashboard
+    ports:
+      - "5005:5000"
+    volumes:
+      - ./dashboard:/app
+      - ./shared:/app/shared
+    depends_on:
+      - kafka
+      - matcher
+    environment:
+      - MATCHER_URL=http://matcher:6000
+
+volumes:
+  matcher_data:  # Persists SQLite database across container restarts

fix-ui-client/Dockerfile

@@ -0,0 +1,12 @@
+FROM fix-base
+
+WORKDIR /app
+COPY . /app
+
+# Make sure store/ and log/ exist
+RUN mkdir -p /app/store /app/log
+
+# Install specific deps
+RUN pip install --no-cache-dir kafka-python requests
+
+CMD ["python", "fix-ui-client.py"]

fix-ui-client/client1.cfg

@@ -0,0 +1,21 @@
+[DEFAULT]
+ConnectionType=initiator
+StartTime=00:00:00
+EndTime=23:59:59
+UseLocalTime=Y
+HeartBtInt=30
+FileStorePath=store
+FileLogPath=log
+UseDataDictionary=N
+DataDictionary=FIX44.xml
+ReconnectInterval=5
+ResetOnLogon=Y
+ResetOnLogout=Y
+ResetOnDisconnect=Y
+
+[SESSION]
+BeginString=FIX.4.4
+SenderCompID=CLIENT1
+TargetCompID=FIX_SERVER
+SocketConnectHost=fix_oeg
+SocketConnectPort=5001

fix-ui-client/client2.cfg

@@ -0,0 +1,22 @@
+[DEFAULT]
+ConnectionType=initiator
+StartTime=00:00:00
+EndTime=23:59:59
+UseLocalTime=Y
+HeartBtInt=30
+FileStorePath=store
+FileLogPath=log
+UseDataDictionary=N
+DataDictionary=FIX44.xml
+ReconnectInterval=5
+ResetOnLogon=Y
+ResetOnLogout=Y
+ResetOnDisconnect=Y
+
+[SESSION]
+BeginString=FIX.4.4
+SenderCompID=CLIENT2
+TargetCompID=FIX_SERVER
+SocketConnectHost=fix_oeg
+SocketConnectPort=5001
+

fix-ui-client/fix-ui-client.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+import sys
+sys.path.insert(0, "/app")
+
+import quickfix as fix
+import quickfix44 as fix44
+from flask import Flask, render_template, request, redirect, url_for, jsonify
+import json
+import threading, time, os
+from collections import deque
+from threading import Lock
+
+from shared.config import Config
+from shared.kafka_utils import create_producer
+
+app = Flask(__name__)
+
+fix_initiator = None
+fix_app = None
+_messages = deque(maxlen=500)
+_msgs_lock = Lock()
+
+# --- Global OrderID counter ---
+LOCK = threading.Lock()
+
+def next_order_id():
+    os.makedirs(os.path.dirname(Config.ORDER_ID_FILE), exist_ok=True)
+
+    with LOCK:  # thread safety inside container
+        if not os.path.exists(Config.ORDER_ID_FILE):
+            with open(Config.ORDER_ID_FILE, "w") as f:
+                f.write("0")
+
+        with open(Config.ORDER_ID_FILE, "r+") as f:
+            current = int(f.read().strip() or 0)
+            new_id = current + 1
+            f.seek(0)
+            f.write(str(new_id))
+            f.truncate()
+
+    return new_id
+
+
+def log(msg: str):
+    with _msgs_lock:
+        _messages.append(msg)
+
+class FixUIClientApp(fix.Application):
+    def __init__(self):
+        super().__init__()
+        self.sessionID = None
+        self.connected = False
+        self.producer = create_producer(component_name="FIX-UI-Client")
+
+    def onCreate(self, sessionID): self.sessionID = sessionID
+    def onLogon(self, sessionID):
+        self.connected = True
+        self.sessionID = sessionID
+        log(f"✅ Logon: {sessionID}")
+    def onLogout(self, sessionID):
+        self.connected = False
+        log(f"❌ Logout: {sessionID}")
+
+    def toAdmin(self, message, sessionID): pass
+    def fromAdmin(self, message, sessionID): pass
+
+    def toApp(self, message, sessionID):
+        log(f"➡️ Sent App: {message.toString()}")
+
+    def fromApp(self, message, sessionID):
+        msg_type = fix.MsgType()
+        message.getHeader().getField(msg_type)
+        if msg_type.getValue() == fix.MsgType_ExecutionReport:
+            execType, ordStatus, clOrdID = fix.ExecType(), fix.OrdStatus(), fix.ClOrdID()
+            try: message.getField(execType)
+            except: pass
+            try: message.getField(ordStatus)
+            except: pass
+            try: message.getField(clOrdID)
+            except: pass
+
+            status_map = {
+                fix.ExecType_NEW: "New",
+                fix.ExecType_PARTIAL_FILL: "Partial Fill",
+                fix.ExecType_FILL: "Fill",
+                fix.ExecType_CANCELED: "Canceled",
+                fix.ExecType_REPLACED: "Replaced",
+                fix.ExecType_REJECTED: "Rejected",
+            }
+            status = status_map.get(execType.getValue(), f"ExecType={execType.getValue()}")
+            log(f"📥 ExecReport: ClOrdID={clOrdID.getValue() if clOrdID else '?'} Status={status}")
+        else:
+            log(f"📩 App: {message.toString()}")
+
+    def send_order(self, side, symbol, qty, price):
+        if not self.sessionID:
+            return "⚠️ No FIX session active"
+
+        order = fix44.NewOrderSingle()
+        cl_ord_id = next_order_id()
+        order.setField(fix.ClOrdID(str(cl_ord_id)))
+        order.setField(fix.HandlInst('1'))
+        order.setField(fix.Symbol(symbol))
+        order.setField(fix.Side(side))
+        order.setField(fix.TransactTime())
+        order.setField(fix.OrdType(fix.OrdType_LIMIT))
+        order.setField(fix.OrderQty(qty))
+        order.setField(fix.Price(price))
+
+        fix.Session.sendToTarget(order, self.sessionID)
+        log(f"📤 Sent Order (ID={cl_ord_id}): {order.toString()}")
+        
+        # 🔥 Publish to Kafka
+        self.producer.send(Config.ORDERS_TOPIC,
+        {
+            "id": cl_ord_id,
+            "symbol": symbol,
+            "side": "buy" if side == "1" else "sell",
+            "qty": qty,
+            "price": price,
+            "timestamp": time.time(),
+        })
+
+        return "Order sent!"
+     
+# --- FIX lifecycle ---
+def start_fix():
+    global fix_initiator, fix_app
+    if fix_initiator is not None:
+        log("ℹ️ FIX already starting/started")
+        return
+    settings = fix.SessionSettings(CONFIG_FILE)
+    fix_app = FixUIClientApp()
+    store = fix.FileStoreFactory(settings)
+    logfile = fix.FileLogFactory(settings)
+    fix_initiator = fix.SocketInitiator(fix_app, store, settings, logfile)
+    fix_initiator.start()
+    log(f"🔌 FIX initiator started with {CONFIG_FILE}")
+
+def stop_fix():
+    global fix_initiator
+    if fix_initiator:
+        fix_initiator.stop()
+        log("🪫 FIX initiator stopped")
+        fix_initiator = None
+
+# --- Flask routes ---
+@app.route("/")
+def index():
+    with _msgs_lock:
+        msgs = list(reversed(_messages))   # newest first
+    connected = bool(fix_app and fix_app.connected)
+    return render_template("index.html", messages=msgs, connected=connected)
+
+@app.route("/status")
+def status():
+    return jsonify({"connected": bool(fix_app and fix_app.connected)})
+
+@app.route("/connect")
+def connect():
+    threading.Thread(target=start_fix, daemon=True).start()
+    return redirect(url_for("index"))
+
+@app.route("/disconnect")
+def disconnect():
+    stop_fix()
+    return redirect(url_for("index"))
+
+@app.route("/order", methods=["POST"])
+def order():
+    if not fix_app or not fix_app.connected:
+        log("⚠️ Tried to send while disconnected")
+        return redirect(url_for("index"))
+    side = request.form.get("side", "buy")
+    side_tag = "1" if side.lower() == "buy" else "2"
+    symbol = request.form.get("symbol", "FOO")
+    qty = float(request.form.get("qty", "100"))
+    price = float(request.form.get("price", "10"))
+    fix_app.send_order(side_tag, symbol, qty, price)
+    return redirect(url_for("index"))
+
+# --- Configurable ---
+CONFIG_FILE = os.getenv("FIX_CONFIG", "client.cfg")
+PORT = int(os.getenv("UI_PORT", "5002"))
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=PORT, debug=True)

fix-ui-client/templates/index.html

@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>FIX UI Client</title>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; background: #f7f7f7; }
+    h1 { display: flex; align-items: center; gap: 15px; margin-bottom: 20px; }
+    h2 { margin: 5px 0 10px; font-size: 16px; }
+    .container { display: grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; }
+
+    .panel {
+      background: #fff;
+      border-radius: 8px;
+      padding: 15px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      display: flex;
+      flex-direction: column;
+      min-height: 400px;
+    }
+
+    /* Status badge */
+    .status {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 12px;
+      border-radius: 20px;
+      font-size: 12px;
+      font-weight: bold;
+    }
+    .status .dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+    }
+    .status.connected { background: #d4edda; color: #155724; }
+    .status.connected .dot { background: #28a745; }
+    .status.disconnected { background: #f8d7da; color: #721c24; }
+    .status.disconnected .dot { background: #dc3545; }
+
+    /* Buttons */
+    .btn-group { display: flex; gap: 8px; margin-top: 10px; }
+    .btn {
+      padding: 7px 18px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 13px;
+      font-weight: bold;
+      text-decoration: none;
+      display: inline-block;
+    }
+    .btn-connect { background: #28a745; color: #fff; }
+    .btn-connect:hover { background: #218838; }
+    .btn-disconnect { background: #dc3545; color: #fff; }
+    .btn-disconnect:hover { background: #c82333; }
+
+    /* Divider */
+    .divider { border: none; border-top: 1px solid #eee; margin: 15px 0; }
+
+    /* Order form */
+    .form-group { margin-bottom: 12px; }
+    .form-group label { display: block; font-size: 12px; color: #666; margin-bottom: 4px; }
+    .form-group input,
+    .form-group select {
+      width: 100%;
+      padding: 8px;
+      border: 1px solid #ccc;
+      border-radius: 4px;
+      font-size: 13px;
+      box-sizing: border-box;
+    }
+    .form-group select option[value="buy"]  { color: #2e7d32; }
+    .form-group select option[value="sell"] { color: #c62828; }
+    .btn-send {
+      width: 100%;
+      padding: 10px;
+      background: #2196F3;
+      color: #fff;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 14px;
+      font-weight: bold;
+    }
+    .btn-send:hover { background: #1976D2; }
+
+    /* Messages box */
+    .messages-box {
+      flex-grow: 1;
+      overflow-y: auto;
+      background: #1a1a2e;
+      color: #e0e0e0;
+      padding: 12px;
+      border-radius: 6px;
+      font-family: monospace;
+      font-size: 12px;
+      white-space: pre-wrap;
+      line-height: 1.5;
+      min-height: 300px;
+    }
+  </style>
+</head>
+<body>
+
+  <h1>
+    FIX UI Client
+    <span class="status {{ 'connected' if connected else 'disconnected' }}">
+      <span class="dot"></span>
+      <span>{{ 'CONNECTED' if connected else 'DISCONNECTED' }}</span>
+    </span>
+  </h1>
+
+  <div class="container">
+
+    <!-- Left panel: Connection + Order form -->
+    <div class="panel">
+      <h2>Connection</h2>
+      <div class="btn-group">
+        <a href="{{ url_for('connect') }}" class="btn btn-connect">Connect</a>
+        <a href="{{ url_for('disconnect') }}" class="btn btn-disconnect">Disconnect</a>
+      </div>
+
+      <hr class="divider">
+
+      <h2>Send Order</h2>
+      <form action="{{ url_for('order') }}" method="post">
+        <div class="form-group">
+          <label>Side</label>
+          <select name="side">
+            <option value="buy">BUY</option>
+            <option value="sell">SELL</option>
+          </select>
+        </div>
+        <div class="form-group">
+          <label>Symbol</label>
+          <input type="text" name="symbol" value="AAPL">
+        </div>
+        <div class="form-group">
+          <label>Quantity</label>
+          <input type="number" step="1" name="qty" value="100">
+        </div>
+        <div class="form-group">
+          <label>Price</label>
+          <input type="number" step="0.01" name="price" value="150.00">
+        </div>
+        <button type="submit" class="btn-send">Send Order</button>
+      </form>
+    </div>
+
+    <!-- Right panel: Messages log -->
+    <div class="panel">
+      <h2>Messages <span style="font-size:12px; color:#999; font-weight:normal;">FIX Session Log</span></h2>
+      <div class="messages-box">{% for msg in messages %}{{ msg }}
+{% endfor %}</div>
+    </div>
+
+  </div>
+
+</body>
+</html>

fix_oeg/Dockerfile

@@ -0,0 +1,45 @@
+# Stage 1: Build stage with all dependencies
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    build-essential \
+    libssl-dev \
+    zlib1g-dev \
+    libbz2-dev \
+    libreadline-dev \
+    libsqlite3-dev \
+    wget \
+    curl \
+    llvm \
+    libncurses5-dev \
+    libncursesw5-dev \
+    xz-utils \
+    tk-dev \
+    libffi-dev \
+    liblzma-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# Stage 2: Runtime image
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy only the necessary files from builder
+COPY --from=builder /root/.local /root/.local
+COPY fix_oeg_server.py fix_server.cfg ./
+
+COPY FIX44.xml .
+
+# Ensure scripts in .local are usable
+ENV PATH=/root/.local/bin:$PATH
+
+EXPOSE 5001
+CMD ["python", "fix_oeg_server.py"]

fix_oeg/fix_oeg_server.py

@@ -0,0 +1,341 @@
+import sys
+sys.path.insert(0, "/app")
+
+import time, json, threading, uuid
+import quickfix as fix
+import quickfix44 as fix44
+
+from shared.config import Config
+from shared.kafka_utils import create_producer, create_consumer
+
+# Order tracking for execution reports
+order_sessions = {}  # cl_ord_id -> (sessionID, order_details)
+order_sessions_lock = threading.Lock()
+
+class Application(fix.Application):
+    def __init__(self):
+        super().__init__()
+        self.producer = create_producer(component_name="FIX-OEG")
+        self.sessions = {}  # sessionID -> session for sending messages
+
+    def onCreate(self, sessionID):
+        print("FIX-OEG onCreate:", sessionID)
+        self.sessions[sessionID] = sessionID
+
+    def onLogon(self, sessionID):
+        print("FIX-OEG onLogon:", sessionID)
+
+    def onLogout(self, sessionID):
+        print("FIX-OEG onLogout:", sessionID)
+        if sessionID in self.sessions:
+            del self.sessions[sessionID]
+
+    def toAdmin(self, message, sessionID): pass
+    def fromAdmin(self, message, sessionID): pass
+    def toApp(self, message, sessionID): pass
+
+    def fromApp(self, message, sessionID):
+        msgType = fix.MsgType()
+        message.getHeader().getField(msgType)
+        mtype = msgType.getValue()
+        if mtype == fix.MsgType_NewOrderSingle:
+            self.onNewOrderSingle(message, sessionID)
+        elif mtype == fix.MsgType_OrderCancelRequest:
+            self.onOrderCancelRequest(message, sessionID)
+        elif mtype == fix.MsgType_OrderCancelReplaceRequest:
+            self.onOrderCancelReplaceRequest(message, sessionID)
+        else:
+            print("FIX-OEG: Unsupported MsgType:", mtype)
+            self.sendReject(sessionID, message, f"Unsupported message type: {mtype}")
+
+    def validateNewOrderSingle(self, message):
+        """Validate required fields for NewOrderSingle. Returns (valid, error_msg)."""
+        errors = []
+
+        def gf(tag, name):
+            try:
+                return message.getField(tag)
+            except Exception:
+                return None
+
+        # Required fields
+        cl_ord_id = gf(11, "ClOrdID")
+        symbol = gf(55, "Symbol")
+        side = gf(54, "Side")
+        qty = gf(38, "OrderQty")
+
+        if not cl_ord_id:
+            errors.append("Missing required field ClOrdID (11)")
+        if not symbol:
+            errors.append("Missing required field Symbol (55)")
+        if not side:
+            errors.append("Missing required field Side (54)")
+        elif side not in ("1", "2"):
+            errors.append(f"Invalid Side (54): must be 1 (Buy) or 2 (Sell), got {side}")
+        if not qty:
+            errors.append("Missing required field OrderQty (38)")
+        else:
+            try:
+                qty_val = float(qty)
+                if qty_val <= 0:
+                    errors.append(f"OrderQty (38) must be positive, got {qty_val}")
+            except ValueError:
+                errors.append(f"Invalid OrderQty (38): {qty}")
+
+        # Price validation for limit orders
+        ord_type = gf(40, "OrdType")
+        if ord_type == "2":  # Limit order
+            price = gf(44, "Price")
+            if not price:
+                errors.append("Missing Price (44) for limit order")
+            else:
+                try:
+                    if float(price) <= 0:
+                        errors.append(f"Price (44) must be positive, got {price}")
+                except ValueError:
+                    errors.append(f"Invalid Price (44): {price}")
+
+        return (len(errors) == 0, "; ".join(errors))
+
+    def sendReject(self, sessionID, original_msg, reason):
+        """Send a Reject message (35=3) for invalid messages."""
+        reject = fix.Message()
+        reject.getHeader().setField(fix.MsgType(fix.MsgType_Reject))
+        reject.setField(fix.RefSeqNum(0))  # Reference sequence number
+        reject.setField(fix.Text(reason))
+        try:
+            fix.Session.sendToTarget(reject, sessionID)
+            print(f"FIX-OEG: Sent Reject: {reason}")
+        except Exception as e:
+            print(f"FIX-OEG: Failed to send Reject: {e}")
+
+    def sendExecutionReport(self, sessionID, order, exec_type, ord_status,
+                           exec_qty=0, exec_price=0, cum_qty=0, leaves_qty=0):
+        """Send an ExecutionReport (35=8)."""
+        exec_report = fix.Message()
+        exec_report.getHeader().setField(fix.MsgType(fix.MsgType_ExecutionReport))
+
+        # Required fields
+        exec_report.setField(fix.OrderID(order.get('order_id', str(uuid.uuid4()))))
+        exec_report.setField(fix.ClOrdID(order.get('cl_ord_id', '')))
+        exec_report.setField(fix.ExecID(str(uuid.uuid4())))
+        exec_report.setField(fix.ExecType(exec_type))
+        exec_report.setField(fix.OrdStatus(ord_status))
+        exec_report.setField(fix.Symbol(order.get('symbol', '')))
+        exec_report.setField(fix.Side(fix.Side_BUY if order.get('type') == 'buy' else fix.Side_SELL))
+        exec_report.setField(fix.OrderQty(order.get('quantity', 0)))
+
+        if order.get('price'):
+            exec_report.setField(fix.Price(order.get('price')))
+
+        # Fill information
+        exec_report.setField(fix.LastShares(exec_qty))
+        exec_report.setField(fix.LastPx(exec_price))
+        exec_report.setField(fix.CumQty(cum_qty))
+        exec_report.setField(fix.LeavesQty(leaves_qty))
+        exec_report.setField(fix.AvgPx(exec_price if cum_qty > 0 else 0))
+
+        try:
+            fix.Session.sendToTarget(exec_report, sessionID)
+            print(f"FIX-OEG: Sent ExecutionReport: ExecType={exec_type}, OrdStatus={ord_status}")
+        except Exception as e:
+            print(f"FIX-OEG: Failed to send ExecutionReport: {e}")
+
+    def onNewOrderSingle(self, message, sessionID):
+        # Validate message first
+        valid, error_msg = self.validateNewOrderSingle(message)
+        if not valid:
+            self.sendReject(sessionID, message, error_msg)
+            return
+
+        def gf(tag, default=None, cast=str):
+            try:
+                return cast(message.getField(tag))
+            except Exception:
+                return default
+
+        cl_ord_id = gf(11)
+        symbol    = gf(55, "FOO")
+        side_val  = gf(54, "1")  # 1=Buy, 2=Sell
+        qty       = gf(38, 0.0, float)
+        price     = gf(44, 0.0, float)
+
+        order_id = cl_ord_id or f"fix-{int(time.time()*1000)}"
+        order = {
+            "order_id": order_id,
+            "cl_ord_id": cl_ord_id,
+            "symbol": symbol,
+            "type": "buy" if str(side_val) == "1" else "sell",
+            "quantity": qty,
+            "price": price,
+            "timestamp": time.time(),
+            "source": "fix-oeg"
+        }
+
+        # Track order for execution reports
+        with order_sessions_lock:
+            order_sessions[cl_ord_id] = (sessionID, order)
+
+        try:
+            meta = self.producer.send(Config.ORDERS_TOPIC, value=order).get(timeout=10)
+            print(f"📥 FIX → Kafka: {order}")
+            print(json.dumps({"component":"fix-oeg","event":"order_received","payload":{"order":order,"topic":meta.topic,"partition":meta.partition,"offset":meta.offset}}))
+
+            # Send Execution Report: New (ExecType=0, OrdStatus=0)
+            self.sendExecutionReport(
+                sessionID, order,
+                exec_type=fix.ExecType_NEW,
+                ord_status=fix.OrdStatus_NEW,
+                leaves_qty=qty
+            )
+        except Exception as e:
+            print(json.dumps({"component":"fix-oeg","event":"produce_failed","payload":{"order":order,"error":str(e)}}))
+
+    def onOrderCancelRequest(self, message, sessionID):
+        """Handle Order Cancel Request (35=F)."""
+        def gf(tag, default=None):
+            try:
+                return message.getField(tag)
+            except Exception:
+                return default
+
+        orig_cl_ord_id = gf(41)  # OrigClOrdID
+        cl_ord_id = gf(11)  # ClOrdID (for cancel request)
+        symbol = gf(55)
+
+        if not orig_cl_ord_id:
+            self.sendReject(sessionID, message, "Missing OrigClOrdID (41)")
+            return
+
+        cancel_msg = {
+            "type": "cancel",
+            "orig_cl_ord_id": orig_cl_ord_id,
+            "cl_ord_id": cl_ord_id,
+            "symbol": symbol,
+            "timestamp": time.time(),
+            "source": "fix-oeg"
+        }
+
+        try:
+            self.producer.send(Config.ORDERS_TOPIC, value=cancel_msg).get(timeout=10)
+            print(f"📥 FIX Cancel → Kafka: {cancel_msg}")
+        except Exception as e:
+            print(f"FIX-OEG: Failed to send cancel: {e}")
+
+    def onOrderCancelReplaceRequest(self, message, sessionID):
+        """Handle Order Cancel/Replace Request (35=G) - amend order price/quantity."""
+        def gf(tag, default=None, cast=str):
+            try:
+                return cast(message.getField(tag))
+            except Exception:
+                return default
+
+        orig_cl_ord_id = gf(41)  # OrigClOrdID - order to modify
+        cl_ord_id = gf(11)  # ClOrdID - new ID for modified order
+        symbol = gf(55)
+        side = gf(54)
+        new_qty = gf(38, 0.0, float)  # New OrderQty
+        new_price = gf(44, 0.0, float)  # New Price
+
+        if not orig_cl_ord_id:
+            self.sendReject(sessionID, message, "Missing OrigClOrdID (41)")
+            return
+
+        amend_msg = {
+            "type": "amend",
+            "orig_cl_ord_id": orig_cl_ord_id,
+            "cl_ord_id": cl_ord_id,
+            "symbol": symbol,
+            "side": "buy" if str(side) == "1" else "sell",
+            "quantity": new_qty,
+            "price": new_price,
+            "timestamp": time.time(),
+            "source": "fix-oeg"
+        }
+
+        # Track for execution reports
+        with order_sessions_lock:
+            order_sessions[cl_ord_id] = (sessionID, amend_msg)
+
+        try:
+            self.producer.send(Config.ORDERS_TOPIC, value=amend_msg).get(timeout=10)
+            print(f"📥 FIX Amend → Kafka: {amend_msg}")
+        except Exception as e:
+            print(f"FIX-OEG: Failed to send amend: {e}")
+
+
+def start_trades_consumer(app):
+    """Consume trades from Kafka and send execution reports to FIX clients."""
+    try:
+        consumer = create_consumer(
+            topics=[Config.TRADES_TOPIC],
+            group_id="fix-oeg-execreports",
+            component_name="FIX-OEG-TradesConsumer"
+        )
+    except Exception as e:
+        print(f"FIX-OEG: Failed to create trades consumer: {e}")
+        return
+
+    for msg in consumer:
+        try:
+            trade = msg.value
+            buy_id = trade.get('buy_id')
+            sell_id = trade.get('sell_id')
+            price = trade.get('price', 0)
+            qty = trade.get('quantity', 0)
+
+            # Send fill report to buyer
+            with order_sessions_lock:
+                if buy_id and buy_id in order_sessions:
+                    session_id, order = order_sessions[buy_id]
+                    # Calculate remaining quantity (simplified - would need proper tracking)
+                    app.sendExecutionReport(
+                        session_id, order,
+                        exec_type=fix.ExecType_TRADE,
+                        ord_status=fix.OrdStatus_FILLED,  # Simplified: assume full fill
+                        exec_qty=qty,
+                        exec_price=price,
+                        cum_qty=qty,
+                        leaves_qty=0
+                    )
+                    print(f"FIX-OEG: Sent fill report to buyer {buy_id}")
+
+                # Send fill report to seller
+                if sell_id and sell_id in order_sessions:
+                    session_id, order = order_sessions[sell_id]
+                    app.sendExecutionReport(
+                        session_id, order,
+                        exec_type=fix.ExecType_TRADE,
+                        ord_status=fix.OrdStatus_FILLED,
+                        exec_qty=qty,
+                        exec_price=price,
+                        cum_qty=qty,
+                        leaves_qty=0
+                    )
+                    print(f"FIX-OEG: Sent fill report to seller {sell_id}")
+
+        except Exception as e:
+            print(f"FIX-OEG: Error processing trade: {e}")
+
+
+if __name__ == "__main__":
+    settings = fix.SessionSettings("fix_server.cfg")
+    app = Application()
+    store_factory = fix.FileStoreFactory(settings)
+    log_factory = fix.FileLogFactory(settings)
+    acceptor = fix.SocketAcceptor(app, store_factory, settings, log_factory)
+    acceptor.start()
+    print("FIX OEG Gateway listening on 0.0.0.0:5001 (FIX 4.4)")
+
+    # Start trades consumer for execution reports
+    trades_thread = threading.Thread(target=start_trades_consumer, args=(app,), daemon=True)
+    trades_thread.start()
+    print("FIX-OEG: Started trades consumer for execution reports")
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        acceptor.stop()

fix_oeg/fix_server.cfg

@@ -0,0 +1,27 @@
+[DEFAULT]
+ConnectionType=acceptor
+SocketAcceptPort=5001
+SocketReuseAddress=Y
+StartTime=00:00:00
+EndTime=23:59:59
+UseLocalTime=Y
+UseDataDictionary=Y
+DataDictionary=FIX44.xml
+FileStorePath=store
+FileLogPath=log
+HeartBtInt=30
+ValidateUserDefinedFields=N
+ResetOnLogon=Y
+ResetOnLogout=Y
+ResetOnDisconnect=Y
+
+[SESSION]
+BeginString=FIX.4.4
+SenderCompID=FIX_SERVER
+TargetCompID=CLIENT1
+
+[SESSION]
+BeginString=FIX.4.4
+SenderCompID=FIX_SERVER
+TargetCompID=CLIENT2
+

fix_oeg/requirements.txt

@@ -0,0 +1,2 @@
+quickfix
+kafka-python

frontend/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY frontend.py .
+COPY templates templates
+CMD ["python", "frontend.py"]

frontend/frontend.py

@@ -0,0 +1,98 @@
+import sys
+sys.path.insert(0, "/app")
+
+from flask import Flask, request, jsonify, render_template
+import json, time, os
+
+from shared.config import Config
+from shared.kafka_utils import create_producer
+
+app = Flask(__name__, template_folder='templates')
+
+producer = create_producer(component_name="Frontend")
+
+@app.route('/')
+def index():
+    return render_template('index.html')
+
+@app.route('/health')
+def health():
+    """Health check endpoint."""
+    import requests
+    status = {
+        "status": "healthy",
+        "service": "frontend",
+        "timestamp": time.time()
+    }
+    # Check Kafka producer
+    try:
+        producer.flush(timeout=1)
+        status["kafka"] = "connected"
+    except Exception as e:
+        status["kafka"] = f"error: {e}"
+        status["status"] = "degraded"
+
+    # Check matcher connectivity
+    try:
+        r = requests.get(f"{Config.MATCHER_URL}/health", timeout=2)
+        if r.status_code == 200:
+            status["matcher"] = "connected"
+        else:
+            status["matcher"] = f"error: status {r.status_code}"
+    except Exception as e:
+        status["matcher"] = f"error: {e}"
+
+    return jsonify(status)
+
+@app.route('/order', methods=['POST'])
+def send_order():
+    if request.is_json:
+        data = request.json
+    else:
+        data = {
+            'order_id': request.form.get('order_id') or str(time.time_ns()),
+            'symbol': request.form.get('symbol'),
+            'type': request.form.get('type'),
+            'quantity': int(request.form.get('quantity')),
+            'price': float(request.form.get('price')),
+            'timestamp': time.time()
+        }
+    producer.send(Config.ORDERS_TOPIC, value=data)
+    producer.flush()
+    return jsonify({'status':'sent','data':data})
+
+@app.route('/book')
+def book():
+    import requests
+    r = requests.get(f"{Config.MATCHER_URL}/book", timeout=2)
+    return (r.text, r.status_code, {'Content-Type': 'application/json'})
+
+@app.route('/trades')
+def trades():
+    import requests
+    r = requests.get(f"{Config.MATCHER_URL}/trades", timeout=2)
+    return (r.text, r.status_code, {'Content-Type': 'application/json'})
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=5000)
+
+
+@app.route('/submit', methods=['POST'])
+def submit_order():
+    from flask import request
+    data = None
+    try:
+        data = request.get_json(force=True)
+    except Exception as e:
+        return jsonify({'status':'badjson','error': str(e)}), 400
+    if not data:
+        return jsonify({'status':'no_data'}), 400
+    try:
+        fut = producer.send(Config.ORDERS_TOPIC, value=data)
+        meta = fut.get(timeout=10)
+        producer.flush()
+        app.logger.info("Produced order %s -> topic=%s partition=%s offset=%s", data.get('order_id'), meta.topic, meta.partition, meta.offset)
+        return jsonify({'status':'sent','data':data})
+    except Exception as e:
+        app.logger.exception("Failed producing order: %s", e)
+        return jsonify({'status':'failed','error':str(e)}), 500

frontend/requirements.txt

@@ -0,0 +1,4 @@
+Flask==2.2.5
+kafka-python==2.0.2
+requests==2.31.0
+

frontend/templates/index.html

@@ -0,0 +1,312 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Order Entry</title>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; background: #f7f7f7; }
+    h1 { display: flex; align-items: center; gap: 15px; margin-bottom: 20px; }
+    h2 { margin: 5px 0 10px; font-size: 16px; }
+
+    .panel {
+      background: #fff;
+      border-radius: 8px;
+      padding: 15px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      margin-bottom: 20px;
+    }
+    .grid { display: grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; }
+    .panel-inner {
+      background: #fff;
+      border-radius: 8px;
+      padding: 15px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      display: flex;
+      flex-direction: column;
+      min-height: 350px;
+    }
+
+    /* Status badge */
+    .status {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 12px;
+      border-radius: 20px;
+      font-size: 12px;
+      font-weight: bold;
+    }
+    .status .dot { width: 10px; height: 10px; border-radius: 50%; }
+    .status.connected { background: #d4edda; color: #155724; }
+    .status.connected .dot { background: #28a745; }
+    .status.disconnected { background: #f8d7da; color: #721c24; }
+    .status.disconnected .dot { background: #dc3545; }
+    @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+
+    /* Order form grid */
+    .order-grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 12px;
+    }
+    .form-group { }
+    .form-group.full { grid-column: 1 / -1; }
+    .form-group label { display: block; font-size: 12px; color: #666; margin-bottom: 4px; }
+    .form-group input,
+    .form-group select {
+      width: 100%;
+      padding: 8px;
+      border: 1px solid #ccc;
+      border-radius: 4px;
+      font-size: 13px;
+      box-sizing: border-box;
+    }
+    .btn-send {
+      width: 100%;
+      padding: 10px;
+      background: #2196F3;
+      color: #fff;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 14px;
+      font-weight: bold;
+    }
+    .btn-send:hover { background: #1976D2; }
+
+    /* Order feedback */
+    #order-status {
+      padding: 8px 12px;
+      border-radius: 4px;
+      font-size: 13px;
+      margin-top: 10px;
+      display: none;
+    }
+    #order-status.success { background: #d4edda; color: #155724; display: block; }
+    #order-status.error   { background: #f8d7da; color: #721c24; display: block; }
+
+    /* Tables */
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th, td { border: 1px solid #ccc; padding: 5px 8px; text-align: center; }
+    th { background: #f0f0f0; font-weight: bold; }
+    tbody tr:hover { background: #f5f5f5; }
+    .bid { color: #2e7d32; font-weight: bold; }
+    .ask { color: #c62828; font-weight: bold; }
+
+    /* Highlight animation for new rows */
+    @keyframes highlight { from { background: #c8e6c9; } to { background: transparent; } }
+    .new-row { animation: highlight 2s ease-out; }
+
+    .refresh-info { font-size: 11px; color: #999; text-align: right; margin-top: 6px; }
+  </style>
+</head>
+<body>
+
+  <h1>
+    Order Entry
+    <span id="status-badge" class="status connected">
+      <span class="dot"></span>
+      <span id="status-text">Live</span>
+    </span>
+  </h1>
+
+  <!-- Order Entry (full width) -->
+  <div class="panel">
+    <h2>Place Order</h2>
+    <form id="orderForm" onsubmit="sendOrder(event)">
+      <div class="order-grid">
+        <div class="form-group">
+          <label>Order ID <span style="color:#bbb;">(optional)</span></label>
+          <input name="order_id" placeholder="Auto-generated">
+        </div>
+        <div class="form-group">
+          <label>Symbol</label>
+          <input name="symbol" value="FOO">
+        </div>
+        <div class="form-group">
+          <label>Side</label>
+          <select name="type">
+            <option value="buy">BUY</option>
+            <option value="sell">SELL</option>
+          </select>
+        </div>
+        <div class="form-group">
+          <label>Quantity</label>
+          <input name="quantity" type="number" value="10">
+        </div>
+        <div class="form-group full">
+          <label>Price</label>
+          <input name="price" type="number" step="0.01" value="100.00">
+        </div>
+        <div class="form-group full">
+          <button type="submit" class="btn-send">Send Order</button>
+        </div>
+      </div>
+    </form>
+    <div id="order-status"></div>
+  </div>
+
+  <!-- Order Book + Trades grid -->
+  <div class="grid">
+
+    <div class="panel-inner">
+      <h2>Order Book</h2>
+      <div style="flex-grow:1; overflow-y:auto;">
+        <table>
+          <thead>
+            <tr>
+              <th class="bid">Bid Qty</th>
+              <th class="bid">Bid Price</th>
+              <th class="ask">Ask Price</th>
+              <th class="ask">Ask Qty</th>
+            </tr>
+          </thead>
+          <tbody id="book-body">
+            <tr><td colspan="4" style="color:#999;">Loading...</td></tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="refresh-info" id="book-updated">--</div>
+    </div>
+
+    <div class="panel-inner">
+      <h2>Trades <span id="trade-count" style="font-size:13px; color:#999; font-weight:normal;"></span></h2>
+      <div style="flex-grow:1; overflow-y:auto;">
+        <table>
+          <thead>
+            <tr>
+              <th>Symbol</th>
+              <th>Qty</th>
+              <th>Price</th>
+              <th>Value</th>
+              <th>Time</th>
+            </tr>
+          </thead>
+          <tbody id="trades-body">
+            <tr><td colspan="5" style="color:#999;">Loading...</td></tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="refresh-info" id="trades-updated">--</div>
+    </div>
+
+  </div>
+
+  <script>
+    async function sendOrder(evt) {
+      evt.preventDefault();
+      const form = document.getElementById('orderForm');
+      const statusEl = document.getElementById('order-status');
+      const data = {
+        order_id: form.order_id.value || Date.now().toString(),
+        symbol:   form.symbol.value,
+        type:     form.type.value,
+        quantity: parseInt(form.quantity.value, 10),
+        price:    parseFloat(form.price.value),
+        timestamp: Date.now() / 1000
+      };
+      try {
+        const r = await fetch('/order', {
+          method: 'POST',
+          headers: {'Content-Type': 'application/json'},
+          body: JSON.stringify(data)
+        });
+        await r.json();
+        statusEl.className = 'success';
+        statusEl.textContent = `Order sent: ${data.type.toUpperCase()} ${data.quantity} ${data.symbol} @ ${data.price.toFixed(2)}`;
+        setTimeout(() => { statusEl.style.display = 'none'; }, 4000);
+        loadBook();
+      } catch(e) {
+        statusEl.className = 'error';
+        statusEl.textContent = 'Error sending order: ' + e.message;
+      }
+    }
+
+    function renderBook(b) {
+      const bids = (b.bids || []).sort((a, c) => (c.price || 0) - (a.price || 0));
+      const asks = (b.asks || []).sort((a, c) => (a.price || 0) - (c.price || 0));
+      const tbody = document.getElementById('book-body');
+      tbody.innerHTML = '';
+      const maxRows = Math.max(bids.length, asks.length);
+      if (maxRows === 0) {
+        tbody.innerHTML = '<tr><td colspan="4" style="color:#999; text-align:center;">No resting orders</td></tr>';
+        return;
+      }
+      for (let i = 0; i < Math.min(maxRows, 20); i++) {
+        const bid = bids[i] || {};
+        const ask = asks[i] || {};
+        const row = document.createElement('tr');
+        row.innerHTML = `
+          <td class="bid">${bid.quantity != null ? bid.quantity : ''}</td>
+          <td class="bid">${bid.price != null ? Number(bid.price).toFixed(2) : ''}</td>
+          <td class="ask">${ask.price != null ? Number(ask.price).toFixed(2) : ''}</td>
+          <td class="ask">${ask.quantity != null ? ask.quantity : ''}</td>
+        `;
+        tbody.appendChild(row);
+      }
+    }
+
+    let prevTradeCount = 0;
+    function renderTrades(trades) {
+      const tbody = document.getElementById('trades-body');
+      const isNew = trades.length > prevTradeCount;
+      tbody.innerHTML = '';
+      if (!trades || trades.length === 0) {
+        tbody.innerHTML = '<tr><td colspan="5" style="color:#999; text-align:center;">No trades yet</td></tr>';
+        document.getElementById('trade-count').textContent = '';
+        return;
+      }
+      for (const t of trades.slice(0, 50)) {
+        const qty   = t.quantity || t.qty || 0;
+        const price = Number(t.price || 0);
+        const value = (qty * price).toFixed(2);
+        const ts    = t.timestamp ? new Date(t.timestamp * 1000).toLocaleTimeString() : '-';
+        const row   = document.createElement('tr');
+        if (isNew) row.className = 'new-row';
+        row.innerHTML = `
+          <td><strong>${t.symbol || '?'}</strong></td>
+          <td>${qty}</td>
+          <td>${price.toFixed(2)}</td>
+          <td style="color:#666;">${value}</td>
+          <td style="font-size:11px;">${ts}</td>
+        `;
+        tbody.appendChild(row);
+      }
+      document.getElementById('trade-count').textContent = `(${trades.length})`;
+      prevTradeCount = trades.length;
+    }
+
+    async function loadBook() {
+      const now = new Date().toLocaleTimeString();
+      const badge = document.getElementById('status-badge');
+
+      try {
+        const r = await fetch('/book');
+        const b = await r.json();
+        renderBook(b);
+        document.getElementById('book-updated').textContent = 'Updated: ' + now;
+        badge.className = 'status connected';
+        document.getElementById('status-text').textContent = 'Live';
+      } catch(e) {
+        document.getElementById('book-body').innerHTML =
+          '<tr><td colspan="4" style="color:red; text-align:center;">Error loading book</td></tr>';
+        badge.className = 'status disconnected';
+        document.getElementById('status-text').textContent = 'Disconnected';
+      }
+
+      try {
+        const r2 = await fetch('/trades');
+        const t  = await r2.json();
+        renderTrades(Array.isArray(t) ? t : (t.trades || []));
+        document.getElementById('trades-updated').textContent = 'Updated: ' + now;
+      } catch(e) {
+        document.getElementById('trades-body').innerHTML =
+          '<tr><td colspan="5" style="color:red; text-align:center;">Error loading trades</td></tr>';
+      }
+    }
+
+    setInterval(loadBook, 2000);
+    window.onload = loadBook;
+  </script>
+</body>
+</html>

matcher/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY matcher.py database.py ./
+CMD ["python", "matcher.py"]

matcher/database.py

@@ -0,0 +1,242 @@
+"""SQLite persistence layer for the matcher service."""
+
+import sqlite3
+import threading
+import time
+import os
+
+DB_PATH = os.getenv("DB_PATH", "/app/data/matcher.db")
+
+_local = threading.local()
+
+
+def get_connection():
+    """Get a thread-local database connection."""
+    if not hasattr(_local, "conn") or _local.conn is None:
+        os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
+        _local.conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+        _local.conn.row_factory = sqlite3.Row
+    return _local.conn
+
+
+def init_db():
+    """Initialize database schema."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    cursor.executescript("""
+        CREATE TABLE IF NOT EXISTS trades (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            symbol TEXT NOT NULL,
+            price REAL NOT NULL,
+            quantity INTEGER NOT NULL,
+            buy_order_id TEXT,
+            sell_order_id TEXT,
+            timestamp REAL NOT NULL,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        );
+
+        CREATE TABLE IF NOT EXISTS order_book (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            cl_ord_id TEXT UNIQUE,
+            symbol TEXT NOT NULL,
+            side TEXT NOT NULL,
+            price REAL,
+            quantity INTEGER NOT NULL,
+            remaining_qty INTEGER NOT NULL,
+            status TEXT DEFAULT 'OPEN',
+            timestamp REAL NOT NULL,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_trades_symbol ON trades(symbol);
+        CREATE INDEX IF NOT EXISTS idx_trades_timestamp ON trades(timestamp);
+        CREATE INDEX IF NOT EXISTS idx_orderbook_symbol_side ON order_book(symbol, side);
+        CREATE INDEX IF NOT EXISTS idx_orderbook_status ON order_book(status);
+        CREATE INDEX IF NOT EXISTS idx_orderbook_cl_ord_id ON order_book(cl_ord_id);
+    """)
+
+    conn.commit()
+    print(f"Database initialized at {DB_PATH}")
+
+
+def save_trade(trade: dict):
+    """Persist a trade to the database."""
+    conn = get_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+        INSERT INTO trades (symbol, price, quantity, buy_order_id, sell_order_id, timestamp)
+        VALUES (?, ?, ?, ?, ?, ?)
+    """, (
+        trade.get("symbol"),
+        trade.get("price"),
+        trade.get("quantity"),
+        trade.get("buy_id"),
+        trade.get("sell_id"),
+        trade.get("timestamp", time.time())
+    ))
+    conn.commit()
+    return cursor.lastrowid
+
+
+def get_trades(symbol: str = None, limit: int = 200, offset: int = 0):
+    """Retrieve trades from database."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    if symbol:
+        cursor.execute("""
+            SELECT * FROM trades
+            WHERE symbol = ?
+            ORDER BY timestamp DESC
+            LIMIT ? OFFSET ?
+        """, (symbol, limit, offset))
+    else:
+        cursor.execute("""
+            SELECT * FROM trades
+            ORDER BY timestamp DESC
+            LIMIT ? OFFSET ?
+        """, (limit, offset))
+
+    rows = cursor.fetchall()
+    return [dict(row) for row in rows]
+
+
+def get_trade_count(symbol: str = None):
+    """Get total trade count."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    if symbol:
+        cursor.execute("SELECT COUNT(*) FROM trades WHERE symbol = ?", (symbol,))
+    else:
+        cursor.execute("SELECT COUNT(*) FROM trades")
+
+    return cursor.fetchone()[0]
+
+
+def save_order(order: dict):
+    """Save or update an order in the order book."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    cl_ord_id = order.get("cl_ord_id")
+    if not cl_ord_id:
+        cl_ord_id = f"gen-{time.time_ns()}"
+
+    cursor.execute("""
+        INSERT INTO order_book (cl_ord_id, symbol, side, price, quantity, remaining_qty, status, timestamp)
+        VALUES (?, ?, ?, ?, ?, ?, 'OPEN', ?)
+        ON CONFLICT(cl_ord_id) DO UPDATE SET
+            remaining_qty = excluded.remaining_qty,
+            status = CASE WHEN excluded.remaining_qty = 0 THEN 'FILLED' ELSE status END
+    """, (
+        cl_ord_id,
+        order.get("symbol"),
+        order.get("side"),
+        order.get("price"),
+        order.get("quantity"),
+        order.get("quantity"),  # remaining_qty starts as full quantity
+        order.get("timestamp", time.time())
+    ))
+    conn.commit()
+    return cl_ord_id
+
+
+def update_order_quantity(cl_ord_id: str, remaining_qty: int):
+    """Update remaining quantity for an order."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    status = "FILLED" if remaining_qty == 0 else "OPEN"
+    cursor.execute("""
+        UPDATE order_book
+        SET remaining_qty = ?, status = ?
+        WHERE cl_ord_id = ?
+    """, (remaining_qty, status, cl_ord_id))
+    conn.commit()
+
+
+def cancel_order(cl_ord_id: str):
+    """Mark an order as cancelled."""
+    conn = get_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+        UPDATE order_book SET status = 'CANCELLED' WHERE cl_ord_id = ?
+    """, (cl_ord_id,))
+    conn.commit()
+    return cursor.rowcount > 0
+
+
+def get_open_orders(symbol: str = None, side: str = None):
+    """Get all open orders, optionally filtered by symbol and side."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    query = "SELECT * FROM order_book WHERE status = 'OPEN'"
+    params = []
+
+    if symbol:
+        query += " AND symbol = ?"
+        params.append(symbol)
+    if side:
+        query += " AND side = ?"
+        params.append(side)
+
+    query += " ORDER BY timestamp ASC"
+    cursor.execute(query, params)
+
+    rows = cursor.fetchall()
+    return [dict(row) for row in rows]
+
+
+def load_order_books():
+    """Load all open orders grouped by symbol for matcher initialization."""
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    cursor.execute("""
+        SELECT * FROM order_book
+        WHERE status = 'OPEN'
+        ORDER BY symbol, side, timestamp
+    """)
+
+    books = {}
+    for row in cursor.fetchall():
+        order = dict(row)
+        symbol = order["symbol"]
+        side = order["side"]
+
+        if symbol not in books:
+            books[symbol] = {"bids": [], "asks": []}
+
+        # Convert DB format to matcher format
+        matcher_order = {
+            "cl_ord_id": order["cl_ord_id"],
+            "symbol": symbol,
+            "side": side,
+            "price": order["price"],
+            "quantity": order["remaining_qty"],
+            "timestamp": order["timestamp"]
+        }
+
+        if side == "BUY":
+            books[symbol]["bids"].append(matcher_order)
+        else:
+            books[symbol]["asks"].append(matcher_order)
+
+    return books
+
+
+def delete_filled_orders(older_than_days: int = 7):
+    """Clean up old filled orders."""
+    conn = get_connection()
+    cursor = conn.cursor()
+    cutoff = time.time() - (older_than_days * 24 * 60 * 60)
+    cursor.execute("""
+        DELETE FROM order_book
+        WHERE status IN ('FILLED', 'CANCELLED')
+        AND timestamp < ?
+    """, (cutoff,))
+    conn.commit()
+    return cursor.rowcount

matcher/matcher - Copy.py

@@ -0,0 +1,135 @@
+import threading, time, json
+from flask import Flask, jsonify
+from kafka import KafkaConsumer, KafkaProducer
+from kafka.errors import NoBrokersAvailable
+
+BOOTSTRAP = 'kafka:9092'
+
+import json, sys, datetime
+def jlog(event_type, payload):
+    out = {
+        "ts": datetime.datetime.utcnow().isoformat() + "Z",
+        "component": "matcher",
+        "event": event_type,
+        "payload": payload
+    }
+    sys.stdout.write(json.dumps(out, default=str) + "\n")
+    sys.stdout.flush()
+
+app = Flask(__name__)
+
+order_book = {'buy': [], 'sell': []}
+trades = []
+producer = None
+
+def create_kafka_producer(retries=20, delay=2):
+    global producer
+    for i in range(retries):
+        try:
+            producer = KafkaProducer(
+                bootstrap_servers=BOOTSTRAP,
+                value_serializer=lambda v: json.dumps(v).encode('utf-8')
+            )
+            print('Producer connected')
+            return
+        except NoBrokersAvailable:
+            print('Producer: Kafka not ready, retry', i)
+            time.sleep(delay)
+    raise RuntimeError('Producer: cannot connect to Kafka')
+
+def create_kafka_consumer(topic='orders', retries=20, delay=2):
+    for i in range(retries):
+        try:
+            consumer = KafkaConsumer(
+                topic,
+                bootstrap_servers=BOOTSTRAP,
+                value_deserializer=lambda m: json.loads(m.decode('utf-8')),
+                auto_offset_reset='earliest',
+                enable_auto_commit=True,
+                group_id='matcher-group'
+            )
+            print('Consumer connected to topic', topic)
+            return consumer
+        except NoBrokersAvailable:
+            print('Consumer: Kafka not ready, retry', i)
+            time.sleep(delay)
+    raise RuntimeError('Consumer: cannot connect to Kafka')
+
+def find_match(order):
+    side = order['type']
+    opp = 'sell' if side == 'buy' else 'buy'
+    candidates = [o for o in order_book[opp] if o['symbol'] == order['symbol'] and o['quantity'] > 0]
+    if not candidates:
+        return None
+    # best-price matching: for buy -> lowest sell price; for sell -> highest buy price
+    if side == 'buy':
+        valid = [o for o in candidates if o['price'] <= order['price']]
+        if not valid: return None
+        best_price = min(o['price'] for o in valid)
+        bests = [o for o in valid if o['price'] == best_price]
+        return min(bests, key=lambda x: x['timestamp'])
+    else:
+        valid = [o for o in candidates if o['price'] >= order['price']]
+        if not valid: return None
+        best_price = max(o['price'] for o in valid)
+        bests = [o for o in valid if o['price'] == best_price]
+        return min(bests, key=lambda x: x['timestamp'])
+
+def process_order(order):
+    print('Processing order:', order)
+    while order['quantity'] > 0:
+        matched = find_match(order)
+        if not matched:
+            order_book[order['type']].append(order.copy())
+            print('Added to book:', order)
+            return
+        traded_qty = min(order['quantity'], matched['quantity'])
+        trade_price = matched['price']
+        trade = {
+            'buy_order_id': order['order_id'] if order['type']=='buy' else matched['order_id'],
+            'sell_order_id': matched['order_id'] if order['type']=='buy' else order['order_id'],
+            'symbol': order['symbol'],
+            'price': trade_price,
+            'quantity': traded_qty,
+            'timestamp': time.time()
+        }
+        trades.append(trade)
+        if producer:
+            producer.send('trades', value=trade)
+            producer.flush()
+        print('TRADE:', trade)
+        order['quantity'] -= traded_qty
+        matched['quantity'] -= traded_qty
+        if matched['quantity'] == 0:
+            try:
+                order_book['sell' if order['type']=='buy' else 'buy'].remove(matched)
+                print('Removed matched from book:', matched)
+            except ValueError:
+                pass
+
+def consumer_loop():
+    consumer = create_kafka_consumer('orders')
+    for msg in consumer:
+        try:
+            order = msg.value
+            order['price'] = float(order['price'])
+            order['quantity'] = int(order['quantity'])
+            order.setdefault('timestamp', time.time())
+            process_order(order)
+        except Exception as e:
+            print('Error processing message:', e)
+
+@app.route('/book')
+def get_book():
+    # present best bids/asks sorted
+    return jsonify(order_book)
+
+@app.route('/trades')
+def get_trades():
+    return jsonify(trades)
+
+if __name__ == '__main__':
+    create_kafka_producer()
+    t = threading.Thread(target=consumer_loop, daemon=True)
+    t.start()
+    app.run(host='0.0.0.0', port=6000)

matcher/matcher.py

@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""Simple matcher service:
+ - consumes orders from Kafka topic 'orders'
+ - maintains in-memory order book per symbol (with SQLite persistence)
+ - matches incoming orders using simple price-time priority
+ - publishes trades to Kafka 'trades' topic and persists to SQLite
+ - exposes HTTP API:
+    GET /trades -> recent trades list (from DB with pagination)
+    GET /orderbook/<symbol> -> current book for symbol
+"""
+import sys
+sys.path.insert(0, "/app")
+
+import json, time, threading
+from collections import defaultdict, deque
+from flask import Flask, jsonify, request
+
+from shared.config import Config
+from shared.kafka_utils import create_producer, create_consumer
+from database import init_db, save_trade, get_trades, get_trade_count, save_order, update_order_quantity, load_order_books
+
+# Initialize database on startup
+init_db()
+
+# Load persisted order books from database
+_loaded_books = load_order_books()
+order_books = defaultdict(lambda: {"bids": [], "asks": []})
+order_books.update(_loaded_books)
+print(f"Loaded {len(_loaded_books)} symbols from database")
+
+# In-memory trades cache for fast access (DB is source of truth)
+trades_log = deque(maxlen=200)
+lock = threading.Lock()
+
+app = Flask(__name__)
+
+
+def normalize_order(raw):
+    # Expecting JSON with keys like symbol, price, quantity, side (BUY/SELL) or FIX-like tags
+    if not isinstance(raw, dict):
+        return None
+    payload = raw.get('payload') or raw.get('message') or raw
+    def pick(*keys):
+        for k in keys:
+            if k in payload:
+                return payload.get(k)
+            if k in raw:
+                return raw.get(k)
+        return None
+    sym = pick('55','Symbol','symbol')
+    side = pick('54','Side','side','type')
+    qty = pick('38','OrderQty','quantity','qty')
+    px = pick('44','Price','price','px')
+    cl = pick('11','ClOrdID','cl_ord_id','id')
+    ord_type = pick('40','OrdType','ord_type','order_type')  # 1=Market, 2=Limit
+    time_in_force = pick('59','TimeInForce','time_in_force','tif')  # 0=Day, 1=GTC, 3=IOC, 4=FOK
+
+    try:
+        quantity = int(qty) if qty is not None else 0
+    except:
+        try:
+            quantity = int(float(qty))
+        except:
+            quantity = 0
+    try:
+        price = float(px) if px is not None else None
+    except:
+        price = None
+
+    side_norm = None
+    if side is not None:
+        s = str(side).lower()
+        if s in ('1','buy','b'):
+            side_norm = 'BUY'
+        elif s in ('2','sell','s'):
+            side_norm = 'SELL'
+        else:
+            # if type field contains 'buy' or 'sell'
+            if 'buy' in s:
+                side_norm = 'BUY'
+            elif 'sell' in s:
+                side_norm = 'SELL'
+            else:
+                side_norm = s.upper()
+
+    # Normalize order type: 1 or 'market' -> MARKET, 2 or 'limit' -> LIMIT
+    ord_type_norm = 'LIMIT'  # Default to limit
+    if ord_type is not None:
+        ot = str(ord_type).lower()
+        if ot in ('1', 'market', 'm'):
+            ord_type_norm = 'MARKET'
+        elif ot in ('2', 'limit', 'l'):
+            ord_type_norm = 'LIMIT'
+
+    # Normalize TimeInForce: 0=Day (default), 1=GTC, 3=IOC, 4=FOK
+    tif_norm = 'DAY'  # Default
+    if time_in_force is not None:
+        tif = str(time_in_force).lower()
+        if tif in ('0', 'day'):
+            tif_norm = 'DAY'
+        elif tif in ('1', 'gtc'):
+            tif_norm = 'GTC'
+        elif tif in ('3', 'ioc'):
+            tif_norm = 'IOC'
+        elif tif in ('4', 'fok'):
+            tif_norm = 'FOK'
+
+    order = {
+        'cl_ord_id': cl,
+        'symbol': sym,
+        'side': side_norm,
+        'quantity': quantity,
+        'price': price,
+        'ord_type': ord_type_norm,
+        'time_in_force': tif_norm,
+        'raw': raw,
+        'timestamp': time.time()
+    }
+    return order
+
+def match_order(order, producer=None):
+    """Try to match incoming order against book and produce trades when matched.
+
+    Supports:
+      - LIMIT orders: match at specified price or better
+      - MARKET orders: match at best available price (any price)
+      - IOC (Immediate-or-Cancel): fill what's available, cancel rest
+      - FOK (Fill-or-Kill): fill entire quantity or reject
+
+    Algorithm:
+      - For BUY: match against lowest-price asks where ask.price <= buy.price (or any for market)
+      - For SELL: match against highest-price bids where bid.price >= sell.price (or any for market)
+    """
+    symbol = order['symbol']
+    if not symbol:
+        return
+
+    is_market = order.get('ord_type') == 'MARKET'
+    tif = order.get('time_in_force', 'DAY')
+
+    with lock:
+        book = order_books[symbol]
+
+        # For FOK orders, check if full quantity can be filled first
+        if tif == 'FOK':
+            available_qty = 0
+            if order['side'] == 'BUY':
+                for ask in book['asks']:
+                    if is_market or (ask['price'] is not None and order['price'] is not None and ask['price'] <= order['price']):
+                        available_qty += ask['quantity']
+            else:
+                for bid in book['bids']:
+                    if is_market or (bid['price'] is not None and order['price'] is not None and bid['price'] >= order['price']):
+                        available_qty += bid['quantity']
+            if available_qty < order['quantity']:
+                print(f"FOK order rejected: only {available_qty} available, need {order['quantity']}")
+                return  # Reject FOK order
+
+        if order['side'] == 'BUY':
+            # try to match with asks (sorted by lowest price)
+            asks = book['asks']
+            asks.sort(key=lambda x: (x['price'] if x['price'] is not None else float('inf'), x['timestamp']))
+            remaining = order['quantity']
+            i = 0
+            while remaining > 0 and i < len(asks):
+                ask = asks[i]
+                # Market orders match at any price; limit orders check price
+                if not is_market:
+                    if ask['price'] is None or order['price'] is None or ask['price'] > order['price']:
+                        break
+                # matchable
+                traded_qty = min(remaining, ask['quantity'])
+                trade_price = ask['price']
+                trade = {
+                    'symbol': symbol,
+                    'price': trade_price,
+                    'quantity': traded_qty,
+                    'buy_id': order.get('cl_ord_id'),
+                    'sell_id': ask.get('cl_ord_id'),
+                    'timestamp': time.time()
+                }
+                trades_log.appendleft(trade)
+                # Persist trade to database
+                try:
+                    save_trade(trade)
+                except Exception as e:
+                    print("DB save_trade error:", e)
+                if producer:
+                    try:
+                        producer.send(Config.TRADES_TOPIC, trade)
+                    except Exception as e:
+                        print("Producer send error:", e)
+                remaining -= traded_qty
+                ask['quantity'] -= traded_qty
+                # Update order quantity in database
+                if ask.get('cl_ord_id'):
+                    try:
+                        update_order_quantity(ask['cl_ord_id'], ask['quantity'])
+                    except Exception as e:
+                        print("DB update_order error:", e)
+                if ask['quantity'] == 0:
+                    asks.pop(i)
+                else:
+                    i += 1
+            # if remaining, add to bids and persist (unless market or IOC order)
+            if remaining > 0:
+                if is_market or tif == 'IOC':
+                    # Market and IOC orders don't rest on book
+                    print(f"{'Market' if is_market else 'IOC'} order cancelled: {remaining} unfilled")
+                else:
+                    new_order = dict(order)
+                    new_order['quantity'] = remaining
+                    book['bids'].append(new_order)
+                    # Persist resting order to database
+                    try:
+                        save_order(new_order)
+                    except Exception as e:
+                        print("DB save_order error:", e)
+
+        elif order['side'] == 'SELL':
+            bids = book['bids']
+            bids.sort(key=lambda x: (-x['price'] if x['price'] is not None else 0, x['timestamp']))
+            remaining = order['quantity']
+            i = 0
+            while remaining > 0 and i < len(bids):
+                bid = bids[i]
+                # Market orders match at any price; limit orders check price
+                if not is_market:
+                    if bid['price'] is None or order['price'] is None or bid['price'] < order['price']:
+                        break
+                traded_qty = min(remaining, bid['quantity'])
+                trade_price = bid['price']
+                trade = {
+                    'symbol': symbol,
+                    'price': trade_price,
+                    'quantity': traded_qty,
+                    'buy_id': bid.get('cl_ord_id'),
+                    'sell_id': order.get('cl_ord_id'),
+                    'timestamp': time.time()
+                }
+                trades_log.appendleft(trade)
+                # Persist trade to database
+                try:
+                    save_trade(trade)
+                except Exception as e:
+                    print("DB save_trade error:", e)
+                if producer:
+                    try:
+                        producer.send(Config.TRADES_TOPIC, trade)
+                    except Exception as e:
+                        print("Producer send error:", e)
+                remaining -= traded_qty
+                bid['quantity'] -= traded_qty
+                # Update order quantity in database
+                if bid.get('cl_ord_id'):
+                    try:
+                        update_order_quantity(bid['cl_ord_id'], bid['quantity'])
+                    except Exception as e:
+                        print("DB update_order error:", e)
+                if bid['quantity'] == 0:
+                    bids.pop(i)
+                else:
+                    i += 1
+            # if remaining, add to asks and persist (unless market or IOC order)
+            if remaining > 0:
+                if is_market or tif == 'IOC':
+                    # Market and IOC orders don't rest on book
+                    print(f"{'Market' if is_market else 'IOC'} order cancelled: {remaining} unfilled")
+                else:
+                    new_order = dict(order)
+                    new_order['quantity'] = remaining
+                    book['asks'].append(new_order)
+                    # Persist resting order to database
+                    try:
+                        save_order(new_order)
+                    except Exception as e:
+                        print("DB save_order error:", e)
+        else:
+            # unknown side: append to book as-is
+            order_books[symbol]['bids' if order.get('side','').upper()=='BUY' else 'asks'].append(order)
+
+def handle_cancel(msg, producer=None):
+    """Handle order cancellation request."""
+    orig_cl_ord_id = msg.get('orig_cl_ord_id')
+    symbol = msg.get('symbol')
+
+    if not orig_cl_ord_id:
+        print("Cancel rejected: missing orig_cl_ord_id")
+        return
+
+    with lock:
+        found = False
+        # Search all order books if symbol not specified
+        symbols_to_search = [symbol] if symbol else list(order_books.keys())
+
+        for sym in symbols_to_search:
+            book = order_books.get(sym, {'bids': [], 'asks': []})
+
+            # Search bids
+            for i, order in enumerate(book['bids']):
+                if order.get('cl_ord_id') == orig_cl_ord_id:
+                    book['bids'].pop(i)
+                    found = True
+                    print(f"Cancelled BUY order {orig_cl_ord_id} in {sym}")
+                    break
+
+            if found:
+                break
+
+            # Search asks
+            for i, order in enumerate(book['asks']):
+                if order.get('cl_ord_id') == orig_cl_ord_id:
+                    book['asks'].pop(i)
+                    found = True
+                    print(f"Cancelled SELL order {orig_cl_ord_id} in {sym}")
+                    break
+
+            if found:
+                break
+
+        if found:
+            # Update database
+            try:
+                from database import cancel_order
+                cancel_order(orig_cl_ord_id)
+            except Exception as e:
+                print(f"DB cancel_order error: {e}")
+        else:
+            print(f"Cancel rejected: order {orig_cl_ord_id} not found")
+
+
+def handle_amend(msg, producer=None):
+    """Handle order amend (cancel/replace) request."""
+    orig_cl_ord_id = msg.get('orig_cl_ord_id')
+    new_cl_ord_id = msg.get('cl_ord_id')
+    symbol = msg.get('symbol')
+    new_qty = msg.get('quantity')
+    new_price = msg.get('price')
+
+    if not orig_cl_ord_id:
+        print("Amend rejected: missing orig_cl_ord_id")
+        return
+
+    with lock:
+        found = False
+        symbols_to_search = [symbol] if symbol else list(order_books.keys())
+
+        for sym in symbols_to_search:
+            book = order_books.get(sym, {'bids': [], 'asks': []})
+
+            # Search bids
+            for order in book['bids']:
+                if order.get('cl_ord_id') == orig_cl_ord_id:
+                    # Update order in place
+                    if new_qty is not None and new_qty > 0:
+                        order['quantity'] = new_qty
+                    if new_price is not None and new_price > 0:
+                        order['price'] = new_price
+                    if new_cl_ord_id:
+                        order['cl_ord_id'] = new_cl_ord_id
+                    found = True
+                    print(f"Amended BUY order {orig_cl_ord_id} -> qty={new_qty}, price={new_price}")
+                    break
+
+            if found:
+                break
+
+            # Search asks
+            for order in book['asks']:
+                if order.get('cl_ord_id') == orig_cl_ord_id:
+                    if new_qty is not None and new_qty > 0:
+                        order['quantity'] = new_qty
+                    if new_price is not None and new_price > 0:
+                        order['price'] = new_price
+                    if new_cl_ord_id:
+                        order['cl_ord_id'] = new_cl_ord_id
+                    found = True
+                    print(f"Amended SELL order {orig_cl_ord_id} -> qty={new_qty}, price={new_price}")
+                    break
+
+            if found:
+                break
+
+        if not found:
+            print(f"Amend rejected: order {orig_cl_ord_id} not found")
+
+
+def consume_orders():
+    producer = None
+    try:
+        producer = create_producer(component_name="Matcher")
+    except Exception as e:
+        print("Producer unavailable:", e)
+
+    try:
+        consumer = create_consumer(
+            topics=Config.ORDERS_TOPIC,
+            group_id="matcher",
+            component_name="Matcher"
+        )
+    except Exception as e:
+        print("Consumer unavailable:", e)
+        return
+
+    for msg in consumer:
+        try:
+            raw = msg.value
+        except Exception:
+            continue
+
+        # Handle special message types (cancel, amend)
+        msg_type = raw.get('type', '').lower() if isinstance(raw, dict) else ''
+
+        if msg_type == 'cancel':
+            handle_cancel(raw, producer)
+            continue
+        elif msg_type == 'amend':
+            handle_amend(raw, producer)
+            continue
+
+        # Regular order
+        order = normalize_order(raw)
+        if not order:
+            continue
+        print("Matcher received order:", order.get('symbol'), order.get('side'), order.get('quantity'), order.get('price'))
+        match_order(order, producer=producer)
+
+@app.route("/health")
+def health():
+    """Health check endpoint."""
+    status = {
+        "status": "healthy",
+        "service": "matcher",
+        "timestamp": time.time(),
+        "stats": {
+            "symbols": len(order_books),
+            "total_orders": sum(len(b["bids"]) + len(b["asks"]) for b in order_books.values()),
+            "trades_in_memory": len(trades_log)
+        }
+    }
+    # Check database connectivity
+    try:
+        from database import get_trade_count
+        status["stats"]["trades_in_db"] = get_trade_count()
+        status["database"] = "connected"
+    except Exception as e:
+        status["database"] = f"error: {e}"
+        status["status"] = "degraded"
+
+    return jsonify(status)
+
+@app.route("/trades")
+def trades_endpoint():
+    """Get trades with optional filtering and pagination.
+
+    Query params:
+        symbol: Filter by symbol (optional)
+        limit: Max records to return (default 200)
+        offset: Records to skip (default 0)
+    """
+    symbol = request.args.get('symbol')
+    limit = request.args.get('limit', 200, type=int)
+    offset = request.args.get('offset', 0, type=int)
+
+    # Fetch from database for persistence
+    trades = get_trades(symbol=symbol, limit=limit, offset=offset)
+    total = get_trade_count(symbol=symbol)
+
+    return jsonify({
+        'trades': trades,
+        'total': total,
+        'limit': limit,
+        'offset': offset
+    })
+
+@app.route("/orderbook/<symbol>")
+def get_orderbook(symbol):
+    with lock:
+        book = order_books[symbol]
+        bids = sorted([o for o in book["bids"]], key=lambda x: -float(x["price"]) if x.get("price") is not None else 0)
+        asks = sorted([o for o in book["asks"]], key=lambda x: float(x["price"]) if x.get("price") is not None else float('inf'))
+        return jsonify({"symbol": symbol, "bids": bids, "asks": asks})
+
+# Metrics tracking
+_metrics = {
+    "orders_received": 0,
+    "trades_executed": 0,
+    "cancels_processed": 0,
+    "amends_processed": 0,
+    "start_time": time.time()
+}
+
+@app.route("/metrics")
+def metrics():
+    """Prometheus-compatible metrics endpoint."""
+    with lock:
+        total_bids = sum(len(b["bids"]) for b in order_books.values())
+        total_asks = sum(len(b["asks"]) for b in order_books.values())
+
+    try:
+        db_trades = get_trade_count()
+    except:
+        db_trades = 0
+
+    uptime = time.time() - _metrics["start_time"]
+
+    # Prometheus text format
+    lines = [
+        "# HELP matcher_orders_received_total Total orders received",
+        "# TYPE matcher_orders_received_total counter",
+        f"matcher_orders_received_total {_metrics['orders_received']}",
+        "",
+        "# HELP matcher_trades_executed_total Total trades executed",
+        "# TYPE matcher_trades_executed_total counter",
+        f"matcher_trades_executed_total {db_trades}",
+        "",
+        "# HELP matcher_cancels_processed_total Total cancel requests processed",
+        "# TYPE matcher_cancels_processed_total counter",
+        f"matcher_cancels_processed_total {_metrics['cancels_processed']}",
+        "",
+        "# HELP matcher_amends_processed_total Total amend requests processed",
+        "# TYPE matcher_amends_processed_total counter",
+        f"matcher_amends_processed_total {_metrics['amends_processed']}",
+        "",
+        "# HELP matcher_order_book_bids Current number of bid orders",
+        "# TYPE matcher_order_book_bids gauge",
+        f"matcher_order_book_bids {total_bids}",
+        "",
+        "# HELP matcher_order_book_asks Current number of ask orders",
+        "# TYPE matcher_order_book_asks gauge",
+        f"matcher_order_book_asks {total_asks}",
+        "",
+        "# HELP matcher_symbols_active Number of active trading symbols",
+        "# TYPE matcher_symbols_active gauge",
+        f"matcher_symbols_active {len(order_books)}",
+        "",
+        "# HELP matcher_uptime_seconds Time since service started",
+        "# TYPE matcher_uptime_seconds counter",
+        f"matcher_uptime_seconds {uptime:.2f}",
+        "",
+    ]
+
+    return "\n".join(lines), 200, {"Content-Type": "text/plain; charset=utf-8"}
+
+if __name__ == "__main__":
+    threading.Thread(target=consume_orders, daemon=True).start()
+    app.run(host="0.0.0.0", port=6000, debug=True)

matcher/requirements.txt

@@ -0,0 +1,4 @@
+kafka-python==2.0.2
+Flask==2.2.5
+requests==2.31.0
+

matcher/test_matcher.py

@@ -0,0 +1,429 @@
+"""Unit tests for the matcher service.
+
+Run with: python -m pytest matcher/test_matcher.py -v
+"""
+import sys
+import os
+import time
+import unittest
+from unittest.mock import Mock, patch
+from collections import defaultdict
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Mock database before importing matcher
+sys.modules['matcher.database'] = Mock()
+
+
+class TestNormalizeOrder(unittest.TestCase):
+    """Tests for order normalization."""
+
+    def setUp(self):
+        # Import after mocking
+        from matcher.matcher import normalize_order
+        self.normalize_order = normalize_order
+
+    def test_normalize_basic_order(self):
+        """Test normalizing a basic order."""
+        raw = {
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.5,
+            'cl_ord_id': 'order-1'
+        }
+        order = self.normalize_order(raw)
+        self.assertEqual(order['symbol'], 'ALPHA')
+        self.assertEqual(order['side'], 'BUY')
+        self.assertEqual(order['quantity'], 100)
+        self.assertEqual(order['price'], 50.5)
+        self.assertEqual(order['cl_ord_id'], 'order-1')
+
+    def test_normalize_fix_tags(self):
+        """Test normalizing FIX-style order with tag numbers."""
+        raw = {
+            '55': 'BETA',
+            '54': '1',  # Buy
+            '38': '200',
+            '44': '25.0',
+            '11': 'fix-order-1'
+        }
+        order = self.normalize_order(raw)
+        self.assertEqual(order['symbol'], 'BETA')
+        self.assertEqual(order['side'], 'BUY')
+        self.assertEqual(order['quantity'], 200)
+        self.assertEqual(order['price'], 25.0)
+
+    def test_normalize_sell_side(self):
+        """Test normalizing sell orders."""
+        for side_value in ['2', 'sell', 'SELL', 's']:
+            raw = {'symbol': 'TEST', 'side': side_value, 'quantity': 50, 'price': 10}
+            order = self.normalize_order(raw)
+            self.assertEqual(order['side'], 'SELL', f"Failed for side={side_value}")
+
+    def test_normalize_market_order(self):
+        """Test normalizing market order type."""
+        raw = {
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'ord_type': '1'  # Market
+        }
+        order = self.normalize_order(raw)
+        self.assertEqual(order['ord_type'], 'MARKET')
+
+    def test_normalize_ioc_order(self):
+        """Test normalizing IOC time-in-force."""
+        raw = {
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50,
+            'time_in_force': '3'  # IOC
+        }
+        order = self.normalize_order(raw)
+        self.assertEqual(order['time_in_force'], 'IOC')
+
+
+class TestMatchOrder(unittest.TestCase):
+    """Tests for order matching logic."""
+
+    def setUp(self):
+        """Set up fresh order books for each test."""
+        # Import and reset order books
+        import matcher.matcher as matcher_module
+        self.matcher = matcher_module
+        self.matcher.order_books = defaultdict(lambda: {"bids": [], "asks": []})
+        self.matcher.trades_log.clear()
+
+    def test_no_match_empty_book(self):
+        """Test that orders rest when book is empty."""
+        order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+        self.matcher.match_order(order, producer=None)
+
+        # Order should be added to bids
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 1)
+        self.assertEqual(self.matcher.order_books['ALPHA']['bids'][0]['quantity'], 100)
+
+    def test_full_match(self):
+        """Test full match between buy and sell."""
+        # Add a resting sell order
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 100,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        # Incoming buy matches
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_trade'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # Trade should be recorded
+        self.assertEqual(len(self.matcher.trades_log), 1)
+        trade = self.matcher.trades_log[0]
+        self.assertEqual(trade['quantity'], 100)
+        self.assertEqual(trade['price'], 50.0)
+
+        # Both sides of book should be empty
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['asks']), 0)
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 0)
+
+    def test_partial_fill(self):
+        """Test partial fill when order qty exceeds available."""
+        # Resting sell for 50
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 50,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        # Buy for 100
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_trade'), \
+             patch.object(self.matcher, 'save_order'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # Trade for 50
+        self.assertEqual(len(self.matcher.trades_log), 1)
+        self.assertEqual(self.matcher.trades_log[0]['quantity'], 50)
+
+        # Remaining 50 rests on bid side
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 1)
+        self.assertEqual(self.matcher.order_books['ALPHA']['bids'][0]['quantity'], 50)
+
+    def test_no_match_price_mismatch(self):
+        """Test no match when prices don't cross."""
+        # Sell at 55
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 100,
+            'price': 55.0,
+            'timestamp': time.time()
+        })
+
+        # Buy at 50 - won't match
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_order'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # No trades
+        self.assertEqual(len(self.matcher.trades_log), 0)
+
+        # Both orders rest
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['asks']), 1)
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 1)
+
+    def test_market_order_matches_any_price(self):
+        """Test market order matches at any price."""
+        # Sell at 100
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 100,
+            'price': 100.0,
+            'timestamp': time.time()
+        })
+
+        # Market buy
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': None,  # No price for market order
+            'ord_type': 'MARKET',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_trade'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # Should match at 100
+        self.assertEqual(len(self.matcher.trades_log), 1)
+        self.assertEqual(self.matcher.trades_log[0]['price'], 100.0)
+
+    def test_ioc_order_cancels_remainder(self):
+        """Test IOC order cancels unfilled portion."""
+        # Sell only 30
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 30,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        # IOC buy for 100
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'IOC',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_trade'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # Trade for 30
+        self.assertEqual(len(self.matcher.trades_log), 1)
+        self.assertEqual(self.matcher.trades_log[0]['quantity'], 30)
+
+        # Remaining 70 cancelled, not added to book
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 0)
+
+    def test_fok_order_rejected_insufficient_qty(self):
+        """Test FOK order rejected when full qty not available."""
+        # Only 30 available
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-1',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 30,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        # FOK buy for 100
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'FOK',
+            'timestamp': time.time()
+        }
+
+        self.matcher.match_order(buy_order, producer=None)
+
+        # No trades - order rejected
+        self.assertEqual(len(self.matcher.trades_log), 0)
+
+        # Sell order still there
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['asks']), 1)
+
+    def test_price_time_priority(self):
+        """Test orders match in price-time priority."""
+        # Two sell orders at different prices
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-high',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 50,
+            'price': 52.0,
+            'timestamp': time.time()
+        })
+        self.matcher.order_books['ALPHA']['asks'].append({
+            'cl_ord_id': 'sell-low',
+            'symbol': 'ALPHA',
+            'side': 'SELL',
+            'quantity': 50,
+            'price': 50.0,
+            'timestamp': time.time() + 1
+        })
+
+        # Buy should match lower price first
+        buy_order = {
+            'cl_ord_id': 'buy-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 50,
+            'price': 55.0,
+            'ord_type': 'LIMIT',
+            'time_in_force': 'DAY',
+            'timestamp': time.time()
+        }
+
+        with patch.object(self.matcher, 'save_trade'):
+            self.matcher.match_order(buy_order, producer=None)
+
+        # Matched at 50 (better price)
+        self.assertEqual(self.matcher.trades_log[0]['price'], 50.0)
+        self.assertEqual(self.matcher.trades_log[0]['sell_id'], 'sell-low')
+
+
+class TestCancelOrder(unittest.TestCase):
+    """Tests for order cancellation."""
+
+    def setUp(self):
+        import matcher.matcher as matcher_module
+        self.matcher = matcher_module
+        self.matcher.order_books = defaultdict(lambda: {"bids": [], "asks": []})
+
+    def test_cancel_existing_order(self):
+        """Test cancelling an existing order."""
+        # Add order to book
+        self.matcher.order_books['ALPHA']['bids'].append({
+            'cl_ord_id': 'order-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        cancel_msg = {
+            'type': 'cancel',
+            'orig_cl_ord_id': 'order-1',
+            'symbol': 'ALPHA'
+        }
+
+        with patch.object(self.matcher, 'cancel_order'):
+            self.matcher.handle_cancel(cancel_msg, producer=None)
+
+        # Order should be removed
+        self.assertEqual(len(self.matcher.order_books['ALPHA']['bids']), 0)
+
+
+class TestAmendOrder(unittest.TestCase):
+    """Tests for order amendment."""
+
+    def setUp(self):
+        import matcher.matcher as matcher_module
+        self.matcher = matcher_module
+        self.matcher.order_books = defaultdict(lambda: {"bids": [], "asks": []})
+
+    def test_amend_price(self):
+        """Test amending order price."""
+        # Add order
+        self.matcher.order_books['ALPHA']['bids'].append({
+            'cl_ord_id': 'order-1',
+            'symbol': 'ALPHA',
+            'side': 'BUY',
+            'quantity': 100,
+            'price': 50.0,
+            'timestamp': time.time()
+        })
+
+        amend_msg = {
+            'type': 'amend',
+            'orig_cl_ord_id': 'order-1',
+            'symbol': 'ALPHA',
+            'price': 55.0
+        }
+
+        self.matcher.handle_amend(amend_msg, producer=None)
+
+        # Price should be updated
+        self.assertEqual(self.matcher.order_books['ALPHA']['bids'][0]['price'], 55.0)
+
+
+if __name__ == '__main__':
+    unittest.main()

md_feeder/Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY mdf_simulator.py .
+
+RUN pip install --no-cache-dir kafka-python
+
+CMD ["python", "-u", "mdf_simulator.py"]

md_feeder/mdf_simulator.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+import sys
+sys.path.insert(0, "/app")
+
+import json, time, random, os
+
+from shared.config import Config
+from shared.kafka_utils import create_producer
+
+ORDER_INTERVAL = 60.0 / Config.ORDERS_PER_MIN
+
+def load_securities():
+    """Load securities from file: SYMBOL start_price current_price"""
+    securities = {}
+    if not os.path.exists(Config.SECURITIES_FILE):
+        raise FileNotFoundError(f"{Config.SECURITIES_FILE} not found")
+
+    with open(Config.SECURITIES_FILE) as f:
+        for line in f:
+            if not line.strip() or line.startswith("#"):
+                continue
+            parts = line.split()
+            if len(parts) >= 3:
+                symbol, start, current = parts[0], float(parts[1]), float(parts[2])
+                securities[symbol] = {"start": start, "current": current}
+    return securities
+
+def save_securities(securities):
+    """Persist securities with header line"""
+    with open(Config.SECURITIES_FILE, "w") as f:
+        f.write("#SYMBOL\t<start_price>\t<current_price>\n")
+        for sym, vals in securities.items():
+            f.write(f"{sym}\t{vals['start']:.2f}\t{vals['current']:.2f}\n")
+
+_order_counter = 0
+
+def make_order(symbol, side, price, qty):
+    global _order_counter
+    _order_counter += 1
+    return {
+        "symbol": symbol,
+        "side": side,
+        "price": round(price, 2),
+        "quantity": qty,
+        "cl_ord_id": f"MDF-{int(time.time()*1000)}-{_order_counter}",
+        "timestamp": time.time(),
+        "source": "MDF"
+    }
+
+def make_snapshot(symbol, best_bid, best_ask, bid_size, ask_size):
+    return {
+        "symbol": symbol,
+        "best_bid": round(best_bid, 2),
+        "best_ask": round(best_ask, 2),
+        "bid_size": bid_size,
+        "ask_size": ask_size,
+        "timestamp": time.time(),
+        "source": "MDF"
+    }
+
+if __name__ == "__main__":
+    producer = create_producer(component_name="MDF")
+
+    # Load securities and reset start=current
+    securities = load_securities()
+    for sym in securities:
+        securities[sym]["start"] = securities[sym]["current"]
+    save_securities(securities)
+    print(f"[MDF] Loaded securities: {list(securities.keys())}")
+
+    try:
+        while True:
+            for sym, vals in securities.items():
+                mid = vals["current"]
+                # Define spread: bids below (mid - spread), asks above (mid + spread)
+                half_spread = 0.10  # 10 cents spread
+
+                # --- generate order ---
+                # 90% passive orders (build book), 10% aggressive (create trades)
+                side = random.choice(["BUY", "SELL"])
+                rand = random.random()
+
+                if rand < 0.90:
+                    # Passive: place orders away from mid to rest on book
+                    if side == "BUY":
+                        # Bids: from (mid - spread) down to (mid - spread - 0.50)
+                        base = mid - half_spread
+                        offset = random.randint(1, 50) * Config.TICK_SIZE
+                        price = round(base - offset, 2)
+                    else:
+                        # Asks: from (mid + spread) up to (mid + spread + 0.50)
+                        base = mid + half_spread
+                        offset = random.randint(1, 50) * Config.TICK_SIZE
+                        price = round(base + offset, 2)
+                else:
+                    # Aggressive: cross the spread to create trades (rare)
+                    if side == "BUY":
+                        # Buy into asks
+                        price = round(mid + half_spread + random.randint(1, 5) * Config.TICK_SIZE, 2)
+                    else:
+                        # Sell into bids
+                        price = round(mid - half_spread - random.randint(1, 5) * Config.TICK_SIZE, 2)
+
+                qty = random.choice([50, 100, 150, 200, 250])
+
+                order = make_order(sym, side, price, qty)
+                producer.send(Config.ORDERS_TOPIC, order)
+                print(f"[MDF] Order: {order}")
+
+                # --- simulate small price drift (10% chance, max 2 ticks) ---
+                if random.random() < 0.10:
+                    drift = random.choice([-2, -1, 1, 2]) * Config.TICK_SIZE
+                    new_price = vals["current"] + drift
+                    # Keep price within reasonable bounds (min 1.00)
+                    if new_price >= 1.00:
+                        vals["current"] = round(new_price, 2)
+                        save_securities(securities)
+
+                # --- snapshot around mid price ---
+                best_bid = mid - half_spread
+                best_ask = mid + half_spread
+                bid_size = random.choice([50, 100, 200])
+                ask_size = random.choice([50, 100, 200])
+                snap = make_snapshot(sym, best_bid, best_ask, bid_size, ask_size)
+                producer.send(Config.SNAPSHOTS_TOPIC, snap)
+                print(f"[MDF] Snapshot: {snap}")
+
+                time.sleep(ORDER_INTERVAL)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        producer.flush()

oeg/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY oeg_simulator.py .
+
+# Install requests and any other deps
+RUN pip install --no-cache-dir requests
+RUN pip install --no-cache-dir kafka-python
+
+CMD ["python", "oeg_simulator.py"]

oeg/oeg_simulator.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+import time, json, random, requests, os
+FRONTEND = os.environ.get("FRONTEND_URL", "http://frontend:5000")
+SYMBOLS = ["FOO","AAA","BBB"]
+SIDES = ["buy","sell"]
+
+def post_order(order):
+    try:
+        r = requests.post(FRONTEND + "/submit", json=order, timeout=5)
+        print(json.dumps({"component":"oeg","event":"post_order","payload":{"order":order,"status":r.status_code}}))
+    except Exception as e:
+        print(json.dumps({"component":"oeg","event":"post_failed","payload":{"order":order,"error":str(e)}}))
+
+if __name__ == "__main__":
+    try:
+        while True:
+            order = {
+                "order_id": str(int(time.time()*1000)),
+                "symbol": random.choice(SYMBOLS),
+                "type": random.choice(SIDES),
+                "quantity": random.choice([5,10,20]),
+                "price": round(100 + random.uniform(-1,1),2),
+                "timestamp": time.time(),
+                "source": "oeg-sim"
+            }
+            post_order(order)
+            time.sleep(2.0)
+    except KeyboardInterrupt:
+        pass

requirements.txt

@@ -0,0 +1,2 @@
+quickfix
+flask

shared/__init__.py

@@ -0,0 +1,6 @@
+"""Shared utilities and configuration for Kafka Trading System."""
+
+from .config import Config
+from .kafka_utils import create_producer, create_consumer
+
+__all__ = ["Config", "create_producer", "create_consumer"]

shared/config.py

@@ -0,0 +1,31 @@
+"""Centralized configuration for all services."""
+
+import os
+
+
+class Config:
+    """Configuration loaded from environment variables with sensible defaults."""
+
+    # Kafka connection
+    KAFKA_BOOTSTRAP: str = os.getenv("KAFKA_BOOTSTRAP", "kafka:9092")
+
+    # Topic names
+    ORDERS_TOPIC: str = os.getenv("ORDERS_TOPIC", "orders")
+    TRADES_TOPIC: str = os.getenv("TRADES_TOPIC", "trades")
+    SNAPSHOTS_TOPIC: str = os.getenv("SNAPSHOTS_TOPIC", "snapshots")
+
+    # Connection retry settings
+    KAFKA_RETRIES: int = int(os.getenv("KAFKA_RETRIES", "30"))
+    KAFKA_RETRY_DELAY: int = int(os.getenv("KAFKA_RETRY_DELAY", "2"))
+
+    # Service URLs
+    MATCHER_URL: str = os.getenv("MATCHER_URL", "http://matcher:6000")
+    FRONTEND_URL: str = os.getenv("FRONTEND_URL", "http://frontend:5000")
+
+    # Market data settings
+    SECURITIES_FILE: str = os.getenv("SECURITIES_FILE", "/app/data/securities.txt")
+    ORDER_ID_FILE: str = os.getenv("ORDER_ID_FILE", "/app/data/order_id.txt")
+
+    # Trading simulation
+    TICK_SIZE: float = float(os.getenv("TICK_SIZE", "0.05"))
+    ORDERS_PER_MIN: int = int(os.getenv("ORDERS_PER_MIN", "8"))

shared/kafka_utils.py

@@ -0,0 +1,114 @@
+"""Reusable Kafka producer and consumer utilities."""
+
+import json
+import time
+import logging
+from typing import Optional, List, Union
+
+from kafka import KafkaProducer, KafkaConsumer
+from kafka.errors import NoBrokersAvailable
+
+from .config import Config
+
+logger = logging.getLogger(__name__)
+
+
+def create_producer(
+    bootstrap_servers: Optional[str] = None,
+    retries: Optional[int] = None,
+    delay: Optional[int] = None,
+    component_name: str = "Service",
+) -> KafkaProducer:
+    """
+    Create a Kafka producer with retry logic.
+
+    Args:
+        bootstrap_servers: Kafka broker address (default: from Config)
+        retries: Number of connection attempts (default: from Config)
+        delay: Seconds between retries (default: from Config)
+        component_name: Name for logging purposes
+
+    Returns:
+        Connected KafkaProducer instance
+
+    Raises:
+        RuntimeError: If connection fails after all retries
+    """
+    bootstrap_servers = bootstrap_servers or Config.KAFKA_BOOTSTRAP
+    retries = retries if retries is not None else Config.KAFKA_RETRIES
+    delay = delay if delay is not None else Config.KAFKA_RETRY_DELAY
+
+    for attempt in range(retries):
+        try:
+            producer = KafkaProducer(
+                bootstrap_servers=bootstrap_servers,
+                value_serializer=lambda v: json.dumps(v).encode("utf-8"),
+            )
+            logger.info(f"{component_name}: Kafka producer connected")
+            print(f"{component_name}: Kafka producer connected")
+            return producer
+        except NoBrokersAvailable:
+            logger.warning(
+                f"{component_name}: Kafka not ready, retry {attempt + 1}/{retries}"
+            )
+            print(f"{component_name}: Kafka not ready, retry {attempt + 1}/{retries}")
+            time.sleep(delay)
+
+    raise RuntimeError(f"{component_name}: Cannot connect to Kafka after {retries} attempts")
+
+
+def create_consumer(
+    topics: Union[str, List[str]],
+    bootstrap_servers: Optional[str] = None,
+    group_id: Optional[str] = None,
+    auto_offset_reset: str = "latest",
+    retries: Optional[int] = None,
+    delay: Optional[int] = None,
+    component_name: str = "Service",
+) -> KafkaConsumer:
+    """
+    Create a Kafka consumer with retry logic.
+
+    Args:
+        topics: Topic name or list of topic names to subscribe to
+        bootstrap_servers: Kafka broker address (default: from Config)
+        group_id: Consumer group ID
+        auto_offset_reset: Where to start reading ('earliest' or 'latest')
+        retries: Number of connection attempts (default: from Config)
+        delay: Seconds between retries (default: from Config)
+        component_name: Name for logging purposes
+
+    Returns:
+        Connected KafkaConsumer instance
+
+    Raises:
+        RuntimeError: If connection fails after all retries
+    """
+    bootstrap_servers = bootstrap_servers or Config.KAFKA_BOOTSTRAP
+    retries = retries if retries is not None else Config.KAFKA_RETRIES
+    delay = delay if delay is not None else Config.KAFKA_RETRY_DELAY
+
+    # Ensure topics is a list
+    if isinstance(topics, str):
+        topics = [topics]
+
+    for attempt in range(retries):
+        try:
+            consumer = KafkaConsumer(
+                *topics,
+                bootstrap_servers=bootstrap_servers,
+                value_deserializer=lambda v: json.loads(v.decode("utf-8")),
+                group_id=group_id,
+                auto_offset_reset=auto_offset_reset,
+            )
+            logger.info(f"{component_name}: Kafka consumer connected to {topics}")
+            print(f"{component_name}: Kafka consumer connected to {topics}")
+            return consumer
+        except NoBrokersAvailable:
+            logger.warning(
+                f"{component_name}: Kafka not ready, retry {attempt + 1}/{retries}"
+            )
+            print(f"{component_name}: Kafka not ready, retry {attempt + 1}/{retries}")
+            time.sleep(delay)
+
+    raise RuntimeError(f"{component_name}: Cannot connect to Kafka after {retries} attempts")

shared/logging_utils.py

@@ -0,0 +1,168 @@
+"""Structured logging utilities for the trading system.
+
+Provides JSON-formatted logging with correlation IDs for tracing
+requests across services.
+"""
+import logging
+import json
+import time
+import uuid
+import threading
+from functools import wraps
+
+# Thread-local storage for correlation ID
+_context = threading.local()
+
+
+def get_correlation_id():
+    """Get current correlation ID, or generate a new one."""
+    if not hasattr(_context, 'correlation_id') or _context.correlation_id is None:
+        _context.correlation_id = str(uuid.uuid4())[:8]
+    return _context.correlation_id
+
+
+def set_correlation_id(correlation_id):
+    """Set correlation ID for current thread."""
+    _context.correlation_id = correlation_id
+
+
+def clear_correlation_id():
+    """Clear correlation ID for current thread."""
+    _context.correlation_id = None
+
+
+class JSONFormatter(logging.Formatter):
+    """JSON log formatter for structured logging."""
+
+    def format(self, record):
+        log_entry = {
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(record.created)),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "correlation_id": get_correlation_id(),
+        }
+
+        # Add component if set
+        if hasattr(record, 'component'):
+            log_entry["component"] = record.component
+
+        # Add extra fields
+        if hasattr(record, 'extra_data') and record.extra_data:
+            log_entry.update(record.extra_data)
+
+        # Add exception info if present
+        if record.exc_info:
+            log_entry["exception"] = self.formatException(record.exc_info)
+
+        # Add source location for errors
+        if record.levelno >= logging.ERROR:
+            log_entry["source"] = {
+                "file": record.filename,
+                "line": record.lineno,
+                "function": record.funcName
+            }
+
+        return json.dumps(log_entry)
+
+
+def setup_logging(component_name, level=logging.INFO, json_format=True):
+    """Configure logging for a service component.
+
+    Args:
+        component_name: Name of the service (e.g., "matcher", "dashboard")
+        level: Logging level
+        json_format: Use JSON formatting (True) or standard format (False)
+
+    Returns:
+        Logger instance
+    """
+    logger = logging.getLogger(component_name)
+    logger.setLevel(level)
+
+    # Remove existing handlers
+    logger.handlers = []
+
+    # Create console handler
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        ))
+
+    logger.addHandler(handler)
+
+    return logger
+
+
+class StructuredLogger:
+    """Convenience wrapper for structured logging."""
+
+    def __init__(self, component_name, json_format=True):
+        self.logger = setup_logging(component_name, json_format=json_format)
+        self.component = component_name
+
+    def _log(self, level, message, **extra):
+        """Internal logging method with extra data."""
+        record = self.logger.makeRecord(
+            self.logger.name, level, "", 0, message, (), None
+        )
+        record.component = self.component
+        record.extra_data = extra if extra else None
+        self.logger.handle(record)
+
+    def info(self, message, **extra):
+        self._log(logging.INFO, message, **extra)
+
+    def debug(self, message, **extra):
+        self._log(logging.DEBUG, message, **extra)
+
+    def warning(self, message, **extra):
+        self._log(logging.WARNING, message, **extra)
+
+    def error(self, message, **extra):
+        self._log(logging.ERROR, message, **extra)
+
+    def order_received(self, order_id, symbol, side, quantity, price, source=None):
+        """Log order received event."""
+        self.info("order_received", event="order_received",
+                  order_id=order_id, symbol=symbol, side=side,
+                  quantity=quantity, price=price, source=source)
+
+    def trade_executed(self, trade_id, symbol, price, quantity, buy_id, sell_id):
+        """Log trade execution event."""
+        self.info("trade_executed", event="trade_executed",
+                  trade_id=trade_id, symbol=symbol, price=price,
+                  quantity=quantity, buy_id=buy_id, sell_id=sell_id)
+
+    def order_cancelled(self, order_id, reason=None):
+        """Log order cancellation event."""
+        self.info("order_cancelled", event="order_cancelled",
+                  order_id=order_id, reason=reason)
+
+
+def with_correlation_id(func):
+    """Decorator to set correlation ID for request handling."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        # Check for correlation ID in headers (for Flask)
+        try:
+            from flask import request
+            correlation_id = request.headers.get('X-Correlation-ID')
+            if correlation_id:
+                set_correlation_id(correlation_id)
+            else:
+                set_correlation_id(str(uuid.uuid4())[:8])
+        except:
+            set_correlation_id(str(uuid.uuid4())[:8])
+
+        try:
+            return func(*args, **kwargs)
+        finally:
+            clear_correlation_id()
+
+    return wrapper

shared_data/securities.txt

@@ -0,0 +1,5 @@
+#SYMBOL	<start_price>	<current_price>
+ALPHA	24.90	24.95
+PEIR	18.50	18.05
+EXAE	42.00	42.05
+QUEST	12.70	12.60

snapshot_viewer/Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+RUN pip install --no-cache-dir kafka-python
+
+COPY snapshot_viewer.py .
+
+CMD ["python", "snapshot_viewer.py"]

snapshot_viewer/snapshot_viewer.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+import sys
+sys.path.insert(0, "/app")
+
+import json
+import os
+import time
+from datetime import datetime
+
+from shared.config import Config
+from shared.kafka_utils import create_consumer
+
+# keep only last BBO per symbol
+last_bbo = {}
+
+def pretty_print(snapshot):
+    bids = snapshot.get("bids", [])
+    asks = snapshot.get("asks", [])
+
+    valid_bids = [b for b in bids if b["qty"] > 0]
+    valid_asks = [a for a in asks if a["qty"] > 0]
+
+    best_bid = max(valid_bids, key=lambda b: b["price"], default=None)
+    best_ask = min(valid_asks, key=lambda a: a["price"], default=None)
+
+    symbol = snapshot.get("symbol", "UNKNOWN")
+    now = datetime.utcnow().strftime("%H:%M:%S")
+
+    last_bbo[symbol] = {
+        "best_bid": best_bid,
+        "best_ask": best_ask,
+        "time": now,
+    }
+
+    print(f"\n Market Data Snapshot: {symbol} {now}")
+
+    print("\n  BIDS:")
+    if best_bid:
+        print(f"   {best_bid['qty']:>6} @ {best_bid['price']:.2f}")
+    else:
+        print("   None")
+
+    print("\n  ASKS:")
+    if best_ask:
+        print(f"   {best_ask['qty']:>6} @ {best_ask['price']:.2f}")
+    else:
+        print("   None")
+
+    print("\nBest Bid :", best_bid["price"] if best_bid else "None")
+    print("Best Ask:", best_ask["price"] if best_ask else "None")
+
+
+if __name__ == "__main__":
+    consumer = create_consumer(
+        topics=Config.SNAPSHOTS_TOPIC,
+        group_id="snapshot-viewer",
+        component_name="SnapshotViewer"
+    )
+    print(f"Subscribed to {Config.SNAPSHOTS_TOPIC}, showing only latest BBO per symbol\n")
+
+    for msg in consumer:
+        snapshot = msg.value
+        if snapshot.get("type") == "snapshot":
+            pretty_print(snapshot)