CryptoTrading/docs/ARCHITECTURE.md

TradeFinder Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              TradeFinder                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌───────────┐ │
│  │  Streamlit  │     │   Engine    │     │  Optimizer  │     │ Backtester│ │
│  │     UI      │◄───►│   (Core)    │◄───►│  (Optuna)   │     │           │ │
│  └─────────────┘     └──────┬──────┘     └─────────────┘     └───────────┘ │
│                             │                                               │
│         ┌───────────────────┼───────────────────┐                          │
│         │                   │                   │                          │
│         ▼                   ▼                   ▼                          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                   │
│  │   Regime    │     │    Risk     │     │   Order     │                   │
│  │ Classifier  │     │   Engine    │     │  Manager    │                   │
│  └─────────────┘     └─────────────┘     └──────┬──────┘                   │
│         │                   │                   │                          │
│         ▼                   ▼                   ▼                          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                   │
│  │ Strategies  │     │  Allocator  │     │  Exchange   │                   │
│  │   Suite     │     │             │     │  Adapter    │                   │
│  └─────────────┘     └─────────────┘     └──────┬──────┘                   │
│                                                  │                          │
├──────────────────────────────────────────────────┼──────────────────────────┤
│  Data Layer                                      │                          │
│  ┌─────────────┐     ┌─────────────┐            │                          │
│  │   DuckDB    │     │    Redis    │            │                          │
│  │ (Analytics) │     │   (State)   │            │                          │
│  └─────────────┘     └─────────────┘            │                          │
└──────────────────────────────────────────────────┼──────────────────────────┘
                                                   │
                                                   ▼
                                          ┌───────────────┐
                                          │   Binance     │
                                          │ Futures API   │
                                          │  (Testnet)    │
                                          └───────────────┘

---

Component Details

1. Core Engine (src/tradefinder/core/)

The main orchestrator that coordinates all components.

core/
├── __init__.py
├── config.py        # Pydantic settings
├── main.py          # Entry point, event loop
├── engine.py        # Trading engine orchestrator
├── backtest.py      # Backtesting entry point
└── optimize.py      # Optimization entry point

Responsibilities:

• Load configuration from environment
• Initialize all components
• Run main trading loop (signal → risk → order)
• Handle graceful shutdown

2. Exchange Adapters (src/tradefinder/adapters/)

Abstract interface for exchange connectivity with Binance implementation.

adapters/
├── __init__.py
├── base.py          # Abstract ExchangeAdapter interface
├── binance_usdm.py  # Binance USDⓈ-M Futures implementation
└── types.py         # Shared types (Order, Position, etc.)

Key Features:

• Hedge mode support (dual position side)
• Isolated margin per symbol
• Order types: limit, stop-market, market
• WebSocket streams for real-time data

Binance USDⓈ-M Specifics:

# Required API calls on initialization
POST /fapi/v1/positionSide/dual  # Enable hedge mode
POST /fapi/v1/marginType         # Set ISOLATED margin
POST /fapi/v1/leverage           # Set leverage per symbol

3. Data Layer (src/tradefinder/data/)

Market data ingestion, storage, and retrieval.

data/
├── __init__.py
├── fetcher.py       # REST historical data fetcher
├── streamer.py      # WebSocket real-time streams
├── storage.py       # DuckDB operations
└── schemas.py       # Database schemas

Data Sources:

Data Type	Source	Frequency
OHLCV	REST (backfill) + WS (live)	1m, 5m, 4h
Mark Price	WebSocket	Real-time
Funding Rate	REST + WS	8h intervals
Order Book	WebSocket (optional)	Real-time

Storage Schema (DuckDB):

CREATE TABLE candles (
    symbol VARCHAR,
    timeframe VARCHAR,
    timestamp TIMESTAMP,
    open DOUBLE,
    high DOUBLE,
    low DOUBLE,
    close DOUBLE,
    volume DOUBLE,
    PRIMARY KEY (symbol, timeframe, timestamp)
);

CREATE TABLE trades (
    id VARCHAR PRIMARY KEY,
    symbol VARCHAR,
    side VARCHAR,
    entry_price DOUBLE,
    exit_price DOUBLE,
    quantity DOUBLE,
    pnl_usdt DOUBLE,
    pnl_pct DOUBLE,
    strategy VARCHAR,
    entry_time TIMESTAMP,
    exit_time TIMESTAMP
);

4. Strategies (src/tradefinder/strategies/)

Trading strategy implementations with common interface.

strategies/
├── __init__.py
├── base.py          # Abstract Strategy interface
├── supertrend.py    # Trend-following
├── squeeze.py       # Volatility breakout
├── mean_reversion.py # Range-bound
└── signals.py       # Signal types

Strategy Interface:

