TCPDashboard/docs/architecture.md

# System Architecture

This document provides a high-level overview of the system architecture for the Crypto Trading Bot Platform.

## 1. Core Components

The platform consists of six core components designed to work together in a monolithic application structure. This design prioritizes rapid development and clear separation of concerns.

```
┌─────────────────────────────────────────────────────────────┐
│                   TCP Dashboard Platform                    │
│                                                             │
│  ┌──────────────────┐      ┌──────────────────┐     ┌──────────────────┐│
│  │   Data Collector  │────> │  Strategy Engine │────>│    Bot Manager   ││
│  │ (OKX, Binance...) │      │ (Signal Generation)│     │(State & Execution)││
│  └──────────────────┘      └──────────────────┘     └──────────────────┘│
│          │                          │                        │           │
│┌──────────────────┐      ┌──────────────────┐     ┌──────────────────┐│
││    Dashboard     │<──── │   Backtesting    │<────│     Database     ││
││ (Visualization)  │      │     Engine       │     │   (PostgreSQL)   ││
│└──────────────────┘      └──────────────────┘     └──────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

### 1. Data Collection Module
**Responsibility**: Collect real-time market data from exchanges
**Implementation**: `data/`
**Key Features**:
- Connects to exchange WebSocket APIs (OKX implemented)
- Aggregates raw trades into OHLCV candles
- Publishes data to Redis for real-time distribution
- Stores data in PostgreSQL for historical analysis
- See [Data Collectors Documentation (`modules/data_collectors.md`)](./modules/data_collectors.md) for details.

### 2. Strategy Engine
**Responsibility**: Unified interface for all trading strategies
**Status**: Not yet implemented. This section describes the planned architecture.

```python
class BaseStrategy:
    def __init__(self, parameters: dict):
        self.params = parameters
        
    def calculate(self, ohlcv_data: pd.DataFrame) -> Signal:
        raise NotImplementedError
        
    def get_indicators(self) -> dict:
        raise NotImplementedError
```

### 3. Bot Manager
**Responsibility**: Orchestrate bot execution and state management
**Status**: Not yet implemented. This section describes the planned architecture.

```python
class BotManager:
    def __init__(self):
        self.bots = {}

    def create_bot(self, config: dict) -> Bot:
        # ...
        
    def run_all_bots(self):
        # ...
```

### 4. Database
**Responsibility**: Data persistence and storage for market data, bot configurations, trading signals, and strategy analysis results.
**Implementation**: `database/`
**Key Features**:
- PostgreSQL with TimescaleDB extension for time-series data
- SQLAlchemy for ORM and schema management
- Alembic for database migrations
- Dedicated tables for strategy backtesting (e.g., `strategy_signals`, `strategy_runs`) separate from live trading `signals`.
- See [Database Operations Documentation (`modules/database_operations.md`)](./modules/database_operations.md) for details.

### 5. Backtesting Engine
**Responsibility**: Test strategies against historical data
**Status**: Not yet implemented. This section describes the planned architecture.

### 6. Dashboard
**Responsibility**: Visualization and user interaction
**Implementation**: `dashboard/`
**Key Features**:
- Dash-based web interface
- Real-time chart visualization with Plotly
- System health monitoring
- Bot management UI (planned)
- See the [Chart System Documentation (`modules/charts/`)](./modules/charts/) for details.

## 2. Data Flow

### Real-time Data Flow
1. **Data Collector** connects to exchange WebSocket (e.g., OKX).
2. Raw trades are aggregated into OHLCV candles (1m, 5m, etc.).
3. OHLCV data is published to a **Redis** channel.
4. **Strategy Engine** subscribes to Redis and receives OHLCV data.
5. Strategy generates a **Signal** (BUY/SELL/HOLD).
6. **Bot Manager** receives the signal and executes a virtual trade.
7. Trade details are stored in the **Database**.
8. **Dashboard** visualizes real-time data and bot activity.

### Backtesting Data Flow
1. **Backtesting Engine** queries historical OHLCV data from the **Database**.
2. Data is fed into the **Strategy Engine**.
3. Strategy generates signals, which are logged.
4. Performance metrics are calculated and stored.

## 3. Design Principles

- **Monolithic Architecture**: All components are part of a single application for simplicity.
- **Modular Design**: Components are loosely coupled to allow for future migration to microservices.
- **API-First**: Internal components communicate through well-defined interfaces.
- **Configuration-driven**: Bot and strategy parameters are managed via JSON files.

---
*Back to [Main Documentation (`README.md`)]*