# asthamishra/matching-engine architecture

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

- Interactive diagram: https://gitdiagram.com/asthamishra/matching-engine
- Repository: https://github.com/asthamishra/matching-engine

## Overview

This repository is a Rust limit-order matching engine with OUCH/ITCH-style binary and REST adapters. The main workflow accepts an order, routes it to a symbol’s single-owner book, matches or updates it, and returns events or a query response. The README documents the layered runtime and shared engine; excerpts show concrete routing and book operations. Several runtime and protocol modules were not excerpted, so their connections are included only where the README supports them.

Main entry points: [`ouch-gateway/src/gateway.rs`](https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/gateway.rs) (OUCH gateway), [`matching-engine/src/client/order.rs`](https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/client/order.rs) (Order commands), [`matching-core/src/order_book.rs`](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/order_book.rs) (Order book), [`rest-gateway/src/order.rs`](https://github.com/asthamishra/matching-engine/blob/stable/rest-gateway/src/order.rs) (REST orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Matching core"]
  node_orders[("Order book<br/>[order_book.rs]")]
  node_matching["Match operations<br/>[matching.rs]"]
  node_order_types["Order types<br/>[order.rs]"]
  node_trade_types["Trade events<br/>[trade.rs]"]
  node_symbols[("Symbol registry<br/>[symbol_registry.rs]")]
  node_responses["Response types<br/>[response.rs]"]
end

subgraph group_runtime["Engine runtime"]
  node_app_state["Shared state<br/>[app_state.rs]"]
  node_exchange["Exchange setup<br/>[exchange.rs]"]
  node_matcher["Worker routing<br/>[matcher.rs]"]
  node_order_api["Order commands<br/>[order.rs]"]
end

subgraph group_ouch["OUCH gateway"]
  node_ouch_input["Inbound codec<br/>[inbound.rs]"]
  node_ouch_output["Outbound codec<br/>[outbound.rs]"]
  node_sessions["Client sessions<br/>[sessions.rs]"]
  node_ouch_gateway["OUCH gateway<br/>[gateway.rs]"]
end

subgraph group_rest["REST adapter"]
  node_rest_orders["REST orders<br/>[order.rs]"]
  node_rest_queries["Book queries<br/>[book.rs]"]
end

subgraph group_app["Application"]
  node_server["Server entry<br/>[main.rs]"]
end

node_trader(("Order client"))
node_http_client(("HTTP client"))
node_tcp_client(("TCP client"))

node_tcp_client -->|"sends orders"| node_ouch_gateway
node_ouch_gateway -->|"parses frames"| node_ouch_input
node_ouch_gateway -->|"matches orders"| node_orders
node_ouch_gateway -->|"modifies orders"| node_matching
node_ouch_gateway -->|"tracks orders"| node_sessions
node_ouch_gateway -.->|"encodes responses"| node_ouch_output
node_orders -->|"stores orders"| node_order_types
node_matching -->|"operates on"| node_orders
node_orders -.->|"emits events"| node_trade_types
node_trader -->|"submits commands"| node_order_api
node_order_api -->|"looks up symbols"| node_symbols
node_order_api -->|"routes requests"| node_matcher
node_matcher -->|"dispatches book work"| node_orders
node_exchange -.->|"starts workers"| node_matcher
node_exchange -.->|"provides shared state"| node_app_state
node_app_state -.->|"holds registry"| node_symbols
node_http_client -->|"submits orders"| node_rest_orders
node_http_client -->|"requests data"| node_rest_queries
node_rest_orders -->|"uses engine state"| node_app_state
node_rest_queries -->|"uses engine state"| node_app_state
node_rest_orders -.->|"routes commands"| node_order_api
node_rest_queries -->|"requests book data"| node_matcher
node_server -->|"wires gateway"| node_ouch_gateway
node_server -->|"mounts routes"| node_rest_orders
node_server -->|"wires engine"| node_exchange
node_order_api -.->|"returns results"| node_responses

click node_orders "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/order_book.rs"
click node_matching "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/matching.rs"
click node_order_types "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/types/order.rs"
click node_trade_types "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/types/trade.rs"
click node_symbols "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/symbol_registry.rs"
click node_responses "https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/response.rs"
click node_app_state "https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/app_state.rs"
click node_exchange "https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/exchange.rs"
click node_matcher "https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/matcher.rs"
click node_order_api "https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/client/order.rs"
click node_ouch_input "https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/codec/inbound.rs"
click node_ouch_output "https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/codec/outbound.rs"
click node_sessions "https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/sessions.rs"
click node_ouch_gateway "https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/gateway.rs"
click node_rest_orders "https://github.com/asthamishra/matching-engine/blob/stable/rest-gateway/src/order.rs"
click node_rest_queries "https://github.com/asthamishra/matching-engine/blob/stable/rest-gateway/src/book.rs"
click node_server "https://github.com/asthamishra/matching-engine/blob/stable/server/src/main.rs"

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_orders,node_matching,node_order_types,node_trade_types,node_symbols,node_responses,node_trader,node_http_client,node_tcp_client toneBlue
class node_app_state,node_exchange,node_matcher,node_order_api toneAmber
class node_ouch_input,node_ouch_output,node_sessions,node_ouch_gateway toneMint
class node_rest_orders,node_rest_queries toneRose
class node_server toneIndigo
```

## Components

### Matching core

- [Order book](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/order_book.rs): `matching-core/src/order_book.rs`
- [Match operations](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/matching.rs): `matching-core/src/matching.rs`
- [Order types](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/types/order.rs): `matching-core/src/types/order.rs`
- [Trade events](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/types/trade.rs): `matching-core/src/types/trade.rs`
- [Symbol registry](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/symbol_registry.rs): `matching-core/src/symbol_registry.rs`
- [Response types](https://github.com/asthamishra/matching-engine/blob/stable/matching-core/src/response.rs): `matching-core/src/response.rs`

### Engine runtime

- [Shared state](https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/app_state.rs): `matching-engine/src/app_state.rs`
- [Exchange setup](https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/exchange.rs): `matching-engine/src/exchange.rs`
- [Worker routing](https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/matcher.rs): `matching-engine/src/matcher.rs`
- [Order commands](https://github.com/asthamishra/matching-engine/blob/stable/matching-engine/src/client/order.rs): `matching-engine/src/client/order.rs`

### OUCH gateway

- [Inbound codec](https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/codec/inbound.rs): `ouch-gateway/src/codec/inbound.rs`
- [Outbound codec](https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/codec/outbound.rs): `ouch-gateway/src/codec/outbound.rs`
- [Client sessions](https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/sessions.rs): `ouch-gateway/src/sessions.rs`
- [OUCH gateway](https://github.com/asthamishra/matching-engine/blob/stable/ouch-gateway/src/gateway.rs): `ouch-gateway/src/gateway.rs`

### REST adapter

- [REST orders](https://github.com/asthamishra/matching-engine/blob/stable/rest-gateway/src/order.rs): `rest-gateway/src/order.rs`
- [Book queries](https://github.com/asthamishra/matching-engine/blob/stable/rest-gateway/src/book.rs): `rest-gateway/src/book.rs`

### Application

- [Server entry](https://github.com/asthamishra/matching-engine/blob/stable/server/src/main.rs): `server/src/main.rs`

### Other components

- **Order client**
- **HTTP client**
- **TCP client**

## Connections

- TCP client → OUCH gateway: sends orders
- OUCH gateway → Inbound codec: parses frames (evidence: `ouch-gateway/src/gateway.rs`)
- OUCH gateway → Order book: matches orders (evidence: `ouch-gateway/src/gateway.rs`)
- OUCH gateway → Match operations: modifies orders (evidence: `ouch-gateway/src/gateway.rs`)
- OUCH gateway → Client sessions: tracks orders (evidence: `ouch-gateway/src/gateway.rs`)
- OUCH gateway → Outbound codec: encodes responses
- Order book → Order types: stores orders (evidence: `matching-core/src/order_book.rs`)
- Match operations → Order book: operates on
- Order book → Trade events: emits events
- Order client → Order commands: submits commands
- Order commands → Symbol registry: looks up symbols (evidence: `matching-engine/src/client/order.rs`)
- Order commands → Worker routing: routes requests (evidence: `matching-engine/src/client/order.rs`)
- Worker routing → Order book: dispatches book work
- Exchange setup → Worker routing: starts workers
- Exchange setup → Shared state: provides shared state
- Shared state → Symbol registry: holds registry
- HTTP client → REST orders: submits orders
- HTTP client → Book queries: requests data
- REST orders → Shared state: uses engine state
- Book queries → Shared state: uses engine state (evidence: `rest-gateway/src/book.rs`)
- REST orders → Order commands: routes commands
- Book queries → Worker routing: requests book data (evidence: `rest-gateway/src/book.rs`)
- Server entry → OUCH gateway: wires gateway
- Server entry → REST orders: mounts routes
- Server entry → Exchange setup: wires engine
- Order commands → Response types: returns results
