# rbala25/hermes architecture

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

- Interactive diagram: https://gitdiagram.com/rbala25/hermes
- Repository: https://github.com/rbala25/hermes

## Overview

Hermes is an FPGA-based market-making engine: it parses CME market data, updates an order book, computes quotes, applies risk controls, and sends exchange-native orders. The README describes the receive and transmit paths and identifies mm_top as the orchestrator. The RTL sources were not excerpted, so edges below are supported by README statements; the risk-control node is documented as a capability but its exact implementing module is not established by the available evidence.

Main entry points: [`Hermes.srcs/sources_1/new/mm_top.sv`](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mm_top.sv) (Trading Orchestrator), [`Hermes.srcs/sources_1/new/mii_rx.sv`](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mii_rx.sv) (MII Receive), [`Hermes.srcs/sources_1/new/eth_parser.sv`](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_parser.sv) (Ethernet Parser), [`Hermes.srcs/sources_1/new/eth_tx.sv`](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_tx.sv) (Ethernet Transmit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_data["Market Data"]
  node_mdp_parser["MDP Parser<br/>[mdp_parser.sv]"]
  node_order_book[("Order Book<br/>[order_book.sv]")]
end

subgraph group_trading["Trading Logic"]
  node_mm_core["Market Maker<br/>[mm_core.sv]"]
  node_risk_controls["Risk Controls<br/>[new]"]
  node_mm_top["Trading Orchestrator<br/>[mm_top.sv]"]
end

subgraph group_session["Order Entry"]
  node_ilink_tx["iLink Transmit<br/>[ilink_tx.sv]"]
  node_ilink_rx["iLink Receive<br/>[ilink_rx.sv]"]
  node_tcp_session["TCP Session<br/>[tcp_session.sv]"]
end

subgraph group_network["Network Stack"]
  node_mii_rx["MII Receive<br/>[mii_rx.sv]"]
  node_eth_parser["Ethernet Parser<br/>[eth_parser.sv]"]
  node_ip_parser["IPv4 Parser<br/>[ip_parser.sv]"]
  node_udp_parser["UDP Parser<br/>[udp_parser.sv]"]
  node_tcp_rx["TCP Receive<br/>[tcp_rx.sv]"]
  node_tcp_tx["TCP Transmit<br/>[tcp_tx.sv]"]
  node_ip_tx["IPv4 Transmit<br/>[ip_tx.sv]"]
  node_eth_tx["Ethernet Transmit<br/>[eth_tx.sv]"]
  node_mii_tx["MII Transmit<br/>[mii_tx.sv]"]
  node_icmp_parser["ICMP Parser<br/>[icmp_parser.sv]"]
  node_icmp_tx["ICMP Transmit<br/>[icmp_tx.sv]"]
  node_arp_handler["ARP Handler<br/>[arp_handler.sv]"]
  node_mdio_init["MDIO PHY Setup<br/>[mdio_init.sv]"]
  node_rgmii_rx["RGMII Receive<br/>[rgmii_rx.sv]"]
end

node_cme_feed(("CME Feed"))
node_exchange(("CME Exchange"))

node_cme_feed -->|"sends frames"| node_mii_rx
node_mii_rx -->|"receives frames"| node_eth_parser
node_eth_parser -->|"parses IPv4"| node_ip_parser
node_ip_parser -->|"dispatches UDP"| node_udp_parser
node_udp_parser -->|"delivers market data"| node_mdp_parser
node_mdp_parser -->|"updates book"| node_order_book
node_order_book -->|"provides book state"| node_mm_core
node_mm_core -->|"provides quote logic"| node_mm_top
node_mm_top -.->|"checks orders"| node_risk_controls
node_mm_top -->|"sequences orders"| node_ilink_tx
node_ilink_rx -->|"provides handshake state"| node_mm_top
node_tcp_rx -->|"delivers session data"| node_ilink_rx
node_tcp_session -->|"manages session"| node_mm_top
node_ilink_tx -->|"sends order messages"| node_tcp_tx
node_tcp_tx -->|"encapsulates TCP"| node_ip_tx
node_ip_tx -->|"encapsulates IPv4"| node_eth_tx
node_eth_tx -->|"transmits frames"| node_mii_tx
node_mii_tx -->|"sends orders"| node_exchange
node_icmp_parser -.->|"supports ICMP"| node_icmp_tx
node_arp_handler -.->|"supports ARP frames"| node_eth_tx
node_mdio_init -->|"configures PHY"| node_mii_rx
node_rgmii_rx -.->|"supports RGMII input"| node_eth_parser

click node_mii_rx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mii_rx.sv"
click node_eth_parser "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_parser.sv"
click node_ip_parser "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ip_parser.sv"
click node_udp_parser "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/udp_parser.sv"
click node_mdp_parser "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mdp_parser.sv"
click node_order_book "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/order_book.sv"
click node_mm_core "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mm_core.sv"
click node_risk_controls "https://github.com/rbala25/hermes/tree/main/Hermes.srcs/sources_1/new"
click node_mm_top "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mm_top.sv"
click node_ilink_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ilink_tx.sv"
click node_ilink_rx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ilink_rx.sv"
click node_tcp_session "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_session.sv"
click node_tcp_rx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_rx.sv"
click node_tcp_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_tx.sv"
click node_ip_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ip_tx.sv"
click node_eth_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_tx.sv"
click node_mii_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mii_tx.sv"
click node_icmp_parser "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/icmp_parser.sv"
click node_icmp_tx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/icmp_tx.sv"
click node_arp_handler "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/arp_handler.sv"
click node_mdio_init "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mdio_init.sv"
click node_rgmii_rx "https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/rgmii_rx.sv"

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_mdp_parser,node_order_book toneBlue
class node_mm_core,node_risk_controls,node_mm_top toneAmber
class node_ilink_tx,node_ilink_rx,node_tcp_session toneMint
class node_mii_rx,node_eth_parser,node_ip_parser,node_udp_parser,node_tcp_rx,node_tcp_tx,node_ip_tx,node_eth_tx,node_mii_tx,node_icmp_parser,node_icmp_tx,node_arp_handler,node_mdio_init,node_rgmii_rx toneRose
class node_cme_feed,node_exchange toneIndigo
```

## Components

### Market Data

- [MDP Parser](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mdp_parser.sv): `Hermes.srcs/sources_1/new/mdp_parser.sv`
- [Order Book](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/order_book.sv): `Hermes.srcs/sources_1/new/order_book.sv`

### Trading Logic

- [Market Maker](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mm_core.sv): `Hermes.srcs/sources_1/new/mm_core.sv`
- [Risk Controls](https://github.com/rbala25/hermes/tree/main/Hermes.srcs/sources_1/new): `Hermes.srcs/sources_1/new`
- [Trading Orchestrator](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mm_top.sv): `Hermes.srcs/sources_1/new/mm_top.sv`

### Order Entry

- [iLink Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ilink_tx.sv): `Hermes.srcs/sources_1/new/ilink_tx.sv`
- [iLink Receive](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ilink_rx.sv): `Hermes.srcs/sources_1/new/ilink_rx.sv`
- [TCP Session](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_session.sv): `Hermes.srcs/sources_1/new/tcp_session.sv`

### Network Stack

- [MII Receive](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mii_rx.sv): `Hermes.srcs/sources_1/new/mii_rx.sv`
- [Ethernet Parser](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_parser.sv): `Hermes.srcs/sources_1/new/eth_parser.sv`
- [IPv4 Parser](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ip_parser.sv): `Hermes.srcs/sources_1/new/ip_parser.sv`
- [UDP Parser](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/udp_parser.sv): `Hermes.srcs/sources_1/new/udp_parser.sv`
- [TCP Receive](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_rx.sv): `Hermes.srcs/sources_1/new/tcp_rx.sv`
- [TCP Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/tcp_tx.sv): `Hermes.srcs/sources_1/new/tcp_tx.sv`
- [IPv4 Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/ip_tx.sv): `Hermes.srcs/sources_1/new/ip_tx.sv`
- [Ethernet Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/eth_tx.sv): `Hermes.srcs/sources_1/new/eth_tx.sv`
- [MII Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mii_tx.sv): `Hermes.srcs/sources_1/new/mii_tx.sv`
- [ICMP Parser](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/icmp_parser.sv): `Hermes.srcs/sources_1/new/icmp_parser.sv`
- [ICMP Transmit](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/icmp_tx.sv): `Hermes.srcs/sources_1/new/icmp_tx.sv`
- [ARP Handler](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/arp_handler.sv): `Hermes.srcs/sources_1/new/arp_handler.sv`
- [MDIO PHY Setup](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/mdio_init.sv): `Hermes.srcs/sources_1/new/mdio_init.sv`
- [RGMII Receive](https://github.com/rbala25/hermes/blob/main/Hermes.srcs/sources_1/new/rgmii_rx.sv): `Hermes.srcs/sources_1/new/rgmii_rx.sv`

### Other components

- **CME Feed**
- **CME Exchange**

## Connections

- CME Feed → MII Receive: sends frames (evidence: `README.md`)
- MII Receive → Ethernet Parser: receives frames (evidence: `README.md`)
- Ethernet Parser → IPv4 Parser: parses IPv4 (evidence: `README.md`)
- IPv4 Parser → UDP Parser: dispatches UDP (evidence: `README.md`)
- UDP Parser → MDP Parser: delivers market data (evidence: `README.md`)
- MDP Parser → Order Book: updates book (evidence: `README.md`)
- Order Book → Market Maker: provides book state (evidence: `README.md`)
- Market Maker → Trading Orchestrator: provides quote logic (evidence: `README.md`)
- Trading Orchestrator → Risk Controls: checks orders
- Trading Orchestrator → iLink Transmit: sequences orders (evidence: `README.md`)
- iLink Receive → Trading Orchestrator: provides handshake state (evidence: `README.md`)
- TCP Receive → iLink Receive: delivers session data (evidence: `README.md`)
- TCP Session → Trading Orchestrator: manages session (evidence: `README.md`)
- iLink Transmit → TCP Transmit: sends order messages (evidence: `README.md`)
- TCP Transmit → IPv4 Transmit: encapsulates TCP (evidence: `README.md`)
- IPv4 Transmit → Ethernet Transmit: encapsulates IPv4 (evidence: `README.md`)
- Ethernet Transmit → MII Transmit: transmits frames (evidence: `README.md`)
- MII Transmit → CME Exchange: sends orders (evidence: `README.md`)
- ICMP Parser → ICMP Transmit: supports ICMP
- ARP Handler → Ethernet Transmit: supports ARP frames
- MDIO PHY Setup → MII Receive: configures PHY (evidence: `README.md`)
- RGMII Receive → Ethernet Parser: supports RGMII input (evidence: `README.md`)
