# palc88-stack/apex-trader architecture

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

- Interactive diagram: https://gitdiagram.com/palc88-stack/apex-trader
- Repository: https://github.com/palc88-stack/apex-trader
- Video tour (about a minute): https://gitdiagram.com/palc88-stack/apex-trader/video

## Overview

Basel is a cryptocurrency trading bot with a Supabase-backed web dashboard and a TradingView webhook relay. The main workflow is market data → signal evaluation → risk checks → exchange order/position handling → persisted trade state and notifications. The dashboard reads bot status and trades from Supabase; the worker validates incoming webhook signals before forwarding them. Several runtime modules are present in the tree but were not sampled, so their internal wiring is omitted where it cannot be established.

Main entry points: [`bot/main.py`](https://github.com/palc88-stack/apex-trader/blob/main/bot/main.py) (Bot orchestrator), [`bot/signals/signal_engine.py`](https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/signal_engine.py) (Signal engine), [`web/src/App.jsx`](https://github.com/palc88-stack/apex-trader/blob/main/web/src/App.jsx) (Web dashboard), [`bot/data/market_data.py`](https://github.com/palc88-stack/apex-trader/blob/main/bot/data/market_data.py) (Market data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Trading runtime"]
  node_bot["Bot orchestrator<br/>[main.py]"]
  node_market["Market data<br/>[market_data.py]"]
  node_exchange["Exchange adapter<br/>[exchange.py]"]
  node_positions["Position manager"]
end

subgraph group_analysis["Signals and risk"]
  node_signals["Signal engine<br/>[signal_engine.py]"]
  node_indicators["Indicators<br/>[indicators.py]"]
  node_filters["Signal filters<br/>[filters.py]"]
  node_explosion["Explosion strategy<br/>[explosion.py]"]
  node_scalping["Scalping strategy<br/>[scalping.py]"]
  node_risk["Risk manager<br/>[risk_manager.py]"]
  node_fees["Fee calculator<br/>[fee_calculator.py]"]
end

subgraph group_state["State and notifications"]
  node_state_manager["State manager<br/>[state_manager.py]"]
  node_schema["Trade schema<br/>[schema.sql]"]
  node_telegram["Telegram notifier"]
end

subgraph group_interfaces["User and webhooks"]
  node_dashboard["Web dashboard<br/>[App.jsx]"]
  node_web_entry["Web entry<br/>[main.jsx]"]
  node_worker["Webhook worker<br/>[worker.js]"]
end

node_operator(("Operator"))
node_tradingview(("TradingView"))
node_supabase[("Supabase")]

node_operator -->|"uses"| node_dashboard
node_web_entry -->|"renders"| node_dashboard
node_dashboard -->|"reads/authenticates"| node_supabase
node_dashboard -->|"subscribes"| node_supabase
node_tradingview -->|"posts signal"| node_worker
node_worker -->|"forwards webhook"| node_bot
node_bot -->|"requests candles"| node_market
node_market -->|"fetches market data"| node_exchange
node_bot -->|"evaluates market"| node_signals
node_signals -->|"calculates"| node_indicators
node_signals -->|"validates signal"| node_filters
node_signals -.->|"uses strategy"| node_explosion
node_signals -.->|"uses strategy"| node_scalping
node_bot -->|"checks limits"| node_risk
node_risk -->|"uses"| node_fees
node_bot -->|"places/closes orders"| node_exchange
node_bot -->|"updates positions"| node_positions
node_bot -->|"loads/saves trades"| node_state_manager
node_state_manager -->|"reads/writes"| node_supabase
node_schema -->|"defines tables"| node_supabase
node_bot -->|"sends notifications"| node_telegram

click node_bot "https://github.com/palc88-stack/apex-trader/blob/main/bot/main.py"
click node_market "https://github.com/palc88-stack/apex-trader/blob/main/bot/data/market_data.py"
click node_exchange "https://github.com/palc88-stack/apex-trader/blob/main/bot/core/exchange.py"
click node_positions "https://github.com/palc88-stack/apex-trader/blob/main/bot/core/position_manager.py"
click node_signals "https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/signal_engine.py"
click node_indicators "https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/indicators.py"
click node_filters "https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/filters.py"
click node_explosion "https://github.com/palc88-stack/apex-trader/blob/main/bot/strategies/explosion.py"
click node_scalping "https://github.com/palc88-stack/apex-trader/blob/main/bot/strategies/scalping.py"
click node_risk "https://github.com/palc88-stack/apex-trader/blob/main/bot/core/risk_manager.py"
click node_fees "https://github.com/palc88-stack/apex-trader/blob/main/bot/core/fee_calculator.py"
click node_state_manager "https://github.com/palc88-stack/apex-trader/blob/main/bot/data/state_manager.py"
click node_schema "https://github.com/palc88-stack/apex-trader/blob/main/database/schema.sql"
click node_telegram "https://github.com/palc88-stack/apex-trader/blob/main/bot/notifications/telegram_notifier.py"
click node_dashboard "https://github.com/palc88-stack/apex-trader/blob/main/web/src/App.jsx"
click node_web_entry "https://github.com/palc88-stack/apex-trader/blob/main/web/src/main.jsx"
click node_worker "https://github.com/palc88-stack/apex-trader/blob/main/src/worker.js"

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_bot,node_market,node_exchange,node_positions,node_tradingview toneBlue
class node_signals,node_indicators,node_filters,node_explosion,node_scalping,node_risk,node_fees,node_supabase toneAmber
class node_state_manager,node_schema,node_telegram toneMint
class node_dashboard,node_web_entry,node_worker toneRose
class node_operator toneIndigo
```

## Components

### Trading runtime

- [Bot orchestrator](https://github.com/palc88-stack/apex-trader/blob/main/bot/main.py): `bot/main.py`
- [Market data](https://github.com/palc88-stack/apex-trader/blob/main/bot/data/market_data.py): `bot/data/market_data.py`
- [Exchange adapter](https://github.com/palc88-stack/apex-trader/blob/main/bot/core/exchange.py): `bot/core/exchange.py`
- [Position manager](https://github.com/palc88-stack/apex-trader/blob/main/bot/core/position_manager.py): `bot/core/position_manager.py`

### Signals and risk

- [Signal engine](https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/signal_engine.py): `bot/signals/signal_engine.py`
- [Indicators](https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/indicators.py): `bot/signals/indicators.py`
- [Signal filters](https://github.com/palc88-stack/apex-trader/blob/main/bot/signals/filters.py): `bot/signals/filters.py`
- [Explosion strategy](https://github.com/palc88-stack/apex-trader/blob/main/bot/strategies/explosion.py): `bot/strategies/explosion.py`
- [Scalping strategy](https://github.com/palc88-stack/apex-trader/blob/main/bot/strategies/scalping.py): `bot/strategies/scalping.py`
- [Risk manager](https://github.com/palc88-stack/apex-trader/blob/main/bot/core/risk_manager.py): `bot/core/risk_manager.py`
- [Fee calculator](https://github.com/palc88-stack/apex-trader/blob/main/bot/core/fee_calculator.py): `bot/core/fee_calculator.py`

### State and notifications

- [State manager](https://github.com/palc88-stack/apex-trader/blob/main/bot/data/state_manager.py): `bot/data/state_manager.py`
- [Trade schema](https://github.com/palc88-stack/apex-trader/blob/main/database/schema.sql): `database/schema.sql`
- [Telegram notifier](https://github.com/palc88-stack/apex-trader/blob/main/bot/notifications/telegram_notifier.py): `bot/notifications/telegram_notifier.py`

### User and webhooks

- [Web dashboard](https://github.com/palc88-stack/apex-trader/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Web entry](https://github.com/palc88-stack/apex-trader/blob/main/web/src/main.jsx): `web/src/main.jsx`
- [Webhook worker](https://github.com/palc88-stack/apex-trader/blob/main/src/worker.js): `src/worker.js`

### Other components

- **Operator**
- **TradingView**
- **Supabase**

## Connections

- Operator → Web dashboard: uses
- Web entry → Web dashboard: renders
- Web dashboard → Supabase: reads/authenticates
- Web dashboard → Supabase: subscribes
- TradingView → Webhook worker: posts signal
- Webhook worker → Bot orchestrator: forwards webhook
- Bot orchestrator → Market data: requests candles
- Market data → Exchange adapter: fetches market data
- Bot orchestrator → Signal engine: evaluates market
- Signal engine → Indicators: calculates
- Signal engine → Signal filters: validates signal
- Signal engine → Explosion strategy: uses strategy
- Signal engine → Scalping strategy: uses strategy
- Bot orchestrator → Risk manager: checks limits
- Risk manager → Fee calculator: uses
- Bot orchestrator → Exchange adapter: places/closes orders
- Bot orchestrator → Position manager: updates positions
- Bot orchestrator → State manager: loads/saves trades
- State manager → Supabase: reads/writes
- Trade schema → Supabase: defines tables
- Bot orchestrator → Telegram notifier: sends notifications