kfox/crypto_trader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Local changes: Updated model training, removed debug instrumentation, and configuration improvements

Browse Source
This commit is contained in:
kfox
2025-12-26 01:15:43 -05:00
commit cc60da49e7
388 changed files with 57127 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
docs/architecture/autopilot.md Normal file
View File

@@ -0,0 +1,378 @@
# Autopilot Architecture
This document describes the architecture of the Autopilot system, including both Pattern-Based and ML-Based modes.
## Overview
The Autopilot system provides autonomous trading signal generation using an **Intelligent Autopilot** powered by machine learning-based strategy selection.
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ Unified Autopilot API │
│ (/api/autopilot/start-unified) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ ML-Based │ │ Signal Display │
│ Autopilot │ │ (Dashboard) │
├───────────────────┤ └───────────────────┘
│ MarketAnalyzer │
│ StrategySelector │
│ PerformanceTracker│
└───────────────────┘
│
▼
┌───────────────────────┐
│ Signal Generation │
│ (StrategySignal) │
└───────────────────────┘
│
▼
┌───────────────────┐
│ Auto-Execution │
│ (Optional) │
└───────────────────┘
```
## ML-Based Autopilot Flow
> [!NOTE]
> **Global Model Architecture**: The system uses a single "Global Model" trained on data from *all* configured symbols. This allows for shared learning (patterns from BTC help predict ETH) and efficient resource usage.
> [!IMPORTANT]
> **Single-Asset Focus**: The current ML model is designed for **single-asset strategies** (e.g., Momentum, RSI, Grid). It analyzes each coin in isolation. It does **NOT** currently support multi-asset strategies like **Arbitrage**, which require analyzing correlations between multiple coins simultaneously.
```
Market Data (OHLCV)
│
▼
┌───────────────────┐
│ MarketAnalyzer │
│ - Analyze │
│ conditions │
│ - Determine │
│ regime │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ StrategySelector │
│ - Global ML Model │
│ - Select best │
│ strategy │
│ - Calculate │
│ confidence │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Selected Strategy │
│ - Generate signal│
│ - Calculate size │
└─────────┬─────────┘
│
▼
StrategySignal
```
## API Endpoints
### Unified Endpoints
- `POST /api/autopilot/start-unified` - Start autopilot
- `POST /api/autopilot/stop-unified` - Stop autopilot
- `GET /api/autopilot/status-unified/{symbol}` - Get autopilot status
### Legacy Endpoints (Removed)
- `POST /api/autopilot/start` - (Removed)
- `POST /api/autopilot/intelligent/start` - (Removed)
## Mode Selection Logic
The unified endpoints now exclusively support the "intelligent" mode. Code handling other modes has been removed.
```python
def start_unified_autopilot(config: UnifiedAutopilotConfig):
# Always starts intelligent autopilot
autopilot = get_intelligent_autopilot(
symbol=config.symbol,
exchange_id=config.exchange_id,
timeframe=config.timeframe,
interval=config.interval,
paper_trading=config.paper_trading
)
if config.auto_execute:
autopilot.enable_auto_execution = True
autopilot.start()
```
## Auto-Execution Integration
Auto-execution is integrated directly into the ML-based workflow:
```python
# Auto-Execution
if auto_execute and signal and confidence > threshold:
trading_engine.execute_order(
symbol=signal.symbol,
side=signal.signal_type,
quantity=strategy.calculate_position_size(signal, balance),
...
)
```
## Pre-Flight Order Validation
Before submitting orders, the autopilot validates that the order will succeed:
```python
async def _can_execute_order(side, quantity, price) -> Tuple[bool, str]:
# 1. Check minimum order value ($1 USD)
if order_value < 1.0:
return False, "Order value below minimum"
# 2. For BUY: check sufficient balance (with fee buffer)
if side == BUY:
if balance < (order_value + fee_estimate):
return False, "Insufficient funds"
# 3. For SELL: check position exists
if side == SELL:
if no_position:
return False, "No position to sell"
return True, "OK"
```
**Benefits:**
- Prevents creation of PENDING orders that would be REJECTED
- Cleaner order history (no garbage orders)
- Faster execution (skip validation at execution layer)
## Smart Order Type Selection
The autopilot intelligently chooses between LIMIT and MARKET orders:
| Scenario | Order Type | Rationale |
|----------|-----------|-----------|
| Strong signal (>80%) | MARKET | High confidence, execute now |
| Normal BUY signal | LIMIT (-0.1%) | Get better entry, pay maker fees |
| Take-profit SELL | LIMIT (+0.1%) | Get better exit price |
| Stop-loss SELL | MARKET | Urgent exit, protect capital |
```python
def _determine_order_type_and_price(side, signal_strength, price, is_stop_loss):
# Strong signals or stop-losses use MARKET
if signal_strength > 0.8 or is_stop_loss:
return MARKET, None
# Normal signals use LIMIT with 0.1% better price
if side == BUY:
limit_price = price * 0.999 # 0.1% below market
else:
limit_price = price * 1.001 # 0.1% above market
return LIMIT, limit_price
```
**Stop-Loss vs Take-Profit Detection:**
- If `current_price < entry_price`: Stop-loss (use MARKET)
- If `current_price > entry_price`: Take-profit (use LIMIT)
## Data Flow
1. **Market Data Collection**: OHLCV data from database
2. **Market Analysis**: MarketAnalyzer determines conditions
3. **Strategy Selection**: ML model selects best strategy
4. **Signal Generation**: Selected strategy generates signal
5. **Opportunity Evaluation**: Check confidence and criteria
6. **Execution** (if enabled): Execute trade
7. **Learning**: Record trade for model improvement
## Component Responsibilities
- **MarketAnalyzer**: Analyzes market conditions and determines regime
- **StrategySelector**: ML model for selecting optimal strategy
- **PerformanceTracker**: Tracks strategy performance for learning
- **IntelligentAutopilot**: Orchestrates ML-based selection and execution
## Configuration
```python
{
"symbol": "BTC/USD",
"exchange_id": 1,
"timeframe": "1h",
"interval": 60.0, # Analysis cycle in seconds
"paper_trading": True,
"min_confidence_threshold": 0.75,
"max_trades_per_day": 10,
"auto_execute": False
}
```
## State Management
- `_running`: Boolean flag
- `_last_analysis`: Last analysis result
- `_selected_strategy`: Currently selected strategy
- `_trades_today`: Trade count for daily limit
- `_ohlcv_data`: Current market data
- `_strategy_instances`: Cached strategy instances
- `_intelligent_autopilots`: Global registry of active instances
## Error Handling
Both modes implement error handling:
- **Market Data Errors**: Fallback to cached data or skip cycle
- **Pattern Detection Errors**: Return no pattern, continue monitoring
- **Sentiment Analysis Errors**: Use neutral sentiment, continue
- **ML Model Errors**: Fallback to rule-based selection
- **Execution Errors**: Log error, continue monitoring
## Performance Considerations
- **Moderate**: ML model adds overhead but is optimized for speed
- **Adaptive**: Performance improves with more training data
- **Scalable**: Model can handle multiple symbols with shared learning
## ML Model Training
The ML model training system supports background training via Celery with configurable parameters.
### Training Configuration
Training is configured via the Bootstrap Config API and persisted in the application config:
| Parameter | Description | Default |
|-----------|-------------|---------|
| `days` | Historical data (days) to fetch | 90 |
| `timeframe` | OHLCV candle timeframe | `1h` |
| `min_samples_per_strategy` | Minimum samples needed per strategy | 10 |
| `symbols` | Cryptocurrencies to train on | `["BTC/USD", "ETH/USD"]` |
### API Endpoints
```
GET /api/autopilot/bootstrap-config # Get current config
PUT /api/autopilot/bootstrap-config # Update config
POST /api/autopilot/intelligent/retrain # Trigger retraining
GET /api/autopilot/tasks/{task_id} # Poll training status
GET /api/autopilot/intelligent/model-info # Get model info
POST /api/autopilot/intelligent/reset # Reset model
```
### Background Training Architecture
```
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Settings Page │────▶│ FastAPI │────▶│ Celery Worker │
│ (React) │ │ Backend │ │ (train_task) │
└─────────────────┘ └──────────────┘ └─────────────────┘
│ │ │
│ Poll status │ get_config() │ Reset singletons
│◀─────────────────────│ │ Bootstrap data
│ │ │ Train model
│ │ │ Save to disk
│ │◀─────────────────────│
│ SUCCESS + metrics │ │
│◀─────────────────────│ │
│ │ │
▼ ▼ ▼
UI shows results Model auto-loads Model file saved
```
### Training Task Flow
1. **Singleton Reset**: Reset `StrategySelector`, `PerformanceTracker`, and `Database` singletons to prevent async conflicts
2. **Check Existing Data**: Query performance tracker for existing training samples
3. **Bootstrap (if needed)**: Fetch OHLCV data for each symbol with progress updates
4. **Train Model**: Train ML model with cross-validation and walk-forward validation
5. **Save Model**: Persist trained model to `~/.local/share/crypto_trader/models/`
6. **Return Metrics**: Return training accuracy and model metadata
### Model Auto-Reload
The `StrategySelector.get_model_info()` method automatically checks for new model files:
```python
def get_model_info(self):
# Always check if a newer model is available on disk
self._try_load_saved_model() # Compare timestamps, reload if newer
return {...}
```
This ensures the API process picks up newly trained models without restart.
### Error Handling
- **Celery Task Errors**: Serialized to JSON with traceback for frontend display
- **Polling Errors**: Frontend stops polling after 3 consecutive failures
- **Connection Errors**: Singletons reset to prevent `asyncpg.InterfaceError`
## Strategy Grouping
To improve ML accuracy, individual strategies are grouped into 5 logical categories. The model predicts the best **group**, then rule-based logic selects the optimal strategy within that group.
### Strategy Groups
| Group | Strategies | Market Conditions |
|-------|-----------|-------------------|
| **Trend Following** | moving_average, macd, confirmed | Strong trends (ADX > 25) |
| **Mean Reversion** | rsi, bollinger_mean_reversion, grid, divergence | Ranging markets, oversold/overbought |
| **Momentum** | momentum, volatility_breakout | High volume spikes, breakouts |
| **Market Making** | market_making, dca | Low volatility, stable markets |
| **Sentiment Based** | sentiment, pairs_trading, consensus | External signals available |
### Benefits
- **Reduced Classes**: 5 groups vs 14 strategies (~20% random baseline vs ~7%)
- **Better Generalization**: Model learns group characteristics rather than memorizing individual strategies
- **Combined Confidence**: `group_confidence × strategy_confidence` for final score
## Improved Bootstrap Sampling
Training data is collected using intelligent sampling rather than fixed intervals:
### Sampling Strategies
1. **Regime-Change Detection**: Sample when market regime changes (e.g., trending → ranging)
2. **Minimum Time Spacing**: 24-hour gaps between samples for 1h timeframe
3. **Periodic Sampling**: Every 48 hours regardless of regime changes
### Timeframe Spacing
| Timeframe | Min Spacing (candles) | Actual Time |
|-----------|----------------------|-------------|
| 1m | 1440 | 24 hours |
| 15m | 96 | 24 hours |
| 1h | 24 | 24 hours |
| 4h | 6 | 24 hours |
| 1d | 1 | 24 hours |
## Security Considerations
- **Auto-Execution**: Requires explicit user confirmation
- **Paper Trading**: Default mode for safety
- **Risk Limits**: Enforced regardless of mode
- **API Keys**: Encrypted storage
- **Audit Logging**: All autopilot actions logged
## Future Enhancements
- Hybrid mode combining both approaches
- Real-time mode switching
- Multi-symbol autopilot management
- Advanced risk management integration
- Performance analytics dashboard
- Persistent training configuration (file/database storage)

135
docs/architecture/backtesting.md Normal file
View File

@@ -0,0 +1,135 @@
# Backtesting Engine Architecture
This document describes the backtesting engine design.
## Backtesting Components
```
Backtesting Engine
├──► Data Provider
│ │
│ └──► Historical Data Loading
│
├──► Strategy Execution
│ │
│ ├──► Data Replay
│ ├──► Signal Generation
│ └──► Order Simulation
│
├──► Realism Models
│ │
│ ├──► Slippage Model
│ ├──► Fee Model
│ └──► Order Book Simulation
│
└──► Metrics Calculation
│
├──► Performance Metrics
└──► Risk Metrics
```
## Data Replay
Historical data is replayed chronologically:
```
Historical Data (Time Series)
│
▼
Time-based Iteration
│
├──► For each timestamp:
│ │
│ ├──► Update market data
│ ├──► Notify strategies
│ ├──► Process signals
│ └──► Execute orders
│
└──► Continue until end date
```
## Order Simulation
Simulated order execution:
```
Order Request
│
▼
Order Type Check
│
├──► Market Order
│ │
│ └──► Execute at current price + slippage
│
└──► Limit Order
│
└──► Wait for price to reach limit
│
└──► Execute when filled
```
## Slippage Modeling
Realistic slippage simulation:
```
Market Order
│
▼
Current Price
│
├──► Buy Order: Price + Slippage
└──► Sell Order: Price - Slippage
│
└──► Add Market Impact (for large orders)
```
## Fee Modeling
Exchange fee calculation:
```
Order Execution
│
▼
Order Type Check
│
├──► Maker Order (Limit)
│ │
│ └──► Apply Maker Fee
│
└──► Taker Order (Market)
│
└──► Apply Taker Fee
```
## Performance Metrics
Calculated metrics:
- **Total Return**: (Final Capital - Initial Capital) / Initial Capital
- **Sharpe Ratio**: (Return - Risk-free Rate) / Volatility
- **Sortino Ratio**: (Return - Risk-free Rate) / Downside Deviation
- **Max Drawdown**: Largest peak-to-trough decline
- **Win Rate**: Winning Trades / Total Trades
- **Profit Factor**: Gross Profit / Gross Loss
## Parameter Optimization
Optimization methods:
- **Grid Search**: Test all parameter combinations
- **Genetic Algorithm**: Evolutionary optimization
- **Bayesian Optimization**: Efficient parameter search
## Backtest Results
Stored results:
- Performance metrics
- Trade history
- Equity curve
- Drawdown chart
- Parameter values

233
docs/architecture/data_flow.md Normal file
View File

@@ -0,0 +1,233 @@
# Data Flow Architecture
This document describes how data flows through the Crypto Trader system.
## Real-Time Data Flow
```
Exchange WebSocket
│
▼
Exchange Adapter
│
▼
Data Collector
│
├──► Data Quality Validation
│
├──► Data Storage (Database)
│
└──► Timeframe Manager
│
├──► Strategy 1 (1h timeframe)
├──► Strategy 2 (15m timeframe)
└──► Strategy 3 (1d timeframe)
│
▼
Signal Generation
│
▼
Trading Engine
```
## Trading Signal Flow
```
Market Data Update
│
▼
Strategy.on_data()
│
▼
Indicator Calculation
│
▼
Signal Generation
│
▼
Trading Engine
│
├──► Risk Manager (Pre-trade Check)
│ │
│ ├──► Position Sizing
│ ├──► Drawdown Check
│ └──► Daily Loss Check
│
▼
Order Manager
│
├──► Paper Trading (if enabled)
│ │
│ └──► Paper Trading Simulator
│
└──► Live Trading
│
▼
Exchange Adapter
│
▼
Exchange API
│
▼
Order Execution
│
▼
Order Manager (Update Status)
│
▼
Position Tracker
│
▼
Portfolio Analytics
```
## Backtesting Data Flow
```
Historical Data Provider
│
▼
Backtesting Engine
│
├──► Data Replay (Time-based)
│
├──► Strategy Execution
│ │
│ ├──► Signal Generation
│ │
│ └──► Order Simulation
│ │
│ ├──► Slippage Model
│ ├──► Fee Model
│ └──► Order Book Simulation
│
└──► Performance Calculation
│
├──► Metrics Calculation
│ │
│ ├──► Returns
│ ├──► Sharpe Ratio
│ ├──► Sortino Ratio
│ └──► Drawdown
│
└──► Results Storage
```
## Portfolio Update Flow
```
Trade Execution
│
▼
Position Update
│
├──► Position Tracker
│ │
│ ├──► Update Quantity
│ ├──► Update Entry Price
│ └──► Calculate P&L
│
└──► Portfolio Analytics
│
├──► Recalculate Metrics
│ │
│ ├──► Total Value
│ ├──► Unrealized P&L
│ ├──► Realized P&L
│ └──► Performance Metrics
│
└──► Alert System
│
└──► Risk Alerts (if triggered)
```
## Data Storage Flow
```
Data Collection
│
▼
Data Quality Check
│
├──► Valid Data
│ │
│ └──► Database Storage
│ │
│ ├──► Market Data Table
│ ├──► Trades Table
│ └──► Positions Table
│
└──► Invalid Data
│
└──► Error Logging
│
└──► Gap Detection
│
└──► Gap Filling (if enabled)
```
## Multi-Timeframe Synchronization
```
1m Data Stream
│
├──► Strategy (1m)
│
└──► Resample to 5m
│
├──► Strategy (5m)
│
└──► Resample to 1h
│
├──► Strategy (1h)
│
└──► Resample to 1d
│
└──► Strategy (1d)
```
## Alert Flow
```
Data Update / Event
│
▼
Alert Engine
│
├──► Check Alert Conditions
│ │
│ ├──► Price Alerts
│ ├──► Indicator Alerts
│ ├──► Risk Alerts
│ └──► System Alerts
│
└──► Trigger Alert (if condition met)
│
├──► Desktop Notification
├──► Sound Alert
└──► Email Notification (if configured)
```
## Error Recovery Flow
```
Error Detected
│
▼
Error Recovery System
│
├──► Log Error
│
├──► Attempt Recovery
│ │
│ ├──► Retry Operation
│ ├──► Fallback Mechanism
│ └──► State Restoration
│
└──► Health Monitor
│
├──► Check System Health
│
└──► Auto-restart (if critical)
```

288
docs/architecture/database_schema.md Normal file
View File

@@ -0,0 +1,288 @@
# Database Schema
This document describes the database schema for Crypto Trader.
## Database Options
- **SQLite**: Default, bundled, zero configuration
- **PostgreSQL**: Optional, for advanced users with large datasets
## Core Tables
### Exchanges
Stores exchange configuration and credentials.
```sql
CREATE TABLE exchanges (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE NOT NULL,
api_key TEXT, -- Encrypted
secret_key TEXT, -- Encrypted
password TEXT, -- Encrypted (for some exchanges)
api_permissions TEXT DEFAULT 'read_only',
is_enabled BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Strategies
Stores trading strategy configuration.
```sql
CREATE TABLE strategies (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE NOT NULL,
description TEXT,
strategy_type TEXT NOT NULL,
parameters TEXT, -- JSON
is_enabled BOOLEAN DEFAULT FALSE,
is_paper_trading BOOLEAN DEFAULT TRUE,
exchange_id INTEGER REFERENCES exchanges(id),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Trades
Stores executed trades.
```sql
CREATE TABLE trades (
id INTEGER PRIMARY KEY,
order_id TEXT UNIQUE NOT NULL,
symbol TEXT NOT NULL,
side TEXT NOT NULL, -- 'buy' or 'sell'
type TEXT NOT NULL, -- 'market', 'limit', etc.
price REAL,
amount REAL,
cost REAL,
fee REAL DEFAULT 0.0,
status TEXT DEFAULT 'open',
is_paper_trade BOOLEAN DEFAULT TRUE,
executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
strategy_id INTEGER REFERENCES strategies(id)
);
```
### Positions
Stores open and closed positions.
```sql
CREATE TABLE positions (
id INTEGER PRIMARY KEY,
symbol TEXT NOT NULL,
exchange_id INTEGER REFERENCES exchanges(id),
quantity REAL NOT NULL,
entry_price REAL NOT NULL,
current_price REAL,
unrealized_pnl REAL,
realized_pnl REAL,
is_open BOOLEAN DEFAULT TRUE,
position_type TEXT DEFAULT 'spot', -- 'spot', 'futures', 'margin'
leverage REAL DEFAULT 1.0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP,
UNIQUE(symbol, exchange_id, position_type)
);
```
### Orders
Stores order history and status.
```sql
CREATE TABLE orders (
id INTEGER PRIMARY KEY,
exchange_order_id TEXT UNIQUE NOT NULL,
client_order_id TEXT,
symbol TEXT NOT NULL,
side TEXT NOT NULL,
type TEXT NOT NULL,
price REAL,
amount REAL,
filled_amount REAL DEFAULT 0.0,
remaining_amount REAL DEFAULT 0.0,
cost REAL DEFAULT 0.0,
status TEXT DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
strategy_id INTEGER REFERENCES strategies(id),
is_paper_trade BOOLEAN DEFAULT TRUE
);
```
### Market Data
Stores historical OHLCV data.
```sql
CREATE TABLE market_data (
id INTEGER PRIMARY KEY,
symbol TEXT NOT NULL,
timeframe TEXT NOT NULL,
timestamp TIMESTAMP NOT NULL,
open REAL NOT NULL,
high REAL NOT NULL,
low REAL NOT NULL,
close REAL NOT NULL,
volume REAL NOT NULL,
exchange_id INTEGER REFERENCES exchanges(id),
UNIQUE(symbol, timeframe, timestamp)
);
```
### Portfolio Snapshots
Stores portfolio snapshots over time.
```sql
CREATE TABLE portfolio_snapshots (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
total_value REAL NOT NULL,
cash_balance REAL NOT NULL,
asset_holdings TEXT, -- JSON
exchange_id INTEGER REFERENCES exchanges(id)
);
```
### Backtest Results
Stores backtesting results.
```sql
CREATE TABLE backtest_results (
id INTEGER PRIMARY KEY,
strategy_id INTEGER REFERENCES strategies(id),
start_date TIMESTAMP NOT NULL,
end_date TIMESTAMP NOT NULL,
initial_capital REAL NOT NULL,
final_capital REAL NOT NULL,
total_return REAL NOT NULL,
sharpe_ratio REAL,
sortino_ratio REAL,
max_drawdown REAL,
win_rate REAL,
other_metrics TEXT, -- JSON
run_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Risk Limits
Stores risk management limits.
```sql
CREATE TABLE risk_limits (
id INTEGER PRIMARY KEY,
strategy_id INTEGER REFERENCES strategies(id),
exchange_id INTEGER REFERENCES exchanges(id),
limit_type TEXT NOT NULL,
value REAL NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Alerts
Stores alert configurations.
```sql
CREATE TABLE alerts (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
alert_type TEXT NOT NULL,
condition TEXT NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
triggered_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Rebalancing Events
Stores portfolio rebalancing history.
```sql
CREATE TABLE rebalancing_events (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
old_allocations TEXT, -- JSON
new_allocations TEXT, -- JSON
executed_trades TEXT, -- JSON
status TEXT DEFAULT 'completed'
);
```
### App State
Stores application state for recovery.
```sql
CREATE TABLE app_state (
id INTEGER PRIMARY KEY,
key TEXT UNIQUE NOT NULL,
value TEXT, -- JSON
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Audit Log
Stores security audit events.
```sql
CREATE TABLE audit_log (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
event_type TEXT NOT NULL,
user_id TEXT,
details TEXT -- JSON
);
```
## Indexes
Key indexes for performance:
- `market_data(symbol, timeframe, timestamp)` - Unique index
- `trades(symbol, executed_at)` - For trade queries
- `positions(symbol, exchange_id, is_open)` - For position lookups
- `orders(status, created_at)` - For order management
- `strategies(is_enabled)` - For active strategy queries
## Relationships
- **Exchanges** → **Strategies** (one-to-many)
- **Exchanges** → **Trades** (one-to-many)
- **Strategies** → **Trades** (one-to-many)
- **Strategies** → **Backtest Results** (one-to-many)
- **Exchanges** → **Positions** (one-to-many)
- **Exchanges** → **Market Data** (one-to-many)
## Data Retention
Configurable retention policies:
- **Market Data**: Configurable (default: 1 year)
- **Trades**: Permanent
- **Orders**: Permanent
- **Portfolio Snapshots**: Configurable (default: 1 year)
- **Logs**: Configurable (default: 30 days)
## Backup and Recovery
- **Automatic Backups**: Before critical operations
- **Manual Backups**: Via export functionality
- **Recovery**: From backup files or database dumps

176
docs/architecture/exchange_integration.md Normal file
View File

@@ -0,0 +1,176 @@
# Exchange Integration Architecture
This document describes how exchange adapters integrate with the trading system.
## Adapter Pattern
All exchanges use the adapter pattern to provide a unified interface:
```
Trading Engine
│
▼
BaseExchange (Interface)
│
├──► CoinbaseExchange
├──► BinanceExchange (future)
└──► KrakenExchange (future)
```
## Base Exchange Interface
All exchanges implement `BaseExchange`:
```python
class BaseExchange(ABC):
async def connect()
async def disconnect()
async def fetch_balance()
async def place_order()
async def cancel_order()
async def fetch_order_status()
async def fetch_ohlcv()
async def subscribe_ohlcv()
async def subscribe_trades()
async def subscribe_order_book()
async def fetch_open_orders()
async def fetch_positions()
async def fetch_markets()
```
## Exchange Factory
The factory pattern creates exchange instances:
```
ExchangeFactory
│
├──► get_exchange(name)
│ │
│ ├──► Lookup registered adapter
│ ├──► Get API keys from KeyManager
│ └──► Instantiate adapter
│
└──► register_exchange(name, adapter_class)
```
## Exchange Registration
Exchanges are registered at module import:
```python
# In exchange module
from src.exchanges.factory import ExchangeFactory
ExchangeFactory.register_exchange("coinbase", CoinbaseExchange)
```
## CCXT Integration
Most exchanges use the CCXT library:
```python
import ccxt.pro as ccxt
class CoinbaseExchange(BaseExchange):
def __init__(self, ...):
self.exchange = ccxt.coinbaseadvanced({
'apiKey': api_key,
'secret': secret_key,
'enableRateLimit': True,
})
```
## WebSocket Support
Real-time data via WebSockets:
```python
async def subscribe_ohlcv(self, symbol, timeframe, callback):
"""Subscribe to OHLCV updates."""
await self.exchange.watch_ohlcv(symbol, timeframe, callback)
```
## Rate Limiting
All exchanges respect rate limits:
- CCXT handles rate limiting automatically
- `enableRateLimit: True` in exchange config
- Custom rate limiting for non-CCXT exchanges
## Error Handling
Exchange-specific error handling:
```python
try:
order = await self.exchange.create_order(...)
except ccxt.NetworkError as e:
# Handle network errors
logger.error(f"Network error: {e}")
raise
except ccxt.ExchangeError as e:
# Handle exchange errors
logger.error(f"Exchange error: {e}")
raise
```
## Connection Management
- **Connection Pooling**: Reuse connections when possible
- **Auto-Reconnect**: Automatic reconnection on disconnect
- **Health Monitoring**: Monitor connection health
- **Graceful Shutdown**: Properly close connections
## Adding New Exchanges
See [Adding Exchanges](../developer/adding_exchanges.md) for detailed guide.
## Exchange-Specific Features
Some exchanges have unique features:
- **Coinbase**: Requires passphrase for some operations
- **Binance**: Futures and margin trading
- **Kraken**: Different order types
These are handled in exchange-specific adapters.
## WebSocket Implementation
### Coinbase WebSocket Support
The Coinbase adapter includes WebSocket subscription methods:
- **subscribe_ticker()**: Subscribe to real-time price updates
- **subscribe_orderbook()**: Subscribe to order book changes
- **subscribe_trades()**: Subscribe to trade executions
### WebSocket Architecture
```
Exchange WebSocket API
↓
CoinbaseAdapter.subscribe_*()
↓
Callback Functions
↓
DataCollector (with signals)
↓
UI Widgets (via signals)
```
### Reconnection Strategy
- Automatic reconnection on disconnect
- Message queuing during disconnection
- Heartbeat/ping-pong for connection health
- Fallback to polling if WebSocket unavailable
### Implementation Notes
- Uses `websockets` library for async WebSocket connections
- Callbacks are wrapped to emit Qt signals for UI updates
- Basic implementation provided; can be extended for full Coinbase Advanced Trade WebSocket API

185
docs/architecture/overview.md Normal file
View File

@@ -0,0 +1,185 @@
# Architecture Overview
This document provides a high-level overview of the Crypto Trader architecture.
## System Architecture
Crypto Trader follows a modular architecture with clear separation of concerns:
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (React + Vite) │
│ Dashboard | Strategies | Portfolio | Backtest | Settings│
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Backend API (FastAPI) │
│ Autopilot | Trading | Market Data | WebSocket │
└─────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Redis │ │ Celery │ │ PostgreSQL │
│ State/Cache │←───│ Workers │ │ Database │
└──────────────┘ └──────────────┘ └──────────────────┘
▲ │
│ ▼
┌─────────────────────────────────────────────────────────┐
│ Trading Engine │
│ Order Management | Position Tracking | Risk Management │
└─────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Strategies │ │ Exchanges │ │ Portfolio │
│ Framework │ │ Adapters │ │ Tracker │
└──────────────┘ └──────────────┘ └──────────────┘
```
## Core Components
### 1. Frontend Layer
- **Framework**: React with TypeScript
- **Build Tool**: Vite
- **Components**: Dashboard, Strategy Manager, Portfolio View, Backtest View, Settings
- **State Management**: React Query, Context API
- **Styling**: Material-UI (MUI)
### 2. Backend API
- **Framework**: FastAPI (async Python)
- **Features**: RESTful API, WebSocket support, auto-docs (Swagger/OpenAPI)
- **Authentication**: JWT tokens (planned)
- **Responsibilities**: Orchestrates all business logic
### 3. Redis (State Management)
- **Purpose**: Distributed state management and caching
- **Use Cases**:
- Autopilot registry (prevents multiple instances)
- Daily trade count persistence (survives restarts)
- Session caching (planned)
- Real-time data caching (planned)
- **Configuration**: `src/core/config.py` → `redis` section
### 4. Celery (Background Tasks)
- **Purpose**: Offload CPU-intensive tasks from the API
- **Use Cases**:
- ML model training (`train_model_task`)
- Data bootstrapping (`bootstrap_task`)
- Report generation (`generate_report_task`)
- **Broker**: Redis
- **Worker Command**: `celery -A src.worker.app worker --loglevel=info`
### 5. Trading Engine
- **Responsibilities**: Order execution, position management, risk checks
- **Components**: Trading engine, order manager, paper trading simulator
- **Integration**: Connects strategies to exchanges
### 6. Strategy Framework
- **Base Class**: `BaseStrategy` provides common interface
- **Registry**: Manages available strategies (RSI, MACD, Bollinger, etc.)
- **ML Selection**: `IntelligentAutopilot` uses ML to select optimal strategies
- **Features**: Multi-timeframe support, scheduling, parameter management
### 7. Exchange Adapters
- **Pattern**: Adapter pattern for unified interface
- **Factory**: Dynamic exchange instantiation
- **Current**: Coinbase Advanced Trade API, Binance Public
- **Data Providers**: CCXT-based providers with automatic failover
### 8. Risk Management
- **Components**: Risk manager, stop-loss, position sizing, limits
- **Integration**: Pre-trade checks, real-time monitoring
- **Features**: Drawdown limits, daily loss limits, position limits
### 9. Backtesting Engine
- **Features**: Historical data replay, realistic simulation
- **Components**: Engine, metrics, slippage model, fee model
- **Optimization**: Parameter optimization support
### 10. Portfolio Management
- **Tracking**: Real-time position tracking
- **Analytics**: Performance metrics, risk analysis
- **Rebalancing**: Automatic portfolio rebalancing (planned)
## Data Flow
### Trading Flow
1. User starts autopilot → API receives request
2. Redis lock checked/set → Prevents duplicate instances
3. Strategy generates signal
4. Risk manager validates trade
5. Order manager creates order
6. Exchange adapter executes order
7. Position tracker updates positions
8. Redis updates trade count
### ML Training Flow (Background)
1. User triggers `/retrain` API
2. API queues `train_model_task` to Celery
3. API returns task ID immediately (non-blocking)
4. Celery worker picks up task
5. Worker bootstraps data if needed
6. Worker trains model
7. User polls `/tasks/{task_id}` for status
## Technology Stack
- **Language**: Python 3.11+
- **Frontend**: React 18, TypeScript, Vite
- **Backend**: FastAPI, Uvicorn
- **Database**: PostgreSQL with SQLAlchemy
- **Cache/State**: Redis
- **Task Queue**: Celery
- **Exchange Library**: CCXT
- **Data Analysis**: Pandas, NumPy
- **Machine Learning**: LightGBM, scikit-learn
- **Technical Analysis**: pandas-ta, TA-Lib
- **Async**: asyncio
- **Testing**: pytest, React Testing Library
## Design Patterns
- **Adapter Pattern**: Exchange adapters
- **Factory Pattern**: Exchange and strategy creation
- **Strategy Pattern**: Trading strategies
- **Observer Pattern**: Data updates to strategies
- **Singleton Pattern**: Configuration, database connections, Redis client
## Security Architecture
- **API Key Encryption**: Fernet encryption
- **Secure Storage**: Keyring integration
- **Audit Logging**: All security events logged
- **Permission Management**: Read-only vs trading modes
## Scalability Considerations
- **Async Operations**: Non-blocking I/O throughout
- **Redis State**: Enables horizontal scaling of API workers
- **Celery Workers**: Can scale independently for heavy workloads
- **Database Optimization**: Indexed queries, connection pooling
- **Data Retention**: Configurable retention policies
## Extension Points
- **Exchange Adapters**: Add new exchanges via adapter interface
- **Strategies**: Create custom strategies via base class
- **Indicators**: Add custom indicators
- **Order Types**: Extend advanced order types
- **Risk Rules**: Add custom risk management rules
- **Celery Tasks**: Add new background tasks in `src/worker/tasks.py`

165
docs/architecture/risk_management.md Normal file
View File

@@ -0,0 +1,165 @@
# Risk Management Architecture
This document describes the risk management system.
## Risk Management Components
```
Risk Manager
├──► Pre-Trade Checks
│ │
│ ├──► Position Sizing
│ ├──► Daily Loss Limit
│ └──► Portfolio Allocation
│
├──► Real-Time Monitoring
│ │
│ ├──► Drawdown Monitoring
│ ├──► Position Monitoring
│ └──► Portfolio Monitoring
│
└──► Stop Loss Management
│
├──► Stop Loss Orders
└──► Trailing Stops
```
## Pre-Trade Risk Checks
Before executing any trade:
1. **Position Sizing Check**
- Verify position size within limits
- Check portfolio allocation
- Validate against risk parameters
2. **Daily Loss Limit Check**
- Calculate current daily P&L
- Compare against daily loss limit
- Block trades if limit exceeded
3. **Drawdown Check**
- Calculate current drawdown
- Compare against max drawdown limit
- Block trades if limit exceeded
4. **Portfolio Allocation Check**
- Verify total exposure within limits
- Check per-asset allocation
- Validate diversification requirements
## Position Sizing Methods
### Fixed Percentage
```python
position_size = capital * percentage
```
### Kelly Criterion
```python
f = (bp - q) / b
position_size = capital * f
```
### Volatility-Based
```python
position_size = (capital * risk_percentage) / (stop_loss_distance * price)
```
## Risk Limits
Configurable limits:
- **Max Drawdown**: Maximum allowed drawdown percentage
- **Daily Loss Limit**: Maximum daily loss percentage
- **Position Size Limit**: Maximum position value
- **Portfolio Exposure**: Maximum portfolio exposure percentage
## Stop Loss Management
### Stop Loss Types
- **Fixed Stop Loss**: Fixed price level
- **Trailing Stop**: Adjusts with price movement
- Percentage-based: Adjusts by fixed percentage
- ATR-based: Adjusts based on volatility (Average True Range)
- **Percentage Stop**: Percentage below entry
- **ATR-based Stop**: Based on Average True Range (volatility-adjusted)
- Automatically calculates stop distance using ATR multiplier
- Adapts to market volatility conditions
- Configurable ATR period (default: 14) and multiplier (default: 2.0)
- Works with both fixed and trailing stops
### ATR-Based Dynamic Stops
ATR-based stops provide better risk management in volatile markets:
```python
stop_loss_manager.set_stop_loss(
position_id=1,
stop_price=entry_price,
use_atr=True,
atr_multiplier=Decimal('2.0'),
atr_period=14,
ohlcv_data=market_data,
trailing=True
)
```
**Benefits:**
- Adapts to market volatility
- Tighter stops in low volatility, wider in high volatility
- Reduces stop-outs during normal market noise
- Better risk-adjusted returns
**Calculation:**
- Stop distance = ATR × multiplier
- For long positions: stop_price = entry_price - (ATR × multiplier)
- For short positions: stop_price = entry_price + (ATR × multiplier)
### Stop Loss Execution
```
Price Update
│
▼
Stop Loss Check
│
├──► Stop Loss Triggered?
│ │
│ └──► Execute Market Sell
│
└──► Update Trailing Stop (if applicable)
```
## Real-Time Monitoring
Continuous monitoring of:
- Portfolio value
- Unrealized P&L
- Drawdown levels
- Position sizes
- Risk metrics
## Risk Alerts
Automatic alerts for:
- Drawdown threshold exceeded
- Daily loss limit reached
- Position size exceeded
- Portfolio exposure exceeded
## Integration Points
Risk management integrates with:
- **Trading Engine**: Pre-trade validation
- **Order Manager**: Position tracking
- **Portfolio Tracker**: Real-time monitoring
- **Alert System**: Risk alerts

135
docs/architecture/security.md Normal file
View File

@@ -0,0 +1,135 @@
# Security Architecture
This document describes the security architecture of Crypto Trader.
## Security Layers
```
Application Layer
├──► API Key Encryption
├──► Permission Management
└──► Audit Logging
│
▼
Storage Layer
├──► Encrypted Storage
└──► Secure Key Management
```
## API Key Encryption
### Encryption Process
```
Plain API Key
│
▼
Fernet Encryption
│
▼
Encrypted Key (Stored in Database)
```
### Key Management
- **Encryption Key**: Stored securely (environment variable or keyring)
- **Key Generation**: Automatic on first use
- **Key Rotation**: Manual rotation process
## Permission Management
### Permission Levels
- **Read-Only**: Data collection, backtesting only
- **Trading Enabled**: Full trading capabilities
### Permission Enforcement
```
API Request
│
▼
Permission Check
│
├──► Read-Only Request
│ │
│ └──► Allow (read operations)
│
└──► Trading Request
│
├──► Trading Enabled?
│ │
│ ├──► Yes: Allow
│ └──► No: Reject
```
## Secure Storage
### Keyring Integration
- **Linux**: Secret Service (GNOME Keyring)
- **macOS**: Keychain
- **Windows**: Windows Credential Manager
### Fallback Storage
If keyring unavailable:
- Environment variable (development only)
- Encrypted file with user permission
## Audit Logging
All security events are logged:
- API key changes
- Permission changes
- Trading operations
- Configuration changes
- Error events
### Audit Log Format
```python
{
"timestamp": "2025-12-13T19:00:00Z",
"event_type": "API_KEY_CHANGED",
"user_id": "system",
"details": {
"exchange": "coinbase",
"action": "updated"
}
}
```
## Data Privacy
- **Local Storage**: All data stored locally
- **No Telemetry**: No data sent externally
- **Encryption**: Sensitive data encrypted at rest
- **Access Control**: File system permissions
## Best Practices
1. **Use Read-Only Keys**: When possible, use read-only API keys
2. **IP Whitelisting**: Enable IP whitelisting on exchange accounts
3. **Regular Rotation**: Rotate API keys periodically
4. **Secure Environment**: Keep encryption keys secure
5. **Audit Review**: Regularly review audit logs
## Threat Model
### Threats Addressed
- **API Key Theft**: Encryption at rest
- **Unauthorized Trading**: Permission checks
- **Data Breach**: Local storage, encryption
- **Man-in-the-Middle**: HTTPS for API calls
- **Key Logging**: Secure keyring storage
### Security Boundaries
- **Application Boundary**: Application code
- **Storage Boundary**: Encrypted database
- **Network Boundary**: Secure API connections
- **System Boundary**: File system permissions

208
docs/architecture/strategy_framework.md Normal file
View File

@@ -0,0 +1,208 @@
# Strategy Framework Architecture
This document describes the strategy framework design.
## Strategy Hierarchy
```
BaseStrategy (Abstract)
│
├──► Technical Strategies
│ ├──► RSIStrategy
│ ├──► MACDStrategy
│ ├──► MovingAverageStrategy
│ ├──► ConfirmedStrategy (Multi-Indicator)
│ ├──► DivergenceStrategy
│ └──► BollingerMeanReversionStrategy
│
├──► Ensemble Strategies
│ └──► ConsensusStrategy
│
├──► Other Strategies
│ ├──► DCAStrategy
│ ├──► GridStrategy
│ └──► MomentumStrategy
│
└──► CustomStrategy (user-defined)
```
## Base Strategy Interface
All strategies implement:
```python
class BaseStrategy(ABC):
async def on_data(new_data: pd.DataFrame)
async def generate_signal() -> Dict[str, Any]
async def calculate_position_size(capital, risk) -> float
async def start()
async def stop()
```
## Strategy Lifecycle
```
1. Initialization
└──► __init__(parameters)
2. Activation
└──► start()
3. Data Processing
└──► on_data(new_data)
└──► generate_signal()
└──► Trading Engine
4. Deactivation
└──► stop()
```
## Strategy Registry
Manages available strategies:
```python
StrategyRegistry
├──► register_strategy(name, class)
├──► get_strategy_class(name)
└──► list_available()
```
## Multi-Timeframe Support
Strategies can use multiple timeframes:
```
Primary Timeframe (1h)
│
├──► Signal Generation
│
└──► Higher Timeframe (1d) - Trend Confirmation
│
└──► Lower Timeframe (15m) - Entry Timing
```
## Strategy Scheduling
Strategies can be scheduled:
- **Continuous**: Run on every new candle
- **Time-based**: Run at specific times
- **Condition-based**: Run when conditions met
## Signal Generation
Signal flow:
```
Data Update
│
▼
Indicator Calculation
│
▼
Strategy Logic
│
▼
Signal Generation
│
├──► "buy" - Generate buy signal
├──► "sell" - Generate sell signal
└──► "hold" - No action
```
## Position Sizing
Strategies calculate position sizes:
- **Fixed Percentage**: Fixed % of capital
- **Kelly Criterion**: Optimal position sizing based on win rate
- **Volatility-Based**: Adjusts based on market volatility (ATR)
## Advanced Features
### Trend Filtering
All strategies can optionally use ADX-based trend filtering:
```python
signal = strategy.apply_trend_filter(
signal,
ohlcv_data,
adx_period=14,
min_adx=25.0
)
```
This filters out signals when:
- ADX < threshold (weak trend/chop)
- Signal direction doesn't match trend direction
### Multi-Indicator Confirmation
The ConfirmedStrategy requires multiple indicators to agree before generating signals, reducing false signals by 20-30%.
### Divergence Detection
Divergence strategies detect price vs. indicator divergences:
- Bullish divergence: Price lower low, indicator higher low → BUY
- Bearish divergence: Price higher high, indicator lower high → SELL
### Ensemble Methods
ConsensusStrategy aggregates signals from multiple strategies:
- Weighted voting by strategy performance
- Minimum consensus threshold
- Dynamic weighting based on recent performance
- **Kelly Criterion**: Optimal position sizing
- **Volatility-based**: Based on ATR
- **Risk-based**: Based on stop-loss distance
## Strategy Parameters
Configurable parameters:
- Strategy-specific parameters (e.g., RSI period)
- Risk parameters (position size, stop-loss)
- Timeframe settings
- Symbol selection
## Strategy Execution
Execution flow:
```
Strategy Signal
│
▼
Trading Engine
│
├──► Risk Check
│
├──► Position Sizing
│
└──► Order Execution
│
├──► Paper Trading
└──► Live Trading
```
## Strategy Performance
Performance tracking:
- Win rate
- Total return
- Sharpe ratio
- Max drawdown
- Number of trades
## Extensibility
Easy to add new strategies:
1. Inherit from `BaseStrategy`
2. Implement required methods
3. Register with `StrategyRegistry`
4. Configure and use

270
docs/architecture/ui_architecture.md Normal file
View File

@@ -0,0 +1,270 @@
# UI Architecture
This document describes the user interface architecture and how the frontend integrates with the backend API.
## Overview
The UI is built with React and TypeScript, using Material-UI for components. The frontend communicates with the FastAPI backend through REST API endpoints and WebSocket connections for real-time updates.
## Architecture
```
React Frontend → REST API / WebSocket → FastAPI Backend → Python Services → Database
```
## Frontend Structure
```
frontend/src/
├── pages/ # Page components (Trading, Portfolio, Strategies, etc.)
├── components/ # Reusable UI components
├── api/ # API client functions
├── hooks/ # Custom React hooks
└── types/ # TypeScript type definitions
```
## Page Components
### DashboardPage
- Overview of trading activity
- Key metrics and charts
- Quick actions
### TradingPage
- Order placement form
- Positions table
- Order history
- Real-time price updates
### PortfolioPage
- Portfolio summary
- Holdings table
- Risk metrics
- Performance charts
### StrategiesPage
- Strategy list and management
- Strategy configuration
- Start/stop controls
- Performance metrics
### BacktestPage
- Backtest configuration
- Results display
- Export functionality
### SettingsPage
- Exchange management
- Configuration settings
- API key management
## Real-Time Updates
### WebSocket Connection
The frontend connects to the backend WebSocket endpoint (`/ws/`) for real-time updates:
- Price updates
- Order status changes
- Position updates
- Strategy status changes
### Implementation
```typescript
// Using WebSocket hook
import { useWebSocket } from '@/hooks/useWebSocket';
function TradingPage() {
const { data, connected } = useWebSocket('/ws/');
// Handle real-time price updates
useEffect(() => {
if (data?.type === 'price_update') {
// Update UI with new price
}
}, [data]);
}
```
## API Integration
### API Client
All API calls go through the API client which handles:
- Request/response serialization
- Error handling
- Authentication (if added)
```typescript
// Example API call
import { tradingApi } from '@/api/trading';
const placeOrder = async () => {
const order = await tradingApi.placeOrder({
exchangeId: 1,
symbol: 'BTC/USD',
side: 'buy',
type: 'market',
quantity: 0.1,
paperTrading: true
});
};
```
### React Query
The frontend uses React Query for:
- Data fetching
- Caching
- Automatic refetching
- Optimistic updates
```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { portfolioApi } from '@/api/portfolio';
function PortfolioPage() {
const { data, isLoading } = useQuery({
queryKey: ['portfolio'],
queryFn: () => portfolioApi.getCurrent()
});
const updateMutation = useMutation({
mutationFn: portfolioApi.update,
onSuccess: () => {
// Invalidate and refetch
queryClient.invalidateQueries({ queryKey: ['portfolio'] });
}
});
}
```
## State Management
### Component State
- Local component state with `useState`
- Form state management
- UI-only state (modals, tabs, etc.)
### Server State
- React Query for server state
- Automatic caching and synchronization
- Optimistic updates
### Global State
- Context API for theme, auth (if needed)
- Minimal global state - prefer server state
## Component Patterns
### Container/Presentational Pattern
```typescript
// Container component (handles data fetching)
function TradingPageContainer() {
const { data } = useQuery({ queryKey: ['orders'], queryFn: fetchOrders });
return <TradingPage orders={data} />;
}
// Presentational component (pure UI)
function TradingPage({ orders }) {
return (
<Box>
<OrdersTable orders={orders} />
</Box>
);
}
```
### Custom Hooks
Extract reusable logic into custom hooks:
```typescript
function useOrders() {
const { data, isLoading, error } = useQuery({
queryKey: ['orders'],
queryFn: () => tradingApi.getOrders()
});
const placeOrder = useMutation({
mutationFn: tradingApi.placeOrder
});
return { orders: data, isLoading, error, placeOrder };
}
```
## Error Handling
### API Errors
```typescript
try {
await tradingApi.placeOrder(order);
} catch (error) {
if (error.response?.status === 400) {
// Handle validation error
} else if (error.response?.status === 500) {
// Handle server error
}
}
```
### Error Boundaries
Use React Error Boundaries to catch and display errors gracefully:
```typescript
<ErrorBoundary fallback={<ErrorPage />}>
<TradingPage />
</ErrorBoundary>
```
## Performance Optimization
### Code Splitting
Use React.lazy for code splitting:
```typescript
const TradingPage = lazy(() => import('@/pages/TradingPage'));
<Suspense fallback={<Loading />}>
<TradingPage />
</Suspense>
```
### Memoization
Use React.memo, useMemo, and useCallback to prevent unnecessary re-renders:
```typescript
const MemoizedTable = React.memo(OrdersTable);
const filteredData = useMemo(() => {
return data.filter(/* ... */);
}, [data, filter]);
```
## Testing
See [Testing Guide](../developer/testing.md) for frontend testing strategies.
## Styling
- Material-UI components and theming
- Consistent design system
- Dark/light theme support
- Responsive design
## Accessibility
- Semantic HTML
- ARIA labels where needed
- Keyboard navigation
- Screen reader support