# dilanj123/wire-to-decision architecture

> Architecture diagram of the GitHub repository dilanj123/wire-to-decision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dilanj123/wire-to-decision
- Repository: https://github.com/dilanj123/wire-to-decision

## Overview

Wire-to-Decision is an FPGA datapath that converts a framed post-MAC Ethernet stream into a bounded order-book mutation and, when configured thresholds are crossed, a BUY/SELL event. The documented Architecture A flow validates Ethernet/IP/UDP and Mold framing, decodes the supported ITCH subset, updates order state, then evaluates a decision. The Python package is a functional reference oracle; the C++ replay checker independently derives decisions for comparison with RTL-exported logs. Edges among RTL stages follow the README’s datapath; model orchestration is supported by the oracle excerpt. RTL internals and C++ call paths were not sampled.

Main entry points: [`model/python/wire_to_decision/oracle.py`](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/oracle.py) (Reference oracle), [`tools/cpp/checker.cpp`](https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/checker.cpp) (Replay checker), [`model/python/wire_to_decision/framing.py`](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/framing.py) (Packet framing model), [`model/python/wire_to_decision/book.py`](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/book.py) (Order book model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Ingress and framing"]
  node_ingress_buffer["Ingress buffer"]
  node_gearbox["64-to-8 gearbox"]
  node_ethernet["Ethernet parser<br/>[wire_eth_parser.sv]"]
  node_ipv4["IPv4 parser"]
  node_udp["UDP parser<br/>[wire_udp_parser.sv]"]
  node_mold_header["Mold header sequence"]
  node_mold_framer["Mold message framer"]
  node_async_fifo["Optional CDC FIFO<br/>[wire_async_fifo.sv]"]
end

subgraph group_mutation["Mutation and decision"]
  node_itch["ITCH decoder"]
  node_order_book[("Order store<br/>[wire_order_book.sv]")]
  node_decision_engine["Decision engine"]
  node_functional_top["Architecture A top"]
end

subgraph group_reference["Python reference model"]
  node_model_framing["Packet framing model<br/>[framing.py]"]
  node_model_mold["Mold parser model<br/>[mold.py]"]
  node_model_itch["ITCH decoder model<br/>[itch.py]"]
  node_model_book[("Order book model<br/>[book.py]")]
  node_model_hash["Order-set hash<br/>[hash.py]"]
  node_model_decision["Decision model<br/>[decision.py]"]
  node_model_checksum["IPv4 checksum<br/>[checksum.py]"]
  node_model_oracle["Reference oracle<br/>[oracle.py]"]
  node_model_types["Canonical types<br/>[types.py]"]
  node_model_constants["Model constants<br/>[constants.py]"]
  node_model_errors["Model validation<br/>[errors.py]"]
end

subgraph group_checking["Replay checking"]
  node_cpp_main["Checker CLI<br/>[main.cpp]"]
  node_cpp_checker["Replay checker<br/>[checker.cpp]"]
  node_cpp_header["Checker interfaces<br/>[checker.hpp]"]
end

node_rx(("Post-MAC stream"))
node_decision(("Decision event"))
node_rtl_log["RTL decision log"]
node_checker_result["Comparison result"]

node_rx -->|"accepts beats"| node_ingress_buffer
node_ingress_buffer -->|"streams beats"| node_gearbox
node_gearbox -->|"serializes bytes"| node_ethernet
node_ethernet -->|"passes payload"| node_ipv4
node_ipv4 -->|"passes datagram"| node_udp
node_udp -->|"passes payload"| node_mold_header
node_mold_header -->|"frames messages"| node_mold_framer
node_mold_framer -->|"passes messages"| node_itch
node_itch -->|"emits mutations"| node_order_book
node_order_book -->|"provides totals"| node_decision_engine
node_decision_engine -->|"emits event"| node_decision
node_async_fifo -.->|"streams across clocks"| node_functional_top
node_rx -.->|"optional beats"| node_async_fifo
node_model_oracle -->|"calls framing"| node_model_framing
node_model_oracle -->|"decodes messages"| node_model_itch
node_model_oracle -->|"owns state"| node_model_book
node_model_oracle -->|"owns decisions"| node_model_decision
node_model_framing -->|"parses Mold"| node_model_mold
node_model_framing -->|"checks header"| node_model_checksum
node_model_itch -->|"reads framed payload"| node_model_mold
node_model_book -->|"indexes orders"| node_model_hash
node_model_decision -->|"applies mutation"| node_model_book
node_cpp_main -.->|"runs checker"| node_cpp_checker
node_cpp_checker -->|"uses interfaces"| node_cpp_header
node_cpp_main -->|"uses interfaces"| node_cpp_header
node_cpp_checker -->|"compares decisions"| node_rtl_log
node_cpp_checker -->|"reports mismatches"| node_checker_result

click node_ingress_buffer "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_ingress_buffer.sv"
click node_gearbox "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_gearbox_64to8.sv"
click node_ethernet "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_eth_parser.sv"
click node_ipv4 "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_ipv4_parser.sv"
click node_udp "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_udp_parser.sv"
click node_mold_header "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_mold_header_seq.sv"
click node_mold_framer "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_mold_message_framer.sv"
click node_itch "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_itch_decoder.sv"
click node_order_book "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_order_book.sv"
click node_decision_engine "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_decision_engine.sv"
click node_async_fifo "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_async_fifo.sv"
click node_functional_top "https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_arch_a_functional_top.sv"
click node_model_framing "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/framing.py"
click node_model_mold "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/mold.py"
click node_model_itch "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/itch.py"
click node_model_book "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/book.py"
click node_model_hash "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/hash.py"
click node_model_decision "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/decision.py"
click node_model_checksum "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/checksum.py"
click node_model_oracle "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/oracle.py"
click node_model_types "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/types.py"
click node_model_constants "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/constants.py"
click node_model_errors "https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/errors.py"
click node_cpp_main "https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/main.cpp"
click node_cpp_checker "https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/checker.cpp"
click node_cpp_header "https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/checker.hpp"

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_ingress_buffer,node_gearbox,node_ethernet,node_ipv4,node_udp,node_mold_header,node_mold_framer,node_async_fifo toneBlue
class node_itch,node_order_book,node_decision_engine,node_functional_top toneAmber
class node_model_framing,node_model_mold,node_model_itch,node_model_book,node_model_hash,node_model_decision,node_model_checksum,node_model_oracle,node_model_types,node_model_constants,node_model_errors toneMint
class node_cpp_main,node_cpp_checker,node_cpp_header toneRose
class node_rx,node_decision,node_rtl_log,node_checker_result toneIndigo
```

## Components

### Ingress and framing

- [Ingress buffer](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_ingress_buffer.sv): `rtl/common/wire_ingress_buffer.sv`
- [64-to-8 gearbox](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_gearbox_64to8.sv): `rtl/arch_a/wire_gearbox_64to8.sv`
- [Ethernet parser](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_eth_parser.sv): `rtl/arch_a/wire_eth_parser.sv`
- [IPv4 parser](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_ipv4_parser.sv): `rtl/arch_a/wire_ipv4_parser.sv`
- [UDP parser](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_udp_parser.sv): `rtl/arch_a/wire_udp_parser.sv`
- [Mold header sequence](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_mold_header_seq.sv): `rtl/arch_a/wire_mold_header_seq.sv`
- [Mold message framer](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_mold_message_framer.sv): `rtl/arch_a/wire_mold_message_framer.sv`
- [Optional CDC FIFO](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_async_fifo.sv): `rtl/common/wire_async_fifo.sv`

### Mutation and decision

- [ITCH decoder](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_itch_decoder.sv): `rtl/arch_a/wire_itch_decoder.sv`
- [Order store](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_order_book.sv): `rtl/common/wire_order_book.sv`
- [Decision engine](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/common/wire_decision_engine.sv): `rtl/common/wire_decision_engine.sv`
- [Architecture A top](https://github.com/dilanj123/wire-to-decision/blob/main/rtl/arch_a/wire_arch_a_functional_top.sv): `rtl/arch_a/wire_arch_a_functional_top.sv`

### Python reference model

- [Packet framing model](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/framing.py): `model/python/wire_to_decision/framing.py`
- [Mold parser model](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/mold.py): `model/python/wire_to_decision/mold.py`
- [ITCH decoder model](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/itch.py): `model/python/wire_to_decision/itch.py`
- [Order book model](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/book.py): `model/python/wire_to_decision/book.py`
- [Order-set hash](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/hash.py): `model/python/wire_to_decision/hash.py`
- [Decision model](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/decision.py): `model/python/wire_to_decision/decision.py`
- [IPv4 checksum](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/checksum.py): `model/python/wire_to_decision/checksum.py`
- [Reference oracle](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/oracle.py): `model/python/wire_to_decision/oracle.py`
- [Canonical types](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/types.py): `model/python/wire_to_decision/types.py`
- [Model constants](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/constants.py): `model/python/wire_to_decision/constants.py`
- [Model validation](https://github.com/dilanj123/wire-to-decision/blob/main/model/python/wire_to_decision/errors.py): `model/python/wire_to_decision/errors.py`

### Replay checking

- [Checker CLI](https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/main.cpp): `tools/cpp/main.cpp`
- [Replay checker](https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/checker.cpp): `tools/cpp/checker.cpp`
- [Checker interfaces](https://github.com/dilanj123/wire-to-decision/blob/main/tools/cpp/checker.hpp): `tools/cpp/checker.hpp`

### Other components

- **Post-MAC stream**
- **Decision event**
- **RTL decision log**
- **Comparison result**

## Connections

- Post-MAC stream → Ingress buffer: accepts beats (evidence: `README.md`)
- Ingress buffer → 64-to-8 gearbox: streams beats (evidence: `README.md`)
- 64-to-8 gearbox → Ethernet parser: serializes bytes (evidence: `README.md`)
- Ethernet parser → IPv4 parser: passes payload (evidence: `README.md`)
- IPv4 parser → UDP parser: passes datagram (evidence: `README.md`)
- UDP parser → Mold header sequence: passes payload (evidence: `README.md`)
- Mold header sequence → Mold message framer: frames messages (evidence: `README.md`)
- Mold message framer → ITCH decoder: passes messages (evidence: `README.md`)
- ITCH decoder → Order store: emits mutations (evidence: `README.md`)
- Order store → Decision engine: provides totals (evidence: `README.md`)
- Decision engine → Decision event: emits event (evidence: `README.md`)
- Optional CDC FIFO → Architecture A top: streams across clocks (evidence: `README.md`)
- Post-MAC stream → Optional CDC FIFO: optional beats (evidence: `README.md`)
- Reference oracle → Packet framing model: calls framing (evidence: `model/python/wire_to_decision/oracle.py`)
- Reference oracle → ITCH decoder model: decodes messages (evidence: `model/python/wire_to_decision/oracle.py`)
- Reference oracle → Order book model: owns state (evidence: `model/python/wire_to_decision/oracle.py`)
- Reference oracle → Decision model: owns decisions (evidence: `model/python/wire_to_decision/oracle.py`)
- Packet framing model → Mold parser model: parses Mold (evidence: `model/python/wire_to_decision/framing.py`)
- Packet framing model → IPv4 checksum: checks header (evidence: `model/python/wire_to_decision/framing.py`)
- ITCH decoder model → Mold parser model: reads framed payload (evidence: `model/python/wire_to_decision/itch.py`)
- Order book model → Order-set hash: indexes orders (evidence: `model/python/wire_to_decision/book.py`)
- Decision model → Order book model: applies mutation (evidence: `model/python/wire_to_decision/decision.py`)
- Checker CLI → Replay checker: runs checker
- Replay checker → Checker interfaces: uses interfaces (evidence: `tools/cpp/checker.cpp`)
- Checker CLI → Checker interfaces: uses interfaces (evidence: `tools/cpp/main.cpp`)
- Replay checker → RTL decision log: compares decisions (evidence: `README.md`)
- Replay checker → Comparison result: reports mismatches (evidence: `README.md`)