# derickwilliams5457-droid/liq_trading_system architecture

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

- Interactive diagram: https://gitdiagram.com/derickwilliams5457-droid/liq_trading_system
- Repository: https://github.com/derickwilliams5457-droid/liq_trading_system

## Overview

This repository implements a liquidation-triggered futures trading bot with an optional Bybit mirror and a read-only performance dashboard. Its main workflow records Binance liquidation events, detects activity after a quiet streak, evaluates a market signal, then dispatches trade execution. Trade monitors persist performance and account state for the dashboard. The excerpts support these major stages and integrations; some internals and dashboard data sources are only partly shown, so uncertain wiring is omitted.

Main entry points: [`trader.py`](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/trader.py) (Binance execution), [`perfio.py`](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/perfio.py) (Persistence access), [`run_bot.py`](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/run_bot.py) (Signal orchestrator), [`bybit_mirror.py`](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/bybit_mirror.py) (Bybit execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_signals["Signal detection"]
  node_liq_stream["Liquidation stream<br/>[liq_stream.py]"]
  node_liq_csv[("Liquidation events")]
  node_bucket["Activity bucketing<br/>[liq_bucket.py]"]
  node_bucket_state[("Bucket state")]
  node_signal_log["Signal stream"]
end

subgraph group_trading["Decision and execution"]
  node_bot["Signal orchestrator<br/>[run_bot.py]"]
  node_strategy["Market strategy<br/>[strategy.py]"]
  node_trader["Binance execution<br/>[trader.py]"]
  node_bybit["Bybit execution<br/>[bybit_mirror.py]"]
end

subgraph group_reporting["State and reporting"]
  node_perfio["Persistence access<br/>[perfio.py]"]
  node_performance[("Performance history")]
  node_trade_log[("Trade activity log")]
  node_account_state[("Account and trade state")]
  node_dashboard["Read-only dashboard<br/>[dash.py]"]
end

subgraph group_controls["Shared controls"]
  node_rate_gate["Request rate gate<br/>[ratelimit.py]"]
end

node_binance_ws(("Binance stream"))
node_binance_api(("Binance Futures"))
node_bybit_api(("Bybit API"))
node_viewer(("Dashboard viewer"))

node_binance_ws -->|"streams orders"| node_liq_stream
node_liq_stream -->|"appends events"| node_liq_csv
node_liq_csv -->|"reads events"| node_bucket
node_bucket -->|"persists counters"| node_bucket_state
node_bucket -->|"emits signals"| node_signal_log
node_signal_log -->|"tails signals"| node_bot
node_bot -->|"requests evaluation"| node_strategy
node_strategy -->|"fetches candles"| node_binance_api
node_strategy -->|"serializes requests"| node_rate_gate
node_bot -->|"dispatches trades"| node_trader
node_trader -->|"places and monitors"| node_binance_api
node_trader -->|"serializes requests"| node_rate_gate
node_bot -.->|"mirrors trades"| node_bybit
node_bybit -.->|"places and monitors"| node_bybit_api
node_trader -->|"records results"| node_perfio
node_bybit -->|"records results"| node_perfio
node_trader -->|"updates positions"| node_account_state
node_bybit -->|"updates positions"| node_account_state
node_perfio -->|"appends rows"| node_performance
node_perfio -->|"appends events"| node_trade_log
node_perfio -->|"reads and writes"| node_account_state
node_dashboard -->|"reads history"| node_performance
node_dashboard -->|"reads activity"| node_trade_log
node_dashboard -->|"reads snapshots"| node_account_state
node_viewer -->|"views dashboard"| node_dashboard

click node_liq_stream "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/liq_stream.py"
click node_bucket "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/liq_bucket.py"
click node_bot "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/run_bot.py"
click node_strategy "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/strategy.py"
click node_trader "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/trader.py"
click node_bybit "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/bybit_mirror.py"
click node_rate_gate "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/ratelimit.py"
click node_perfio "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/perfio.py"
click node_dashboard "https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/dash.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_liq_stream,node_liq_csv,node_bucket,node_bucket_state,node_signal_log,node_viewer toneBlue
class node_bot,node_strategy,node_trader,node_bybit toneAmber
class node_perfio,node_performance,node_trade_log,node_account_state,node_dashboard,node_bybit_api toneMint
class node_rate_gate toneRose
class node_binance_ws,node_binance_api toneIndigo
```

## Components

### Signal detection

- [Liquidation stream](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/liq_stream.py): `liq_stream.py`
- **Liquidation events**
- [Activity bucketing](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/liq_bucket.py): `liq_bucket.py`
- **Bucket state**
- **Signal stream**

### Decision and execution

- [Signal orchestrator](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/run_bot.py): `run_bot.py`
- [Market strategy](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/strategy.py): `strategy.py`
- [Binance execution](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/trader.py): `trader.py`
- [Bybit execution](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/bybit_mirror.py): `bybit_mirror.py`

### State and reporting

- [Persistence access](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/perfio.py): `perfio.py`
- **Performance history**
- **Trade activity log**
- **Account and trade state**
- [Read-only dashboard](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/dash.py): `dash.py`

### Shared controls

- [Request rate gate](https://github.com/derickwilliams5457-droid/liq_trading_system/blob/main/ratelimit.py): `ratelimit.py`

### Other components

- **Binance stream**
- **Binance Futures**
- **Bybit API**
- **Dashboard viewer**

## Connections

- Binance stream → Liquidation stream: streams orders
- Liquidation stream → Liquidation events: appends events
- Liquidation events → Activity bucketing: reads events
- Activity bucketing → Bucket state: persists counters
- Activity bucketing → Signal stream: emits signals
- Signal stream → Signal orchestrator: tails signals
- Signal orchestrator → Market strategy: requests evaluation
- Market strategy → Binance Futures: fetches candles
- Market strategy → Request rate gate: serializes requests
- Signal orchestrator → Binance execution: dispatches trades
- Binance execution → Binance Futures: places and monitors
- Binance execution → Request rate gate: serializes requests
- Signal orchestrator → Bybit execution: mirrors trades
- Bybit execution → Bybit API: places and monitors
- Binance execution → Persistence access: records results
- Bybit execution → Persistence access: records results
- Binance execution → Account and trade state: updates positions
- Bybit execution → Account and trade state: updates positions
- Persistence access → Performance history: appends rows
- Persistence access → Trade activity log: appends events
- Persistence access → Account and trade state: reads and writes
- Read-only dashboard → Performance history: reads history
- Read-only dashboard → Trade activity log: reads activity
- Read-only dashboard → Account and trade state: reads snapshots
- Dashboard viewer → Read-only dashboard: views dashboard