# amritsinha06072022/lob-imbalance-predictor architecture

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

- Interactive diagram: https://gitdiagram.com/amritsinha06072022/lob-imbalance-predictor
- Repository: https://github.com/amritsinha06072022/lob-imbalance-predictor

## Overview

This repository is a scripted limit-order-book prediction workflow: collect public Binance depth snapshots, derive snapshot features and timestamp-based forward labels, train models with purged chronological validation, and produce evaluation figures. The main stages are documented in the README and the sampled source confirms their data handling and call relationships. The model-training and evaluation stages are separate entry points; evaluation reuses model-training utilities. The notebook is exploratory, so it is not mapped as a runtime stage.

Main entry points: [`src/evaluate.py`](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/evaluate.py) (Holdout visualizer), [`src/model_training.py`](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py) (Purged model training), [`src/data_fetcher.py`](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/data_fetcher.py) (Snapshot collector), [`src/features.py`](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/features.py) (Feature and label builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Market Data"]
  node_collector["Snapshot collector<br/>[data_fetcher.py]"]
  node_rawcsv[("Raw snapshots")]
end

subgraph group_engineering["Feature Engineering"]
  node_builder["Feature and label builder<br/>[features.py]"]
  node_featurecsv[("Feature table")]
end

subgraph group_modeling["Modeling"]
  node_trainer["Purged model training<br/>[model_training.py]"]
  node_models["Trained classifiers<br/>[model_training.py]"]
  node_training_utils["Split and load utilities<br/>[model_training.py]"]
end

subgraph group_assessment["Evaluation"]
  node_evaluator["Holdout visualizer<br/>[evaluate.py]"]
  node_figures["ROC and importance plots"]
end

node_user(("Pipeline operator"))
node_binance{{"Binance public API"}}

node_user -->|"starts collection"| node_collector
node_collector -->|"requests depth"| node_binance
node_collector -->|"writes snapshots"| node_rawcsv
node_user -->|"builds dataset"| node_builder
node_builder -->|"reads snapshots"| node_rawcsv
node_builder -->|"writes features and labels"| node_featurecsv
node_user -->|"trains models"| node_trainer
node_trainer -->|"loads table"| node_featurecsv
node_trainer -->|"uses split logic"| node_training_utils
node_trainer -->|"fits and scores"| node_models
node_user -->|"generates figures"| node_evaluator
node_evaluator -->|"loads table"| node_featurecsv
node_evaluator -->|"imports holdout helpers"| node_training_utils
node_evaluator -->|"fits classifiers"| node_models
node_evaluator -->|"writes plots"| node_figures

click node_collector "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/data_fetcher.py"
click node_builder "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/features.py"
click node_trainer "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py"
click node_models "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py"
click node_evaluator "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/evaluate.py"
click node_training_utils "https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.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_collector,node_rawcsv toneBlue
class node_builder,node_featurecsv toneAmber
class node_trainer,node_models,node_training_utils,node_binance toneMint
class node_evaluator,node_figures toneRose
class node_user toneIndigo
```

## Components

### Market Data

- [Snapshot collector](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/data_fetcher.py): `src/data_fetcher.py`
- **Raw snapshots**

### Feature Engineering

- [Feature and label builder](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/features.py): `src/features.py`
- **Feature table**

### Modeling

- [Purged model training](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py): `src/model_training.py`
- [Trained classifiers](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py): `src/model_training.py`
- [Split and load utilities](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/model_training.py): `src/model_training.py`

### Evaluation

- [Holdout visualizer](https://github.com/amritsinha06072022/lob-imbalance-predictor/blob/master/src/evaluate.py): `src/evaluate.py`
- **ROC and importance plots**

### Other components

- **Pipeline operator**
- **Binance public API**

## Connections

- Pipeline operator → Snapshot collector: starts collection (evidence: `README.md`)
- Snapshot collector → Binance public API: requests depth (evidence: `src/data_fetcher.py`)
- Snapshot collector → Raw snapshots: writes snapshots (evidence: `src/data_fetcher.py`)
- Pipeline operator → Feature and label builder: builds dataset (evidence: `README.md`)
- Feature and label builder → Raw snapshots: reads snapshots (evidence: `README.md`)
- Feature and label builder → Feature table: writes features and labels (evidence: `src/features.py`)
- Pipeline operator → Purged model training: trains models (evidence: `README.md`)
- Purged model training → Feature table: loads table (evidence: `README.md`)
- Purged model training → Split and load utilities: uses split logic (evidence: `src/model_training.py`)
- Purged model training → Trained classifiers: fits and scores (evidence: `src/model_training.py`)
- Pipeline operator → Holdout visualizer: generates figures (evidence: `README.md`)
- Holdout visualizer → Feature table: loads table (evidence: `README.md`)
- Holdout visualizer → Split and load utilities: imports holdout helpers (evidence: `src/evaluate.py`)
- Holdout visualizer → Trained classifiers: fits classifiers (evidence: `src/evaluate.py`)
- Holdout visualizer → ROC and importance plots: writes plots (evidence: `src/evaluate.py`)
