# arockiadassdev/ai-crypto-trading-bot architecture

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

- Interactive diagram: https://gitdiagram.com/arockiadassdev/ai-crypto-trading-bot
- Repository: https://github.com/arockiadassdev/ai-crypto-trading-bot

## Overview

#### Purpose and entry points
This is a Python crypto-trading research and paper-trading system combining Binance market data, technical indicators, ML/DL predictions, strategy signals, risk controls, and historical backtests. FastAPI is the service boundary at `backend/app/main.py`; REST routes are in `backend/app/api/trading.py` and `backend/app/api/health.py`. The operator-facing dashboard starts at `streamlit_app/app.py`.

#### Runtime and deployment topology
The intended runtime is Python 3.13+, with FastAPI/Uvicorn for the API and a separate Streamlit process. Containers are defined by `Dockerfile`, `Dockerfile.streamlit`, and `docker-compose.yml`. Material external dependencies are PostgreSQL 16, Redis 7, Binance through CCXT and its WebSocket API, and MLflow. Docker database initialization is at `docker/postgres/init.sql`.

#### API orchestration boundary
Trading endpoints accept API schemas, invoke domain services, and return operational state such as prices, signals, portfolio data, model predictions, backtests, and paper orders. The route layer should remain the boundary between HTTP concerns and trading behavior:
- `backend/app/api/trading.py`
- `backend/app/schemas/trading.py`
- `backend/app/main.py`

Health, readiness, and liveness checks are isolated from trading operations in `backend/app/api/health.py` and `backend/app/schemas/health.py`.

#### Market-data and feature pipeline
Historical acquisition and live streaming feed the system’s market-data path. Binance integration is encapsulated rather than exposed directly to strategies; data is processed into indicator/feature-bearing datasets before signal or model use. Local persistence directories distinguish raw, processed, and feature datasets.
- `backend/app/services/exchange.py`
- `backend/app/websocket/client.py`
- `backend/app/services/data_pipeline.py`
- `backend/app/services/historical_data.py`
- `backend/app/indicators/compute.py`
- `data/raw`, `data/processed`, `data/features`

#### Strategy, risk, and paper execution flow
The primary decision flow is market data/features → strategy engine and signal generator → risk validation/sizing → simulated execution → portfolio/trade state. Risk is a hard control boundary before execution; paper trading is the available execution implementation, not evidence of live-order placement.
- `backend/app/strategy/engine.py`
- `backend/app/strategy/signal_generator.py`
- `backend/app/risk/manager.py`
- `backend/app/trading/paper_trading.py`
- `backend/app/portfolio/manager.py`

Domain records for orders, trades, signals, portfolios, and market data are modeled under `backend/app/models/order.py`, `backend/app/models/trade.py`, `backend/app/models/portfolio.py`, `backend/app/models/trading_signal.py`, and `backend/app/models/market_data.py`.

#### ML and model lifecycle
The ML subsystem supports tree-based and LSTM models, preprocessing, and a registry layer. Training/inference is exposed through the API orchestration path and consumes prepared market features; trained artifacts are stored separately from source. MLflow is the experiment/model-tracking integration.
- `backend/app/ml/xgboost_model.py`
- `backend/app/ml/lstm_model.py`
- `backend/app/ml/model_registry.py`
- `backend/app/utils/preprocessing.py`
- `models`, `mlflow`

#### Backtesting and persistence
Historical strategy evaluation is separated from live/paper decisioning in `backend/app/backtesting/engine.py`, producing persisted backtest results via `backend/app/models/backtest_result.py`. PostgreSQL access uses async SQLAlchemy session/base modules, with schema evolution managed by Alembic:
- `backend/app/database/session.py`
- `backend/app/database/base.py`
- `backend/alembic/versions/001_initial_schema.py`

Operational outputs and generated pipeline results belong in `artifacts`; configuration and structured logging are centralized at `backend/app/config/settings.py` and `backend/app/core/logging.py`.