class Strategy(ABC):
    @abstractmethod
    def generate_signal(self, data: pd.DataFrame) -> Signal | None:
        """Analyze data and return entry/exit signal."""
        pass
    
    @abstractmethod
    def get_stop_loss(self, entry_price: float, side: Side) -> float:
        """Calculate stop-loss price for risk sizing."""
        pass
    
    @property
    @abstractmethod
    def parameters(self) -> dict[str, Any]:
        """Current strategy parameters (for UI display)."""
        pass

Regime-Strategy Mapping:

Regime	Primary Strategy	Secondary
Trending	Supertrend	-
Ranging	Mean Reversion	-
High Volatility	Squeeze Breakout	-
Uncertain	Reduce exposure	-

5. Risk Engine (src/tradefinder/core/risk.py)

Position sizing and risk management.

Position Sizing Formula:

Position Size = (Account Equity × Risk %) / |Entry Price - Stop Loss|

Example:
- Equity: $3000
- Risk: 2% = $60
- Entry: $100,000 (BTC)
- Stop: $98,000
- Stop Distance: $2,000

Position = $60 / $2,000 = 0.03 BTC
Notional = 0.03 × $100,000 = $3,000

Risk Limits:

Parameter	Value
Risk per trade	1-3%
Max per strategy	25% equity
Max total exposure	100% equity
Max leverage	2x (initial)

6. Allocator (src/tradefinder/core/allocator.py)

Multi-strategy capital allocation.

Allocation Rules:

1. Each strategy gets max 25% of equity
2. Hedge mode allows simultaneous long/short
3. Reduce allocation during uncertain regimes
4. Track "portfolio heat" (total risk exposure)

7. Order Manager (src/tradefinder/core/orders.py)

Order lifecycle management.

Order Flow:

Signal → Risk Check → Size Calculation → Order Submission
                                              │
                    ┌─────────────────────────┼─────────────────────────┐
                    │                         │                         │
                    ▼                         ▼                         ▼
              [PENDING]                  [FILLED]                 [REJECTED]
                    │                         │
                    ▼                         ▼
              [CANCELLED]              [STOP PLACED]
                                             │
                                             ▼
                                    [STOP TRIGGERED]

Order Types:

Purpose	Order Type	Rationale
Entry	Limit	Better fills, avoid slippage
Stop-Loss	Stop-Market	Guaranteed execution
Take-Profit	Limit	Optional, better exit price

8. Regime Classifier (src/tradefinder/core/regime.py)

Market regime detection.

Indicators Used:

Indicator	Purpose	Threshold
ADX	Trend strength	>25 = trending
ATR%	Volatility	Relative to historical
BB Width	Squeeze detection	Narrow = breakout pending

Regime States:

class Regime(Enum):
    TRENDING_UP = "trending_up"
    TRENDING_DOWN = "trending_down"
    RANGING = "ranging"
    HIGH_VOLATILITY = "high_volatility"
    UNCERTAIN = "uncertain"

9. UI Layer (src/tradefinder/ui/)

Streamlit dashboard for monitoring.

ui/
├── __init__.py
├── app.py           # Main Streamlit app
├── pages/
│   ├── dashboard.py
│   ├── trades.py
│   ├── strategies.py
│   └── optimizer.py
└── components/
    ├── charts.py
    └── tables.py

Dashboard Sections:

1. Overview: Equity, PnL (USDT/CHF/EUR), positions
2. Regime: Current market state, indicator values
3. Strategies: Active strategies, parameters, allocation
4. Trades: Recent trades, performance metrics
5. Optimizer: Last run results, parameter history

---

Data Flow

Trading Loop (Every Signal Interval)

1. Fetch latest candles (4h)
2. Update regime classification
3. Select active strategy based on regime
4. Generate signal from strategy
5. If signal:
   a. Calculate position size (risk engine)
   b. Check allocation limits
   c. Submit order (limit entry + stop-market)
6. Log state to DuckDB
7. Update Redis with current positions

Order Execution (1m/5m Monitoring)

1. Monitor open orders
2. If limit not filled within timeout:
   a. Cancel and retry at new price, OR
   b. Abandon if price moved too far
3. Track fills and update position
4. Ensure stop-loss is active

---

Deployment Architecture

# docker-compose services
services:
  engine:     # Main trading loop
  ui:         # Streamlit dashboard
  redis:      # Real-time state
  optimizer:  # Weekly Optuna runs
  backtester: # On-demand backtesting

Volume Mounts:

/opt/trading/crypto/
├── engine/     # Engine logs, state
├── optimizer/  # Optimization results
├── redis/      # Redis persistence
└── shared/     # DuckDB, shared data

---

Error Handling

Error Type	Response
Exchange API error	Retry with backoff, log, alert if persistent
Order rejected	Log reason, notify, do not retry blindly
WebSocket disconnect	Auto-reconnect with backoff
Invalid signal	Log and skip, continue loop
Risk limit exceeded	Block order, log warning

---

Security Considerations

See SECURITY.md for detailed security guidelines.

Key Points:

• API keys in environment variables only
• No withdrawal permissions on API keys
• Testnet keys separate from production
• Secrets never logged