# astomelio/binance architecture

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

- Interactive diagram: https://gitdiagram.com/astomelio/binance
- Repository: https://github.com/astomelio/binance

## Overview

This repository combines a Binance-facing API, a market-data lake and feature pipeline, ML strategy exploration and allocation, and a reusable trading library, plus automation and bot integrations. The principal research workflow is collect and transform market data, load decision features, train or infer allocations, then evaluate them with backtests. The graph includes documented capabilities whose source was not excerpted; their internal links are omitted where the evidence does not establish them. Paths and connections reflect the tree, README, and supplied source index/excerpts.

Main entry points: [`apps/api/main.py`](https://github.com/astomelio/binance/blob/main/apps/api/main.py) (REST and WebSocket API), [`ai/data/loader.py`](https://github.com/astomelio/binance/blob/main/ai/data/loader.py) (Feature loader), [`ai/training/pipeline.py`](https://github.com/astomelio/binance/blob/main/ai/training/pipeline.py) (Model training), [`ai/explorer/agent.py`](https://github.com/astomelio/binance/blob/main/ai/explorer/agent.py) (Strategy explorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Binance API"]
  node_api_service["REST and WebSocket API<br/>[main.py]"]
end

subgraph group_data["Market Data"]
  node_collectors["Market collectors<br/>[collectors.py]"]
  node_pipeline["Lake pipeline<br/>[pipeline.py]"]
  node_lake[("Bronze and silver lake<br/>[lake_writer.py]")]
  node_duckdb_loader["DuckDB loader"]
  node_transforms["Silver and gold transforms<br/>[gold.py]"]
  node_warehouse[("Feature warehouse")]
end

subgraph group_ai["AI Strategies"]
  node_feature_reader["Feature loader<br/>[loader.py]"]
  node_training["Model training<br/>[pipeline.py]"]
  node_predictor["Allocation inference<br/>[predictor.py]"]
  node_allocation_backtest["Allocation backtest<br/>[backtest.py]"]
  node_explorer["Strategy explorer<br/>[agent.py]"]
  node_explorer_registry["Strategy registry<br/>[registry.py]"]
  node_ai_registry[("Run registry<br/>[registry.py]")]
end

subgraph group_trading["Trading Library"]
  node_planner["Planner engine<br/>[engine.py]"]
  node_planner_alloc["Constrained allocation<br/>[allocation.py]"]
  node_calibration["Quant calibration<br/>[calibration.py]"]
end

subgraph group_automation["Automation"]
  node_market_alerts["Market alerts"]
  node_fee_calculator["Fee calculator<br/>[fee_calculator.py]"]
  node_bot_integrator["Bot rebalance integration<br/>[bot_integrator.py]"]
  node_trading_signals["Trading signals<br/>[trading_signals.py]"]
end

node_user(("API client"))
node_binance["Binance"]

node_user -->|"requests"| node_api_service
node_api_service -->|"calls"| node_binance
node_pipeline -->|"runs collection"| node_collectors
node_pipeline -->|"writes events"| node_lake
node_collectors -->|"fetches market data"| node_binance
node_lake -->|"loads bronze data"| node_duckdb_loader
node_duckdb_loader -->|"writes tables"| node_warehouse
node_transforms -->|"builds features"| node_warehouse
node_feature_reader -->|"reads features"| node_warehouse
node_training -->|"loads rows"| node_feature_reader
node_predictor -->|"loads latest features"| node_feature_reader
node_training -->|"uses calibration"| node_calibration
node_predictor -->|"uses calibration"| node_calibration
node_training -.->|"records runs"| node_ai_registry
node_explorer -->|"loads data"| node_feature_reader
node_explorer -->|"selects strategies"| node_explorer_registry
node_explorer -->|"evaluates experiments"| node_allocation_backtest
node_allocation_backtest -.->|"records results"| node_ai_registry
node_planner -->|"computes allocations"| node_planner_alloc
node_market_alerts -->|"requests market data"| node_api_service
node_market_alerts -->|"checks fees"| node_fee_calculator
node_bot_integrator -.->|"integrates rebalance"| node_api_service
node_trading_signals -.->|"signal integration"| node_api_service

click node_api_service "https://github.com/astomelio/binance/blob/main/apps/api/main.py"
click node_collectors "https://github.com/astomelio/binance/blob/main/data_platform/ingestion/collectors.py"
click node_pipeline "https://github.com/astomelio/binance/blob/main/data_platform/pipeline.py"
click node_lake "https://github.com/astomelio/binance/blob/main/data_platform/storage/lake_writer.py"
click node_duckdb_loader "https://github.com/astomelio/binance/blob/main/data_platform/loaders/bronze_to_duckdb.py"
click node_transforms "https://github.com/astomelio/binance/blob/main/data_platform/transforms/gold.py"
click node_warehouse "https://github.com/astomelio/binance/blob/main/data_platform/loaders/bronze_to_duckdb.py"
click node_feature_reader "https://github.com/astomelio/binance/blob/main/ai/data/loader.py"
click node_training "https://github.com/astomelio/binance/blob/main/ai/training/pipeline.py"
click node_predictor "https://github.com/astomelio/binance/blob/main/ai/inference/predictor.py"
click node_allocation_backtest "https://github.com/astomelio/binance/blob/main/ai/allocation/backtest.py"
click node_explorer "https://github.com/astomelio/binance/blob/main/ai/explorer/agent.py"
click node_explorer_registry "https://github.com/astomelio/binance/blob/main/ai/explorer/registry.py"
click node_ai_registry "https://github.com/astomelio/binance/blob/main/ai/registry.py"
click node_planner "https://github.com/astomelio/binance/blob/main/trading_lib/planner/engine.py"
click node_planner_alloc "https://github.com/astomelio/binance/blob/main/trading_lib/planner/allocation.py"
click node_calibration "https://github.com/astomelio/binance/blob/main/trading_lib/quant/calibration.py"
click node_market_alerts "https://github.com/astomelio/binance/blob/main/apps/automation/market_alert_engine.py"
click node_fee_calculator "https://github.com/astomelio/binance/blob/main/apps/automation/fee_calculator.py"
click node_bot_integrator "https://github.com/astomelio/binance/blob/main/apps/integrations/bot_integrator.py"
click node_trading_signals "https://github.com/astomelio/binance/blob/main/apps/integrations/trading_signals.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_api_service,node_user toneBlue
class node_collectors,node_pipeline,node_lake,node_duckdb_loader,node_transforms,node_warehouse toneAmber
class node_feature_reader,node_training,node_predictor,node_allocation_backtest,node_explorer,node_explorer_registry,node_ai_registry toneMint
class node_planner,node_planner_alloc,node_calibration toneRose
class node_market_alerts,node_fee_calculator,node_bot_integrator,node_trading_signals,node_binance toneIndigo
```

## Components

### Binance API

- [REST and WebSocket API](https://github.com/astomelio/binance/blob/main/apps/api/main.py): `apps/api/main.py`

### Market Data

- [Market collectors](https://github.com/astomelio/binance/blob/main/data_platform/ingestion/collectors.py): `data_platform/ingestion/collectors.py`
- [Lake pipeline](https://github.com/astomelio/binance/blob/main/data_platform/pipeline.py): `data_platform/pipeline.py`
- [Bronze and silver lake](https://github.com/astomelio/binance/blob/main/data_platform/storage/lake_writer.py): `data_platform/storage/lake_writer.py`
- [DuckDB loader](https://github.com/astomelio/binance/blob/main/data_platform/loaders/bronze_to_duckdb.py): `data_platform/loaders/bronze_to_duckdb.py`
- [Silver and gold transforms](https://github.com/astomelio/binance/blob/main/data_platform/transforms/gold.py): `data_platform/transforms/gold.py`
- [Feature warehouse](https://github.com/astomelio/binance/blob/main/data_platform/loaders/bronze_to_duckdb.py): `data_platform/loaders/bronze_to_duckdb.py`

### AI Strategies

- [Feature loader](https://github.com/astomelio/binance/blob/main/ai/data/loader.py): `ai/data/loader.py`
- [Model training](https://github.com/astomelio/binance/blob/main/ai/training/pipeline.py): `ai/training/pipeline.py`
- [Allocation inference](https://github.com/astomelio/binance/blob/main/ai/inference/predictor.py): `ai/inference/predictor.py`
- [Allocation backtest](https://github.com/astomelio/binance/blob/main/ai/allocation/backtest.py): `ai/allocation/backtest.py`
- [Strategy explorer](https://github.com/astomelio/binance/blob/main/ai/explorer/agent.py): `ai/explorer/agent.py`
- [Strategy registry](https://github.com/astomelio/binance/blob/main/ai/explorer/registry.py): `ai/explorer/registry.py`
- [Run registry](https://github.com/astomelio/binance/blob/main/ai/registry.py): `ai/registry.py`

### Trading Library

- [Planner engine](https://github.com/astomelio/binance/blob/main/trading_lib/planner/engine.py): `trading_lib/planner/engine.py`
- [Constrained allocation](https://github.com/astomelio/binance/blob/main/trading_lib/planner/allocation.py): `trading_lib/planner/allocation.py`
- [Quant calibration](https://github.com/astomelio/binance/blob/main/trading_lib/quant/calibration.py): `trading_lib/quant/calibration.py`

### Automation

- [Market alerts](https://github.com/astomelio/binance/blob/main/apps/automation/market_alert_engine.py): `apps/automation/market_alert_engine.py`
- [Fee calculator](https://github.com/astomelio/binance/blob/main/apps/automation/fee_calculator.py): `apps/automation/fee_calculator.py`
- [Bot rebalance integration](https://github.com/astomelio/binance/blob/main/apps/integrations/bot_integrator.py): `apps/integrations/bot_integrator.py`
- [Trading signals](https://github.com/astomelio/binance/blob/main/apps/integrations/trading_signals.py): `apps/integrations/trading_signals.py`

### Other components

- **API client**
- **Binance**

## Connections

- API client → REST and WebSocket API: requests (evidence: `README.md`)
- REST and WebSocket API → Binance: calls (evidence: `apps/api/main.py`)
- Lake pipeline → Market collectors: runs collection (evidence: `data_platform/pipeline.py`)
- Lake pipeline → Bronze and silver lake: writes events (evidence: `data_platform/pipeline.py`)
- Market collectors → Binance: fetches market data (evidence: `data_platform/ingestion/collectors.py`)
- Bronze and silver lake → DuckDB loader: loads bronze data (evidence: `README.md`)
- DuckDB loader → Feature warehouse: writes tables (evidence: `README.md`)
- Silver and gold transforms → Feature warehouse: builds features (evidence: `README.md`)
- Feature loader → Feature warehouse: reads features (evidence: `ai/data/loader.py`)
- Model training → Feature loader: loads rows (evidence: `ai/training/pipeline.py`)
- Allocation inference → Feature loader: loads latest features (evidence: `ai/inference/predictor.py`)
- Model training → Quant calibration: uses calibration (evidence: `ai/training/pipeline.py`)
- Allocation inference → Quant calibration: uses calibration (evidence: `ai/inference/predictor.py`)
- Model training → Run registry: records runs (evidence: `ai/training/pipeline.py`)
- Strategy explorer → Feature loader: loads data (evidence: `ai/explorer/agent.py`)
- Strategy explorer → Strategy registry: selects strategies (evidence: `ai/explorer/agent.py`)
- Strategy explorer → Allocation backtest: evaluates experiments
- Allocation backtest → Run registry: records results
- Planner engine → Constrained allocation: computes allocations (evidence: `trading_lib/planner/engine.py`)
- Market alerts → REST and WebSocket API: requests market data (evidence: `apps/automation/market_alert_engine.py`)
- Market alerts → Fee calculator: checks fees (evidence: `apps/automation/market_alert_engine.py`)
- Bot rebalance integration → REST and WebSocket API: integrates rebalance
- Trading signals → REST and WebSocket API: signal integration