Main entry points: [`backend/app/api/trading.py`](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/api/trading.py) (Trading routes & schemas), [`data/features`](https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/data/features) (Feature datasets), [`backend/app/backtesting/engine.py`](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/backtesting/engine.py) (Backtest engine), [`backend/app/main.py`](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/main.py) (FastAPI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Service Interfaces"]
  node_api["FastAPI service<br/>API application<br/>[main.py]"]
  node_trading_routes["Trading routes &amp; schemas<br/>REST boundary<br/>[trading.py]"]
  node_health_routes["Health routes<br/>health boundary<br/>[health.py]"]
  node_dashboard["Streamlit dashboard<br/>operator UI<br/>[app.py]"]
end

subgraph group_market["Market Data Pipeline"]
  node_binance(("Binance<br/>external exchange"))
  node_market_ingestion["Exchange &amp; historical ingestion<br/>market-data service<br/>[exchange.py]"]
  node_live_stream["WebSocket client<br/>live market stream<br/>[client.py]"]
  node_data_pipeline["Data pipeline<br/>dataset processing<br/>[data_pipeline.py]"]
  node_indicators["Indicator computation<br/>feature engineering<br/>[compute.py]"]
  node_feature_data[("Feature datasets<br/>local datasets")]
end

subgraph group_trading["Trading Decisioning"]
  node_strategy_engine["Strategy engine<br/>strategy orchestration<br/>[engine.py]"]
  node_signals["Signal generator<br/>signal logic"]
  node_risk{{"Risk manager<br/>risk control<br/>[manager.py]"}}
  node_paper_execution["Paper trading<br/>simulated execution<br/>[paper_trading.py]"]
  node_portfolio["Portfolio manager<br/>portfolio state<br/>[manager.py]"]
end

subgraph group_ml["ML &amp; Backtesting"]
  node_ml_models["XGBoost &amp; LSTM models<br/>prediction models<br/>[xgboost_model.py]"]
  node_model_registry["Model registry<br/>model lifecycle<br/>[model_registry.py]"]
  node_mlflow[("MLflow<br/>experiment tracking")]
  node_backtesting["Backtest engine<br/>historical evaluation<br/>[engine.py]"]
end

subgraph group_persistence["Persistence &amp; Operations"]
  node_postgres[("PostgreSQL<br/>operational database")]
  node_schema_migrations["Initial schema migration<br/>Alembic migration"]
  node_artifacts[("Artifacts<br/>generated outputs")]
end

node_api -->|"mounts"| node_trading_routes
node_api -->|"mounts"| node_health_routes
node_dashboard -->|"uses operational API"| node_api
node_trading_routes -->|"requests prices and data"| node_market_ingestion
node_trading_routes -->|"orchestrates signals"| node_strategy_engine
node_trading_routes -->|"requests predictions"| node_ml_models
node_trading_routes -->|"runs evaluations"| node_backtesting
node_trading_routes -->|"submits paper orders"| node_paper_execution
node_binance -->|"historical market data"| node_market_ingestion
node_binance -->|"live market stream"| node_live_stream
node_market_ingestion -->|"acquired data"| node_data_pipeline
node_live_stream -->|"live data"| node_data_pipeline
node_data_pipeline -->|"prepared datasets"| node_indicators
node_indicators -->|"writes features"| node_feature_data
node_feature_data -->|"market features"| node_strategy_engine
node_feature_data -->|"training and inference features"| node_ml_models
node_strategy_engine -->|"generates"| node_signals
node_signals -->|"proposed orders"| node_risk
node_risk -->|"approved and sized orders"| node_paper_execution
node_paper_execution -->|"fills and trade state"| node_portfolio
node_portfolio -->|"persists state"| node_postgres
node_backtesting -->|"persists results"| node_postgres
node_ml_models -->|"registers artifacts"| node_model_registry
node_model_registry -->|"tracks models and experiments"| node_mlflow
node_backtesting -->|"writes outputs"| node_artifacts
node_schema_migrations -->|"evolves schema"| node_postgres

click node_api "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/main.py"
click node_trading_routes "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/api/trading.py"
click node_health_routes "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/api/health.py"
click node_dashboard "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/streamlit_app/app.py"
click node_market_ingestion "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/services/exchange.py"
click node_live_stream "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/websocket/client.py"
click node_data_pipeline "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/services/data_pipeline.py"
click node_indicators "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/indicators/compute.py"
click node_feature_data "https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/data/features"
click node_strategy_engine "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/strategy/engine.py"
click node_signals "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/strategy/signal_generator.py"
click node_risk "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/risk/manager.py"
click node_paper_execution "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/trading/paper_trading.py"
click node_portfolio "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/portfolio/manager.py"
click node_ml_models "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/ml/xgboost_model.py"
click node_model_registry "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/ml/model_registry.py"
click node_mlflow "https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/mlflow"
click node_backtesting "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/backtesting/engine.py"
click node_schema_migrations "https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/alembic/versions/001_initial_schema.py"
click node_artifacts "https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/artifacts"

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,node_trading_routes,node_health_routes,node_dashboard toneBlue
class node_binance,node_market_ingestion,node_live_stream,node_data_pipeline,node_indicators,node_feature_data toneAmber
class node_strategy_engine,node_signals,node_risk,node_paper_execution,node_portfolio toneMint
class node_ml_models,node_model_registry,node_mlflow,node_backtesting toneRose
class node_postgres,node_schema_migrations,node_artifacts toneIndigo
```

## Components

### Service Interfaces

- [FastAPI service](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/main.py): API application · HTTP boundary for trading and health operations. · `backend/app/main.py`
- [Trading routes & schemas](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/api/trading.py): REST boundary · `backend/app/api/trading.py`
- [Health routes](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/api/health.py): health boundary · `backend/app/api/health.py`
- [Streamlit dashboard](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/streamlit_app/app.py): operator UI · `streamlit_app/app.py`

### Market Data Pipeline

- **Binance**: external exchange · Market-data source via CCXT and WebSocket APIs.
- [Exchange & historical ingestion](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/services/exchange.py): market-data service · `backend/app/services/exchange.py`
- [WebSocket client](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/websocket/client.py): live market stream · `backend/app/websocket/client.py`
- [Data pipeline](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/services/data_pipeline.py): dataset processing · `backend/app/services/data_pipeline.py`
- [Indicator computation](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/indicators/compute.py): feature engineering · `backend/app/indicators/compute.py`
- [Feature datasets](https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/data/features): local datasets · Raw, processed, and feature-bearing market datasets. · `data/features`

### Trading Decisioning

- [Strategy engine](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/strategy/engine.py): strategy orchestration · `backend/app/strategy/engine.py`
- [Signal generator](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/strategy/signal_generator.py): signal logic · `backend/app/strategy/signal_generator.py`
- [Risk manager](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/risk/manager.py): risk control · Hard validation and sizing gate before execution. · `backend/app/risk/manager.py`
- [Paper trading](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/trading/paper_trading.py): simulated execution · Available execution path; no live-order placement implied. · `backend/app/trading/paper_trading.py`
- [Portfolio manager](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/portfolio/manager.py): portfolio state · `backend/app/portfolio/manager.py`

### ML & Backtesting

- [XGBoost & LSTM models](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/ml/xgboost_model.py): prediction models · `backend/app/ml/xgboost_model.py`
- [Model registry](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/ml/model_registry.py): model lifecycle · `backend/app/ml/model_registry.py`
- [MLflow](https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/mlflow): experiment tracking · `mlflow`
- [Backtest engine](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/app/backtesting/engine.py): historical evaluation · `backend/app/backtesting/engine.py`

### Persistence & Operations

- **PostgreSQL**: operational database · Async SQLAlchemy-backed state and persisted results.
- [Initial schema migration](https://github.com/arockiadassdev/ai-crypto-trading-bot/blob/main/backend/alembic/versions/001_initial_schema.py): Alembic migration · `backend/alembic/versions/001_initial_schema.py`
- [Artifacts](https://github.com/arockiadassdev/ai-crypto-trading-bot/tree/main/artifacts): generated outputs · Operational outputs and generated pipeline results. · `artifacts`

## Connections

- FastAPI service → Trading routes & schemas: mounts
- FastAPI service → Health routes: mounts
- Streamlit dashboard → FastAPI service: uses operational API
- Trading routes & schemas → Exchange & historical ingestion: requests prices and data
- Trading routes & schemas → Strategy engine: orchestrates signals
- Trading routes & schemas → XGBoost & LSTM models: requests predictions
- Trading routes & schemas → Backtest engine: runs evaluations
- Trading routes & schemas → Paper trading: submits paper orders
- Binance → Exchange & historical ingestion: historical market data
- Binance → WebSocket client: live market stream
- Exchange & historical ingestion → Data pipeline: acquired data
- WebSocket client → Data pipeline: live data
- Data pipeline → Indicator computation: prepared datasets
- Indicator computation → Feature datasets: writes features
- Feature datasets → Strategy engine: market features
- Feature datasets → XGBoost & LSTM models: training and inference features
- Strategy engine → Signal generator: generates
- Signal generator → Risk manager: proposed orders
- Risk manager → Paper trading: approved and sized orders
- Paper trading → Portfolio manager: fills and trade state
- Portfolio manager → PostgreSQL: persists state
- Backtest engine → PostgreSQL: persists results
- XGBoost & LSTM models → Model registry: registers artifacts
- Model registry → MLflow: tracks models and experiments
- Backtest engine → Artifacts: writes outputs
- Initial schema migration → PostgreSQL: evolves schema