# leonardoberti00/tlob architecture

> Architecture diagram of the GitHub repository leonardoberti00/tlob, 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/leonardoberti00/tlob
- Repository: https://github.com/leonardoberti00/tlob

## Overview

TLOB is a research and training system for classifying price trends from limit-order-book sequences. The principal workflow configures a model and dataset, optionally prepares raw data, loads labeled sequence windows, trains and evaluates a selected model, then saves predictions and checkpoints. Separate preprocessing branches support BTC, FI-2010, and LOBSTER; the repository also includes several alternative model architectures and a backtesting entry point. Edges reflect shown imports, calls, or README statements; unsampled subsystem details are not inferred.

Main entry points: [`main.py`](https://github.com/leonardoberti00/tlob/blob/main/main.py) (Training entry), [`run.py`](https://github.com/leonardoberti00/tlob/blob/main/run.py) (Experiment runner), [`utils/utils_model.py`](https://github.com/leonardoberti00/tlob/blob/main/utils/utils_model.py) (Model selector), [`models/engine.py`](https://github.com/leonardoberti00/tlob/blob/main/models/engine.py) (Training engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Configuration and orchestration"]
  node_config["Experiment config<br/>[config.py]"]
  node_entry["Training entry<br/>[main.py]"]
  node_runner["Experiment runner<br/>[run.py]"]
end

subgraph group_data["Market data pipeline"]
  node_btc_builder["BTC preparation<br/>[btc.py]"]
  node_fi_data["FI-2010 preparation<br/>[fi_2010.py]"]
  node_lobster_builder["LOBSTER preparation<br/>[lobster.py]"]
  node_data_utils["Data transforms<br/>[utils_data.py]"]
  node_sequence_data["Sequence datasets<br/>[dataset.py]"]
end

subgraph group_models["Model architectures"]
  node_factory["Model selector<br/>[utils_model.py]"]
  node_tlob["TLOB<br/>[tlob.py]"]
  node_mlplob["MLPLOB<br/>[mlplob.py]"]
  node_deeplob["DeepLOB<br/>[deeplob.py]"]
  node_binctabl["BiN-CTABL<br/>[binctabl.py]"]
  node_bin["BiN normalization<br/>[bin.py]"]
  node_attention["Attention utilities<br/>[attention.py]"]
end

subgraph group_evaluation["Training and evaluation"]
  node_engine["Training engine<br/>[engine.py]"]
  node_checkpoint_store[("Saved checkpoints")]
  node_backtesting["Backtesting<br/>[run_backtesting.py]"]
end

node_researcher(("Researcher"))
node_wandb(("Weights &amp; Biases"))

node_researcher -->|"configures run"| node_entry
node_entry -->|"loads config"| node_config
node_entry -->|"starts run"| node_runner
node_entry -->|"prepares BTC"| node_btc_builder
node_entry -->|"prepares LOBSTER"| node_lobster_builder
node_entry -->|"extracts data"| node_fi_data
node_entry -->|"starts logging"| node_wandb
node_runner -->|"batches windows"| node_sequence_data
node_runner -->|"trains model"| node_engine
node_runner -->|"loads prepared data"| node_btc_builder
node_runner -->|"loads prepared data"| node_lobster_builder
node_runner -->|"loads prepared data"| node_fi_data
node_btc_builder -->|"transforms data"| node_data_utils
node_lobster_builder -->|"labels and normalizes"| node_data_utils
node_sequence_data -->|"encodes event types"| node_data_utils
node_engine -->|"selects architecture"| node_factory
node_factory -->|"instantiates"| node_tlob
node_factory -->|"instantiates"| node_mlplob
node_factory -->|"instantiates"| node_deeplob
node_factory -->|"instantiates"| node_binctabl
node_tlob -->|"normalizes with"| node_bin
node_tlob -->|"uses MLP layer"| node_mlplob
node_engine -->|"saves predictions"| node_checkpoint_store
node_researcher -.->|"runs backtest"| node_backtesting
node_engine -.->|"logs metrics"| node_wandb

click node_config "https://github.com/leonardoberti00/tlob/blob/main/config/config.py"
click node_entry "https://github.com/leonardoberti00/tlob/blob/main/main.py"
click node_runner "https://github.com/leonardoberti00/tlob/blob/main/run.py"
click node_btc_builder "https://github.com/leonardoberti00/tlob/blob/main/preprocessing/btc.py"
click node_fi_data "https://github.com/leonardoberti00/tlob/blob/main/preprocessing/fi_2010.py"
click node_lobster_builder "https://github.com/leonardoberti00/tlob/blob/main/preprocessing/lobster.py"
click node_data_utils "https://github.com/leonardoberti00/tlob/blob/main/utils/utils_data.py"
click node_sequence_data "https://github.com/leonardoberti00/tlob/blob/main/preprocessing/dataset.py"
click node_engine "https://github.com/leonardoberti00/tlob/blob/main/models/engine.py"
click node_factory "https://github.com/leonardoberti00/tlob/blob/main/utils/utils_model.py"
click node_tlob "https://github.com/leonardoberti00/tlob/blob/main/models/tlob.py"
click node_mlplob "https://github.com/leonardoberti00/tlob/blob/main/models/mlplob.py"
click node_deeplob "https://github.com/leonardoberti00/tlob/blob/main/models/deeplob.py"
click node_binctabl "https://github.com/leonardoberti00/tlob/blob/main/models/binctabl.py"
click node_bin "https://github.com/leonardoberti00/tlob/blob/main/models/bin.py"
click node_attention "https://github.com/leonardoberti00/tlob/blob/main/utils/attention.py"
click node_checkpoint_store "https://github.com/leonardoberti00/tlob/tree/main/data/checkpoints"
click node_backtesting "https://github.com/leonardoberti00/tlob/blob/main/run_backtesting.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_config,node_entry,node_runner toneBlue
class node_btc_builder,node_fi_data,node_lobster_builder,node_data_utils,node_sequence_data toneAmber
class node_factory,node_tlob,node_mlplob,node_deeplob,node_binctabl,node_bin,node_attention toneMint
class node_engine,node_checkpoint_store,node_backtesting toneRose
class node_researcher,node_wandb toneIndigo
```

## Components

### Configuration and orchestration

- [Experiment config](https://github.com/leonardoberti00/tlob/blob/main/config/config.py): `config/config.py`
- [Training entry](https://github.com/leonardoberti00/tlob/blob/main/main.py): `main.py`
- [Experiment runner](https://github.com/leonardoberti00/tlob/blob/main/run.py): `run.py`

### Market data pipeline

- [BTC preparation](https://github.com/leonardoberti00/tlob/blob/main/preprocessing/btc.py): `preprocessing/btc.py`
- [FI-2010 preparation](https://github.com/leonardoberti00/tlob/blob/main/preprocessing/fi_2010.py): `preprocessing/fi_2010.py`
- [LOBSTER preparation](https://github.com/leonardoberti00/tlob/blob/main/preprocessing/lobster.py): `preprocessing/lobster.py`
- [Data transforms](https://github.com/leonardoberti00/tlob/blob/main/utils/utils_data.py): `utils/utils_data.py`
- [Sequence datasets](https://github.com/leonardoberti00/tlob/blob/main/preprocessing/dataset.py): `preprocessing/dataset.py`

### Model architectures

- [Model selector](https://github.com/leonardoberti00/tlob/blob/main/utils/utils_model.py): `utils/utils_model.py`
- [TLOB](https://github.com/leonardoberti00/tlob/blob/main/models/tlob.py): `models/tlob.py`
- [MLPLOB](https://github.com/leonardoberti00/tlob/blob/main/models/mlplob.py): `models/mlplob.py`
- [DeepLOB](https://github.com/leonardoberti00/tlob/blob/main/models/deeplob.py): `models/deeplob.py`
- [BiN-CTABL](https://github.com/leonardoberti00/tlob/blob/main/models/binctabl.py): `models/binctabl.py`
- [BiN normalization](https://github.com/leonardoberti00/tlob/blob/main/models/bin.py): `models/bin.py`
- [Attention utilities](https://github.com/leonardoberti00/tlob/blob/main/utils/attention.py): `utils/attention.py`

### Training and evaluation

- [Training engine](https://github.com/leonardoberti00/tlob/blob/main/models/engine.py): `models/engine.py`
- [Saved checkpoints](https://github.com/leonardoberti00/tlob/tree/main/data/checkpoints): `data/checkpoints`
- [Backtesting](https://github.com/leonardoberti00/tlob/blob/main/run_backtesting.py): `run_backtesting.py`

### Other components

- **Researcher**
- **Weights & Biases**

## Connections

- Researcher → Training entry: configures run (evidence: `README.md`)
- Training entry → Experiment config: loads config (evidence: `main.py`)
- Training entry → Experiment runner: starts run (evidence: `main.py`)
- Training entry → BTC preparation: prepares BTC (evidence: `main.py`)
- Training entry → LOBSTER preparation: prepares LOBSTER (evidence: `main.py`)
- Training entry → FI-2010 preparation: extracts data (evidence: `main.py`)
- Training entry → Weights & Biases: starts logging (evidence: `main.py`)
- Experiment runner → Sequence datasets: batches windows (evidence: `run.py`)
- Experiment runner → Training engine: trains model (evidence: `run.py`)
- Experiment runner → BTC preparation: loads prepared data (evidence: `run.py`)
- Experiment runner → LOBSTER preparation: loads prepared data (evidence: `run.py`)
- Experiment runner → FI-2010 preparation: loads prepared data (evidence: `run.py`)
- BTC preparation → Data transforms: transforms data (evidence: `preprocessing/btc.py`)
- LOBSTER preparation → Data transforms: labels and normalizes (evidence: `preprocessing/lobster.py`)
- Sequence datasets → Data transforms: encodes event types (evidence: `preprocessing/dataset.py`)
- Training engine → Model selector: selects architecture (evidence: `models/engine.py`)
- Model selector → TLOB: instantiates (evidence: `utils/utils_model.py`)
- Model selector → MLPLOB: instantiates (evidence: `utils/utils_model.py`)
- Model selector → DeepLOB: instantiates (evidence: `utils/utils_model.py`)
- Model selector → BiN-CTABL: instantiates (evidence: `utils/utils_model.py`)
- TLOB → BiN normalization: normalizes with (evidence: `models/tlob.py`)
- TLOB → MLPLOB: uses MLP layer (evidence: `models/tlob.py`)
- Training engine → Saved checkpoints: saves predictions (evidence: `models/engine.py`)
- Researcher → Backtesting: runs backtest (evidence: `README.md`)
- Training engine → Weights & Biases: logs metrics (evidence: `README.md`)
