# yanguangshaonian/order_book architecture

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

- Interactive diagram: https://gitdiagram.com/yanguangshaonian/order_book
- Repository: https://github.com/yanguangshaonian/order_book

## Overview

1. **Repository purpose**
   - This repo is a Python behavioral model for **SSE/SZSE order-book snapshot reconstruction**, aimed at validating algorithm behavior and estimating FPGA resource needs.
   - It is not packaged as a library; scripts are intended to be run from the repository root.

2. **Main execution path**
   - The top-level runner is **`run_test_behave.py`**.
   - It drives the reconstruction model against historical market data and is the main entry point for experiments and regression checks.

3. **Behavior model subsystem**
   - The core algorithm lives under **`behave/`**, especially **`behave/axob.py`**.
   - This is the “snapshot reconstruction” behavioral model described in the README: it maintains local order-book price levels, reconstructs snapshots from order/trade events, and compares reconstructed results with exchange snapshots.

4. **Event/message layer**
   - The **`tool/`** package contains the market-message and state abstractions used by the model:
     - **`axsbe_order.py`**: order-message handling
     - **`axsbe_exe.py`**: execution/trade-message handling
     - **`axsbe_status.py`**: market status / trading-state handling
     - **`axsbe_snap_stock.py`**: stock snapshot representation
     - **`axsbe_base.py`**: shared base types or common parsing/dispatch logic
   - These modules form the domain model for the reconstruction pipeline.

5. **Data ingestion boundary**
   - **`tool/msg_util.py`** is the main data-access utility mentioned in the README.
   - It reads the project’s historical Level-2 data files, such as the sample ZIP under **`data/20220426/AX_sbe_szse_300750.zip`**.
   - This is the boundary between raw exchange data and the internal event model.

6. **Processing / orchestration**
   - **`tool/pipeline.py`** likely coordinates ordered processing of incoming market messages into the reconstruction engine.
   - The pipeline boundary is important: it separates parsing/normalization from the stateful order-book update logic.

7. **State and buffering utilities**
   - **`tool/simpleStack.py`** suggests a lightweight stack structure used for temporary buffering or event correlation.
   - This fits the README’s note that orders may be cached until corresponding executions arrive, because the exchange sends trades immediately after orders.

8. **Behavioral model specifics**
   - The reconstruction approach is **price-level based**, not full order-queue based.
   - That means the model maintains price ladders and quantities, then updates them using orders plus subsequent execution messages to produce a new snapshot.
   - In architectural terms, the central state is a compact book representation rather than a per-order matching engine.

9. **Testing subsystem**
   - **`behave/test/test_axob.py`** is the focused unit/regression test for the behavioral model.
   - **`behave/test/__init__.py`** marks the test package, and **`run_test_behave.py`** likely acts as the orchestration script for broader test runs.

10. **Support code**
   - **`tool/test_util.py`** and **`behave/mu.py`** appear to be helper modules for tests or mock/unified utilities.
   - These are not core architecture pieces, but they support reproducibility and validation.

11. **Outputs and artifacts**
   - The README indicates logs are written under a **`log/`** directory at runtime, though that directory is not currently in the tree.
   - The repo’s runtime artifacts are therefore separate from source and historical input data.

12. **Key architectural boundary to diagram**
   - The clearest system boundary is:
     **historical SZSE L2 file(s) → message parsing/utilities → ordered event pipeline → snapshot reconstruction model → test/assertion/comparison output**.
   - That end-to-end flow is the main architecture of the repository.

