# 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`