# openexch/match architecture

> Architecture diagram of the GitHub repository openexch/match, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openexch/match
- Repository: https://github.com/openexch/match

## Overview

Match Engine is the clustered matching core of an exchange stack; the README places order management and risk upstream in a separate OMS. The principal workflow is order ingress through Aeron consensus, command dispatch and per-market matching, then egress to market-data clients. The gateway also maintains live market state, streams WebSocket updates, and offers persisted historical data with in-memory fallback. The graph preserves create/cancel/update, cluster recovery, and load-generation capabilities. Some gateway and cluster wiring is based on the documented flow and module roles; unsampled internals are not expanded.

Main entry points: [`match-cluster/src/main/java/com/match/infrastructure/persistence/AppClusteredService.java`](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/AppClusteredService.java) (Cluster service), [`match-gateway/src/main/java/com/match/infrastructure/gateway/state/GatewayStateManager.java`](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/state/GatewayStateManager.java) (Gateway state), [`match-cluster/src/main/java/com/match/application/engine/Engine.java`](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/engine/Engine.java) (Order engine), [`match-cluster/src/main/java/com/match/application/orderbook/DirectMatchingEngine.java`](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/orderbook/DirectMatchingEngine.java) (Matching engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Order ingress"]
  node_order_gateway["Order gateway"]
  node_aeron_gateway["Aeron gateway<br/>[AeronGateway.java]"]
end

subgraph group_matching["Matching core"]
  node_engine["Order engine<br/>[Engine.java]"]
  node_handlers["Order handlers"]
  node_matching_engine["Matching engine"]
  node_orderbook["Direct order book"]
  node_domain["Order domain<br/>[Order.java]"]
  node_publisher["Event publisher"]
end

subgraph group_cluster["Cluster runtime"]
  node_cluster["Aeron cluster<br/>[AeronCluster.java]"]
  node_cluster_service["Cluster service"]
  node_demuxer["Command demuxer<br/>[SbeDemuxer.java]"]
  node_journal["Settlement journal"]
  node_snapshot["Snapshot codec<br/>[SnapshotCodec.java]"]
end

subgraph group_marketdata["Market data"]
  node_market_gateway["Market gateway<br/>[AeronGateway.java]"]
  node_state["Gateway state"]
  node_ws["WebSocket service"]
  node_subscriptions["Subscriptions"]
  node_market_db[("Market data store<br/>[MarketDataDb.java]")]
  node_trade_writer["Trade writer<br/>[TradeWriter.java]"]
  node_read_service["Historical reads"]
  node_rolling_ticker["Rolling ticker"]
end

subgraph group_clients["Clients and storage"]
  node_market_clients(("Market clients"))
  node_load_generator["Load generator<br/>[LoadGenerator.java]"]
end

node_oms["OMS"]

node_oms -->|"submits orders"| node_order_gateway
node_order_gateway -->|"forwards ingress"| node_aeron_gateway
node_aeron_gateway -->|"sends commands"| node_cluster
node_cluster -->|"dispatches events"| node_cluster_service
node_cluster_service -->|"decodes commands"| node_demuxer
node_demuxer -->|"dispatches commands"| node_engine
node_engine -->|"selects handler"| node_handlers
node_engine -->|"processes order"| node_matching_engine
node_matching_engine -->|"reads and updates"| node_orderbook
node_matching_engine -->|"match results"| node_publisher
node_publisher -->|"publishes egress"| node_cluster_service
node_cluster_service -->|"records settlement"| node_journal
node_cluster_service -->|"encodes state"| node_snapshot
node_snapshot -->|"restores state"| node_cluster_service
node_cluster_service -->|"sends market egress"| node_market_gateway
node_market_gateway -->|"updates market state"| node_state
node_state -->|"broadcasts updates"| node_ws
node_ws -->|"routes subscribers"| node_subscriptions
node_market_clients -->|"subscribes"| node_ws
node_state -->|"provides trades"| node_trade_writer
node_trade_writer -->|"writes trades"| node_market_db
node_read_service -->|"reads history"| node_market_db
node_rolling_ticker -->|"reads baselines"| node_market_db
node_rolling_ticker -->|"updates ticker state"| node_state
node_market_clients -->|"requests history"| node_read_service
node_load_generator -.->|"submits load"| node_order_gateway

click node_order_gateway "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/GatewayHttpHandler.java"
click node_aeron_gateway "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java"
click node_cluster "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/AeronCluster.java"
click node_cluster_service "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/AppClusteredService.java"
click node_demuxer "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/SbeDemuxer.java"
click node_engine "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/engine/Engine.java"
click node_handlers "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/handlers/LimitOrderHandler.java"
click node_matching_engine "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/orderbook/DirectMatchingEngine.java"
click node_orderbook "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/orderbook/DirectIndexOrderBook.java"
click node_domain "https://github.com/openexch/match/blob/main/match-common/src/main/java/com/match/domain/Order.java"
click node_publisher "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/publisher/MatchEventPublisher.java"
click node_journal "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/journal/SettlementJournal.java"
click node_snapshot "https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/SnapshotCodec.java"
click node_market_gateway "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java"
click node_state "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/state/GatewayStateManager.java"
click node_ws "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/websocket/MarketDataWebSocket.java"
click node_subscriptions "https://github.com/openexch/match/blob/main/match-common/src/main/java/com/match/infrastructure/websocket/SubscriptionManager.java"
click node_market_db "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataDb.java"
click node_trade_writer "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/TradeWriter.java"
click node_read_service "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataReadService.java"
click node_rolling_ticker "https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/RollingTickerService.java"
click node_load_generator "https://github.com/openexch/match/blob/main/match-loadtest/src/main/java/com/match/loadtest/LoadGenerator.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_order_gateway,node_aeron_gateway toneBlue
class node_engine,node_handlers,node_matching_engine,node_orderbook,node_domain,node_publisher toneAmber
class node_cluster,node_cluster_service,node_demuxer,node_journal,node_snapshot toneMint
class node_market_gateway,node_state,node_ws,node_subscriptions,node_market_db,node_trade_writer,node_read_service,node_rolling_ticker toneRose
class node_market_clients,node_load_generator,node_oms toneIndigo
```

## Components

### Order ingress

- [Order gateway](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/GatewayHttpHandler.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/GatewayHttpHandler.java`
- [Aeron gateway](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java`

### Matching core

- [Order engine](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/engine/Engine.java): `match-cluster/src/main/java/com/match/application/engine/Engine.java`
- [Order handlers](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/handlers/LimitOrderHandler.java): `match-cluster/src/main/java/com/match/application/handlers/LimitOrderHandler.java`
- [Matching engine](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/orderbook/DirectMatchingEngine.java): `match-cluster/src/main/java/com/match/application/orderbook/DirectMatchingEngine.java`
- [Direct order book](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/orderbook/DirectIndexOrderBook.java): `match-cluster/src/main/java/com/match/application/orderbook/DirectIndexOrderBook.java`
- [Order domain](https://github.com/openexch/match/blob/main/match-common/src/main/java/com/match/domain/Order.java): `match-common/src/main/java/com/match/domain/Order.java`
- [Event publisher](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/application/publisher/MatchEventPublisher.java): `match-cluster/src/main/java/com/match/application/publisher/MatchEventPublisher.java`

### Cluster runtime

- [Aeron cluster](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/AeronCluster.java): `match-cluster/src/main/java/com/match/infrastructure/persistence/AeronCluster.java`
- [Cluster service](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/AppClusteredService.java): `match-cluster/src/main/java/com/match/infrastructure/persistence/AppClusteredService.java`
- [Command demuxer](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/SbeDemuxer.java): `match-cluster/src/main/java/com/match/infrastructure/persistence/SbeDemuxer.java`
- [Settlement journal](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/journal/SettlementJournal.java): `match-cluster/src/main/java/com/match/infrastructure/journal/SettlementJournal.java`
- [Snapshot codec](https://github.com/openexch/match/blob/main/match-cluster/src/main/java/com/match/infrastructure/persistence/SnapshotCodec.java): `match-cluster/src/main/java/com/match/infrastructure/persistence/SnapshotCodec.java`

### Market data

- [Market gateway](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/AeronGateway.java`
- [Gateway state](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/state/GatewayStateManager.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/state/GatewayStateManager.java`
- [WebSocket service](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/websocket/MarketDataWebSocket.java): `match-gateway/src/main/java/com/match/infrastructure/websocket/MarketDataWebSocket.java`
- [Subscriptions](https://github.com/openexch/match/blob/main/match-common/src/main/java/com/match/infrastructure/websocket/SubscriptionManager.java): `match-common/src/main/java/com/match/infrastructure/websocket/SubscriptionManager.java`
- [Market data store](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataDb.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataDb.java`
- [Trade writer](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/TradeWriter.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/TradeWriter.java`
- [Historical reads](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataReadService.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/MarketDataReadService.java`
- [Rolling ticker](https://github.com/openexch/match/blob/main/match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/RollingTickerService.java): `match-gateway/src/main/java/com/match/infrastructure/gateway/persistence/RollingTickerService.java`

### Clients and storage

- **Market clients**
- [Load generator](https://github.com/openexch/match/blob/main/match-loadtest/src/main/java/com/match/loadtest/LoadGenerator.java): `match-loadtest/src/main/java/com/match/loadtest/LoadGenerator.java`

### Other components

- **OMS**

## Connections

- OMS → Order gateway: submits orders
- Order gateway → Aeron gateway: forwards ingress
- Aeron gateway → Aeron cluster: sends commands
- Aeron cluster → Cluster service: dispatches events
- Cluster service → Command demuxer: decodes commands
- Command demuxer → Order engine: dispatches commands
- Order engine → Order handlers: selects handler
- Order engine → Matching engine: processes order
- Matching engine → Direct order book: reads and updates
- Matching engine → Event publisher: match results
- Event publisher → Cluster service: publishes egress
- Cluster service → Settlement journal: records settlement
- Cluster service → Snapshot codec: encodes state
- Snapshot codec → Cluster service: restores state
- Cluster service → Market gateway: sends market egress
- Market gateway → Gateway state: updates market state
- Gateway state → WebSocket service: broadcasts updates
- WebSocket service → Subscriptions: routes subscribers
- Market clients → WebSocket service: subscribes
- Gateway state → Trade writer: provides trades
- Trade writer → Market data store: writes trades
- Historical reads → Market data store: reads history
- Rolling ticker → Market data store: reads baselines
- Rolling ticker → Gateway state: updates ticker state
- Market clients → Historical reads: requests history
- Load generator → Order gateway: submits load