Main entry points: [`behave/axob.py`](https://github.com/yanguangshaonian/order_book/blob/main/behave/axob.py) (AXOB), [`tool/pipeline.py`](https://github.com/yanguangshaonian/order_book/blob/main/tool/pipeline.py) (Pipeline), [`tool/axsbe_base.py`](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_base.py) (Base Types), [`behave/test/test_axob.py`](https://github.com/yanguangshaonian/order_book/blob/main/behave/test/test_axob.py) (Model Test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry & Data"]
  node_n_run["Test Runner<br/>script<br/>[run_test_behave.py]"]
  node_n_data[("L2 Archive<br/>sample data")]
end

subgraph group_grp_tool["Message Toolkit"]
  node_n_msgutil["Msg Util<br/>ingest<br/>[msg_util.py]"]
  node_n_pipeline["Pipeline<br/>orchestration<br/>[pipeline.py]"]
  node_n_base["Base Types<br/>domain core<br/>[axsbe_base.py]"]
  node_n_order["Order Msg<br/>market message<br/>[axsbe_order.py]"]
  node_n_exe["Trade Msg<br/>market message<br/>[axsbe_exe.py]"]
  node_n_status["Market Status<br/>market state<br/>[axsbe_status.py]"]
  node_n_snap["Snapshot<br/>book state"]
end

subgraph group_grp_behave["Behavior Model"]
  node_n_axob["AXOB<br/>reconstruction model<br/>[axob.py]"]
  node_n_btest["Model Test<br/>regression test<br/>[test_axob.py]"]
  node_n_binit["Test Package<br/>[__init__.py]"]
end

subgraph group_grp_support["Support"]
  node_n_stack{{"Stack<br/>buffer<br/>[simpleStack.py]"}}
  node_n_mu["MU Helpers<br/>[mu.py]"]
  node_n_tutil["Test Utils<br/>testing utility<br/>[test_util.py]"]
end

node_n_run -->|"loads"| node_n_msgutil
node_n_run -->|"drives"| node_n_pipeline
node_n_msgutil -->|"reads"| node_n_data
node_n_msgutil -->|"parses via"| node_n_base
node_n_base -->|"defines"| node_n_order
node_n_base -->|"defines"| node_n_exe
node_n_base -->|"defines"| node_n_status
node_n_base -->|"defines"| node_n_snap
node_n_pipeline -->|"routes"| node_n_order
node_n_pipeline -->|"routes"| node_n_exe
node_n_pipeline -->|"routes"| node_n_status
node_n_pipeline -->|"buffers"| node_n_stack
node_n_pipeline -->|"feeds"| node_n_axob
node_n_order -->|"updates"| node_n_axob
node_n_exe -->|"applies"| node_n_axob
node_n_status -->|"gates"| node_n_axob
node_n_snap -->|"compares"| node_n_axob
node_n_axob -->|"verified by"| node_n_btest
node_n_btest -->|"uses"| node_n_tutil
node_n_btest -->|"uses"| node_n_mu
node_n_axob -->|"shares"| node_n_mu
node_n_binit -->|"packages"| node_n_btest

click node_n_run "https://github.com/yanguangshaonian/order_book/blob/main/run_test_behave.py"
click node_n_data "https://github.com/yanguangshaonian/order_book/blob/main/data/20220426/AX_sbe_szse_300750.zip"
click node_n_msgutil "https://github.com/yanguangshaonian/order_book/blob/main/tool/msg_util.py"
click node_n_pipeline "https://github.com/yanguangshaonian/order_book/blob/main/tool/pipeline.py"
click node_n_base "https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_base.py"
click node_n_order "https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_order.py"
click node_n_exe "https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_exe.py"
click node_n_status "https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_status.py"
click node_n_snap "https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_snap_stock.py"
click node_n_stack "https://github.com/yanguangshaonian/order_book/blob/main/tool/simpleStack.py"
click node_n_mu "https://github.com/yanguangshaonian/order_book/blob/main/behave/mu.py"
click node_n_axob "https://github.com/yanguangshaonian/order_book/blob/main/behave/axob.py"
click node_n_btest "https://github.com/yanguangshaonian/order_book/blob/main/behave/test/test_axob.py"
click node_n_binit "https://github.com/yanguangshaonian/order_book/blob/main/behave/test/__init__.py"
click node_n_tutil "https://github.com/yanguangshaonian/order_book/blob/main/tool/test_util.py"

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_n_run,node_n_data toneBlue
class node_n_msgutil,node_n_pipeline,node_n_base,node_n_order,node_n_exe,node_n_status,node_n_snap toneAmber
class node_n_axob,node_n_btest,node_n_binit toneMint
class node_n_stack,node_n_mu,node_n_tutil toneRose
```

## Components

### Entry & Data

Script entry point and historical market data boundary.

- [Test Runner](https://github.com/yanguangshaonian/order_book/blob/main/run_test_behave.py): script · Top-level experiment and regression entry point. · `run_test_behave.py`
- [L2 Archive](https://github.com/yanguangshaonian/order_book/blob/main/data/20220426/AX_sbe_szse_300750.zip): sample data · Historical SZSE market data used by the model. · `data/20220426/AX_sbe_szse_300750.zip`

### Message Toolkit

Parsing, message types, and pipeline coordination.

- [Msg Util](https://github.com/yanguangshaonian/order_book/blob/main/tool/msg_util.py): ingest · Reads historical message files and adapts raw data for processing. · `tool/msg_util.py`
- [Pipeline](https://github.com/yanguangshaonian/order_book/blob/main/tool/pipeline.py): orchestration · Coordinates ordered processing of incoming market messages. · `tool/pipeline.py`
- [Base Types](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_base.py): domain core · Shared message and parsing foundations. · `tool/axsbe_base.py`
- [Order Msg](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_order.py): market message · Order-event handling and normalization. · `tool/axsbe_order.py`
- [Trade Msg](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_exe.py): market message · Execution/trade-event handling. · `tool/axsbe_exe.py`
- [Market Status](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_status.py): market state · Trading-state and session-status handling. · `tool/axsbe_status.py`
- [Snapshot](https://github.com/yanguangshaonian/order_book/blob/main/tool/axsbe_snap_stock.py): book state · Stock snapshot representation used as the exchange reference. · `tool/axsbe_snap_stock.py`

### Behavior Model

Snapshot reconstruction logic and its test surface.

- [AXOB](https://github.com/yanguangshaonian/order_book/blob/main/behave/axob.py): reconstruction model · Price-level snapshot reconstruction and comparison logic. · `behave/axob.py`
- [Model Test](https://github.com/yanguangshaonian/order_book/blob/main/behave/test/test_axob.py): regression test · Focused test coverage for the behavioral model. · `behave/test/test_axob.py`
- [Test Package](https://github.com/yanguangshaonian/order_book/blob/main/behave/test/__init__.py): test package · Marks the behavioral test package. · `behave/test/__init__.py`

### Support

Shared helpers used by the model and tests.

- [Stack](https://github.com/yanguangshaonian/order_book/blob/main/tool/simpleStack.py): buffer · Lightweight buffering or correlation structure for event sequencing. · `tool/simpleStack.py`
- [MU Helpers](https://github.com/yanguangshaonian/order_book/blob/main/behave/mu.py): utility · Shared helper routines used by model and tests. · `behave/mu.py`
- [Test Utils](https://github.com/yanguangshaonian/order_book/blob/main/tool/test_util.py): testing utility · Helper functions for reproducible checks. · `tool/test_util.py`

## Connections

- Test Runner → Msg Util: loads · Runner pulls historical data through message utilities.
- Test Runner → Pipeline: drives · Runner executes the ordered processing pipeline.
- Msg Util → L2 Archive: reads · Utility boundary from raw archive to parsed messages.
- Msg Util → Base Types: parses via · Raw exchange records are normalized through shared base types.
- Base Types → Order Msg: defines · Common foundations for order messages.
- Base Types → Trade Msg: defines · Common foundations for trade messages.
- Base Types → Market Status: defines · Common foundations for market-status messages.
- Base Types → Snapshot: defines · Common foundations for snapshot representation.
- Pipeline → Order Msg: routes · Pipeline dispatches order events.
- Pipeline → Trade Msg: routes · Pipeline dispatches execution events.
- Pipeline → Market Status: routes · Pipeline dispatches session-status events.
- Pipeline → Stack: buffers · Pipeline uses temporary buffering for sequencing or correlation.
- Pipeline → AXOB: feeds · Normalized event stream enters the reconstruction model.
- Order Msg → AXOB: updates · Order messages modify reconstructed book state.
- Trade Msg → AXOB: applies · Executions are used to reconcile quantities and snapshots.
- Market Status → AXOB: gates · Trading-state changes affect model processing.
- Snapshot → AXOB: compares · Exchange snapshots are used as the reference for validation.
- AXOB → Model Test: verified by · Regression tests exercise the reconstruction behavior.
- Model Test → Test Utils: uses · Tests rely on shared testing helpers.
- Model Test → MU Helpers: uses · Tests share utility routines with the model.
- AXOB → MU Helpers: shares · Model uses common helper utilities.
- Test Package → Model Test: packages · Test package groups the behavioral tests.
