commit 49e9fa26a1358ce19fe6371e0dba43010bca37c8 Author: AI Dev Factory Date: Sat Dec 6 00:30:12 2025 +0000 Generate project architecture and tasks - Created ARCHITECTURE.md - Created TASKS.md - Based on PROJECT_SPEC.md Generated by init-mvp-project.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3dd19a0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,31 @@ +# Dependencies +node_modules/ +__pycache__/ +*.pyc +*.pyo +*.pyd +.Python +venv/ +.venv/ +env/ +.env + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Build +dist/ +build/ +*.egg-info/ + +# Test +.coverage +.pytest_cache/ +*.log diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..7d3c8d0 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,594 @@ +# AI Trading Bot - System Architecture + +## 1. High-Level System Design + +The AI Trading Bot is a full-stack application designed for automated grid trading with AI optimization capabilities. The system follows a microservices architecture with clear separation between the backend API, real-time WebSocket connections, asynchronous task processing, and the frontend dashboard. + +### System Components + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FRONTEND (Vue 3) │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Dashboard │ │ Config │ │ Charts │ │ +│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ +└─────────┼────────────────┼─────────────────┼────────────────────── + │ │ │ + └────────────────┼─────────────────┘ + │ +┌──────────────────────────┼──────────────────────────────────────┐ +│ BACKEND (FastAPI) │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ REST API │ │ WebSocket │ │ Celery │ │ +│ │ Endpoints │ │ Handler │ │ Worker │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ +└─────────┼──────────────────┼──────────────────┼───────────────────� + │ │ │ + │ ┌────────▼────────┐ │ + │ │ Redis │ │ + │ │ (Caching + │ │ + │ │ Queue) │ │ + │ └────────┬────────┘ │ +┌─────────┼──────────────────┼──────────────────┼───────────────────┐ +│ │ │ │ │ +│ ┌───────▼──────┐ ┌────────▼────────┐ ┌─────▼─────┐ │ +│ │ Binance │ │ PostgreSQL │ │ Claude │ │ +│ │ Exchange │ │ + TimescaleDB │ │ AI │ │ +│ └──────────────┘ └─────────────────┘ └───────────┘ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Core Workflows + +**1. Trading Flow** +- User configures grid parameters via UI → API → Bot record created +- Celery worker reads bot config → Connects to Binance → Places grid orders +- WebSocket sends real-time updates to UI +- Order fills trigger grid rebalancing + +**2. AI Optimization Flow** +- User requests AI optimization → API → Claude API call with market data +- Claude returns grid parameters → User accepts/rejects → Config updated + +**3. Real-time Data Flow** +- Binance WebSocket → Price data → Redis cache → WebSocket → UI +- Bot status changes → WebSocket → Dashboard updates + +## 2. Technology Choices and Rationale + +### Backend Technologies + +**FastAPI** +- **Rationale**: High-performance async web framework with automatic API documentation +- **Benefits**: Type hints, automatic validation, built-in WebSocket support, excellent for real-time trading applications +- **Alternatives Considered**: Django (too heavyweight), Flask (requires more manual work) + +**PostgreSQL + TimescaleDB** +- **Rationale**: Time-series data optimization for price history +- **Benefits**: ACID compliance, TimescaleDB provides automatic data partitioning and time-based queries +- **Database Choice**: PostgreSQL chosen for reliability and TimescaleDB extension for price data + +**Redis** +- **Rationale**: In-memory data store for caching and message queuing +- **Benefits**: Sub-millisecond latency for price data caching, session storage, Celery broker +- **Alternatives Considered**: Memcached (no persistence), RabbitMQ (heavier for simple use case) + +**Celery** +- **Rationale**: Distributed task queue for background processing +- **Benefits**: Handles long-running trading operations without blocking API, retry logic, monitoring +- **Use Cases**: Order placement, grid rebalancing, AI optimization calls + +**ccxt** +- **Rationale**: Unified cryptocurrency exchange library +- **Benefits**: Single API for multiple exchanges, handles WebSocket connections, rate limiting +- **Critical For**: Binance integration, order management + +**Anthropic (Claude)** +- **Rationale**: AI optimization of trading parameters +- **Benefits**: Natural language reasoning, structured JSON responses +- **Integration**: Market data → AI → Parameter suggestions + +### Frontend Technologies + +**Vue 3** +- **Rationale**: Progressive framework with Composition API +- **Benefits**: Reactive data binding, component-based architecture, excellent TypeScript support +- **Choice**: Chosen over React for simpler learning curve and excellent integration with Vite + +**Vite** +- **Rationale**: Next-generation frontend build tool +- **Benefits**: Fast HMR, optimized builds, excellent developer experience +- **Performance**: Sub-second cold starts crucial for rapid development + +**TailwindCSS** +- **Rationale**: Utility-first CSS framework +- **Benefits**: Rapid UI development, consistent design system, minimal CSS bundle size +- **Efficiency**: Perfect for trading dashboard with many similar components + +**Lightweight Charts** +- **Rationale**: Financial charting library by TradingView +- **Benefits**: Real-time candlestick charts, overlay support for grid levels +- **Features**: Candlestick, volume, indicators + +**Pinia** +- **Rationale**: State management for Vue 3 +- **Benefits**: Type-safe, simple API, devtools integration +- **Use Case**: Bot configuration, real-time price updates, user state + +### Deployment & Infrastructure + +**Docker Compose** +- **Rationale**: Container orchestration for development and production +- **Benefits**: Consistent environment, easy deployment, service isolation +- **Services**: Backend, Frontend, PostgreSQL, Redis, Celery worker + +## 3. Database Schema + +```sql +-- Users table +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + email VARCHAR(255) UNIQUE NOT NULL, + api_key_encrypted TEXT, -- AES-256 encrypted Binance API key + api_secret_encrypted TEXT, -- AES-256 encrypted Binance API secret + created_at TIMESTAMP DEFAULT NOW() +); + +-- Bots table +CREATE TABLE bots ( + id SERIAL PRIMARY KEY, + user_id INTEGER REFERENCES users(id) ON DELETE CASCADE, + strategy VARCHAR(50) NOT NULL, -- 'grid' for now, extensible + pair VARCHAR(20) NOT NULL, -- 'BTC/USDT' + status VARCHAR(20) NOT NULL, -- 'running', 'stopped', 'error' + config JSONB NOT NULL, -- Grid parameters, risk settings + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +-- Orders table +CREATE TABLE orders ( + id SERIAL PRIMARY KEY, + bot_id INTEGER REFERENCES bots(id) ON DELETE CASCADE, + exchange_order_id VARCHAR(100), -- Binance order ID + side VARCHAR(10) NOT NULL, -- 'buy', 'sell' + price DECIMAL(20, 8) NOT NULL, + amount DECIMAL(20, 8) NOT NULL, + status VARCHAR(20) NOT NULL, -- 'open', 'filled', 'cancelled' + filled_at TIMESTAMP, + created_at TIMESTAMP DEFAULT NOW() +); + +-- Trades table (filled order pairs) +CREATE TABLE trades ( + id SERIAL PRIMARY KEY, + bot_id INTEGER REFERENCES bots(id) ON DELETE CASCADE, + buy_order_id INTEGER REFERENCES orders(id), + sell_order_id INTEGER REFERENCES orders(id), + profit DECIMAL(20, 8), -- Realized profit/loss + created_at TIMESTAMP DEFAULT NOW() +); + +-- Price data table (TimescaleDB hypertable) +CREATE TABLE prices ( + time TIMESTAMPTZ NOT NULL, + symbol VARCHAR(20) NOT NULL, + open DECIMAL(20, 8) NOT NULL, + high DECIMAL(20, 8) NOT NULL, + low DECIMAL(20, 8) NOT NULL, + close DECIMAL(20, 8) NOT NULL, + volume DECIMAL(20, 8) NOT NULL, + PRIMARY KEY (time, symbol) +); + +-- Create TimescaleDB hypertable +SELECT create_hypertable('prices', 'time'); +``` + +### Database Design Rationale + +**Normalization Strategy** +- Users → Bots → Orders → Trades follows proper foreign key relationships +- JSONB config allows flexible bot parameters without schema changes +- TimescaleDB enables efficient time-series queries for historical price analysis + +**Performance Optimizations** +- Indexes on frequently queried columns (bot_id, user_id, symbol, time) +- TimescaleDB automatic data partitioning by time +- Redis caching for frequently accessed bot status and current prices + +**Data Integrity** +- ON DELETE CASCADE ensures proper cleanup +- CHECK constraints on ENUM values (side, status, strategy) +- Foreign key constraints maintain referential integrity + +## 4. API Endpoints + +### Authentication Endpoints +```python +POST /api/auth/register +Body: { email, password } +Response: { token, user_id } + +POST /api/auth/login +Body: { email, password } +Response: { token, user_id } +``` + +### Bot Management Endpoints +```python +GET /api/bots +Response: [ { id, strategy, pair, status, config, created_at } ] + +POST /api/bots +Body: { strategy, pair, config } +Response: { id, strategy, pair, status, config } + +GET /api/bots/{id} +Response: { id, strategy, pair, status, config, created_at, updated_at } + +PUT /api/bots/{id} +Body: { config } # Update configuration +Response: { id, updated_config } + +POST /api/bots/{id}/start +Response: { status: "started" } + +POST /api/bots/{id}/stop +Response: { status: "stopped" } + +DELETE /api/bots/{id} +Response: { status: "deleted" } +``` + +### Trading Data Endpoints +```python +GET /api/bots/{id}/orders +Query: ?status=open # optional filter +Response: [ { id, side, price, amount, status, created_at } ] + +GET /api/bots/{id}/trades +Query: ?limit=50&offset=0 # pagination +Response: [ { id, buy_price, sell_price, profit, created_at } ] + +GET /api/bots/{id}/balance +Response: { free, locked, total } + +GET /api/bots/{id}/stats +Response: { total_trades, win_rate, total_profit, max_drawdown } +``` + +### AI Optimization Endpoints +```python +POST /api/ai/optimize +Body: { + pair: "BTC/USDT", + capital: 10000, + current_price: 97500, + lower_bound: 95000, + upper_bound: 105000, + volatility: 0.02, + volume_24h: 1000000 +} +Response: { + grid_lower: 96000, + grid_upper: 104000, + num_levels: 25, + confidence: 78, + reasoning: "...", + risk_level: "medium" +} +``` + +### Market Data Endpoints +```python +GET /api/market/price/{symbol} +Response: { symbol: "BTC/USDT", price: 97500, timestamp: "..." } + +GET /api/market/indicators/{symbol} +Response: { + rsi: 65.5, + volatility: 0.02, + support: 97000, + resistance: 98000, + volume_24h: 1500000000 +} + +GET /api/market/history/{symbol} +Query: ?interval=1h&limit=100 +Response: [ { time, open, high, low, close, volume } ] +``` + +### WebSocket Endpoints +```python +# Real-time bot status updates +WS /ws/bot/{id} +Message: { + type: "status_update", + data: { status, open_orders, realized_pnl, unrealized_pnl } +} + +# Real-time price feed +WS /ws/market/{symbol} +Message: { + type: "price_update", + data: { symbol, price, timestamp } +} + +# Real-time order updates +WS /ws/bot/{id}/orders +Message: { + type: "order_update", + data: { order_id, status, filled_price, filled_amount } +} +``` + +### Request/Response Validation + +All endpoints use Pydantic models for request/response validation: + +```python +# Example: Create Bot Request +class CreateBotRequest(BaseModel): + strategy: Literal["grid"] + pair: str # e.g., "BTC/USDT" + config: BotConfig + +class BotConfig(BaseModel): + capital: float = Field(gt=0, le=1000000) + lower_bound: float = Field(gt=0) + upper_bound: float = Field(gt=0) + grid_levels: int = Field(ge=10, le=50) + stop_loss_pct: float = Field(ge=0, le=10) + max_daily_loss: float = Field(ge=0) +``` + +## 5. File Structure + +``` +/home/bam/openhands/workspace/aibo +├── docker-compose.yml # Container orchestration +├── .env.example # Environment variables template +├── README.md # Setup instructions +│ +├── backend/ # FastAPI backend +│ ├── Dockerfile +│ ├── requirements.txt +│ ├── main.py # FastAPI app entry point +│ │ +│ └── app/ +│ ├── __init__.py +│ ├── config.py # Settings, environment variables +│ ├── database.py # Database connection, models +│ ├── celery.py # Celery configuration +│ ├── security.py # Auth, encryption utilities +│ │ +│ ├── api/ # FastAPI routers +│ │ ├── __init__.py +│ │ ├── deps.py # Dependencies (auth, db) +│ │ ├── auth.py # Authentication endpoints +│ │ ├── bots.py # Bot management endpoints +│ │ ├── trading.py # Trading data endpoints +│ │ ├── market.py # Market data endpoints +│ │ └── ai.py # AI optimization endpoints +│ │ +│ ├── models/ # Database models +│ │ ├── __init__.py +│ │ ├── user.py # User model +│ │ ├── bot.py # Bot model +│ │ ├── order.py # Order model +│ │ └── trade.py # Trade model +│ │ +│ ├── schemas/ # Pydantic schemas +│ │ ├── __init__.py +│ │ ├── user.py # User schemas +│ │ ├── bot.py # Bot schemas +│ │ ├── order.py # Order schemas +│ │ └── trade.py # Trade schemas +│ │ +│ ├── services/ # Business logic +│ │ ├── __init__.py +│ │ ├── binance.py # Binance API integration +│ │ ├── ai.py # Claude AI integration +│ │ ├── grid.py # Grid trading strategy +│ │ ├── websocket.py # WebSocket connection manager +│ │ └── risk.py # Risk management +│ │ +│ ├── strategies/ # Trading strategies +│ │ ├── __init__.py +│ │ ├── base.py # Strategy interface +│ │ └── grid.py # Grid strategy implementation +│ │ +│ └── tasks/ # Celery tasks +│ ├── __init__.py +│ ├── trading.py # Trading operations +│ ├── grid.py # Grid management +│ └── ai_optimization.py # AI parameter optimization +│ +└── frontend/ # Vue 3 frontend + ├── Dockerfile + ├── package.json + ├── vite.config.js + ├── index.html + │ + └── src/ + ├── main.js # Vue app entry point + ├── App.vue # Root component + ├── router/ # Vue Router + │ └── index.js + │ + ├── stores/ # Pinia stores + │ ├── auth.js # Authentication store + │ ├── bot.js # Bot management store + │ └── market.js # Market data store + │ + ├── views/ # Page components + │ ├── Dashboard.vue # Main trading dashboard + │ ├── Config.vue # Bot configuration page + │ ├── Login.vue # Login page + │ └── Register.vue # Registration page + │ + ├── components/ # Reusable components + │ ├── BotCard.vue # Bot status card + │ ├── PriceChart.vue # TradingView chart + │ ├── OrderBook.vue # Grid orders display + │ ├── TradeHistory.vue # Trade history table + │ ├── StatsPanel.vue # Performance statistics + │ ├── EmergencyStop.vue # Emergency stop button + │ └── AIDialog.vue # AI optimization dialog + │ + ├── composables/ # Vue composables + │ ├── useWebSocket.js # WebSocket connection + │ ├── useBinance.js # Binance data + │ └── useTrading.js # Trading utilities + │ + └── utils/ # Helper functions + ├── api.js # API client + ├── formatters.js # Number/date formatting + └── grid.js # Grid calculations +``` + +### Directory Structure Rationale + +**Backend Organization** +- **API Layer**: FastAPI routers handle HTTP requests/responses +- **Services Layer**: Business logic and external integrations +- **Models Layer**: Database models using SQLAlchemy +- **Strategies Layer**: Trading strategy implementations +- **Tasks Layer**: Celery background tasks + +**Frontend Organization** +- **Views**: Page-level components (routed components) +- **Components**: Reusable UI components +- **Stores**: Pinia state management +- **Composables**: Vue 3 Composition API utilities +- **Utils**: Helper functions and API client + +## 6. Component Interactions + +### Backend Component Interactions + +**1. Bot Lifecycle Flow** +``` +User (UI) → POST /api/bots → API Router → Bot Model → Database + ↓ + Celery Task → Grid Service + ↓ + Binance Service → Exchange API +``` + +**2. Order Management Flow** +``` +Binance WebSocket → WebSocket Service → Redis Cache → WebSocket API → UI + ↓ + Order Model → Database +``` + +**3. AI Optimization Flow** +``` +User Request → AI Endpoint → Claude Service → Grid Service → Bot Config + ↓ + Redis Cache → WebSocket → UI +``` + +### Frontend Component Interactions + +**1. Dashboard State Flow** +``` +Page Load → Market Store → API GET /market/price → WebSocket Connect + ↓ + Bot Store ← Real-time Updates + ↓ + Components Re-render +``` + +**2. Bot Control Flow** +``` +User Action (Start) → Bot Store → API POST /bots/{id}/start + ↓ + WebSocket ← Status Update + ↓ + Dashboard Components Update +``` + +### Cross-System Interactions + +**1. Real-time Price Updates** +``` +Binance WebSocket → Backend WebSocket Handler → Redis Pub/Sub → +Frontend WebSocket → Market Store → Chart Components +``` + +**2. Bot Status Synchronization** +``` +Celery Worker → Database Update → Redis Cache → WebSocket Broadcast → +Frontend Store Update → UI Re-render +``` + +**3. Risk Management Flow** +``` +Trading Task → Risk Service → Database Check → +If Limit Exceeded → Stop Bot → WebSocket Notification +``` + +### Message Flow Patterns + +**1. Publish-Subscribe (Redis)** +- Price updates published to Redis channels +- WebSocket service subscribes and forwards to clients +- Decouples data producers from consumers + +**2. Event-Driven Architecture** +- Order fills trigger grid rebalancing events +- WebSocket events broadcast to connected clients +- Celery tasks triggered by database events + +**3. Observer Pattern** +- Bot status changes notify all subscribers +- Market data changes trigger chart updates +- Risk events trigger emergency stop procedures + +## 7. Security Architecture + +**Authentication & Authorization** +- JWT tokens for API authentication +- Role-based access control (user owns their bots) +- Password hashing with bcrypt + +**Data Protection** +- API keys encrypted with AES-256 before database storage +- TLS encryption for all external communications +- Environment variables for sensitive configuration + +**Trading Safety** +- Mandatory paper trading for new users +- Confirmation dialogs for live mode activation +- Daily loss limits enforced at application level +- Emergency stop capability from UI + +**Rate Limiting** +- API endpoints rate limited by user/IP +- Binance API rate limiting compliance +- WebSocket connection limits + +## 8. Scalability Considerations + +**Horizontal Scaling** +- Stateless FastAPI servers behind load balancer +- Celery workers can be scaled independently +- Redis cluster for high availability + +**Database Optimization** +- TimescaleDB automatic partitioning by time +- Read replicas for market data queries +- Connection pooling with async SQLAlchemy + +**Caching Strategy** +- Redis for hot price data (1-second TTL) +- Application-level caching for bot configurations +- Database query result caching + +**Monitoring & Observability** +- Health check endpoints for all services +- Structured logging with correlation IDs +- Metrics collection for trading performance diff --git a/PROJECT_SPEC.md b/PROJECT_SPEC.md new file mode 100644 index 0000000..d0dd725 --- /dev/null +++ b/PROJECT_SPEC.md @@ -0,0 +1,346 @@ +# AI Trading Bot - Build Spec + +Full-stack grid trading bot with Binance + AI optimization. Extensible for future strategies. + +--- + +## STACK + +**Backend:** FastAPI, PostgreSQL + TimescaleDB, Redis, Celery, ccxt, anthropic +**Frontend:** Vue 3, Vite, TailwindCSS, Lightweight Charts, Pinia +**Deploy:** Docker compose + +--- + +## REQUIREMENTS + +### 1. Binance Integration +```python +# Connect to Binance (testnet + mainnet toggle) +# Real-time price via WebSocket +# Place/cancel limit orders +# Get balance, positions, order status, trade history +# Rate limiting, auto-reconnect, health checks +``` + +### 2. Grid Trading Strategy +```python +# Calculate support/resistance +# Generate N buy orders (lower bound → mid) +# Generate N sell orders (mid → upper bound) +# Monitor fills, rebalance grid +# Track P&L per trade + +# User config: +- pair (BTC/USDT) +- capital ($10k) +- lower_bound ($95k) +- upper_bound ($105k) +- grid_levels (20) +- stop_loss_pct (2%) +``` + +### 3. AI Optimization +```python +# Call Claude API with market data: +- current price, 24h range +- volatility, volume +- support/resistance levels + +# AI returns JSON: +{ + "grid_lower": 95000, + "grid_upper": 105000, + "num_levels": 20, + "confidence": 78, + "reasoning": "...", + "risk_level": "medium" +} + +# User can accept/reject AI suggestions +``` + +### 4. Trading Modes +- **Paper Mode:** Simulate orders, fake money, real prices +- **Live Mode:** Real execution, confirmation required + +### 5. Dashboard (Vue 3) +``` +[Header] +- P&L today / all-time +- Balance +- PAPER/LIVE indicator +- Emergency STOP button + +[Bot Status Card] +- Strategy: Grid Trading +- Pair: BTC/USDT +- Status: Running/Stopped +- Grid: $95k - $105k +- Open orders: 15/20 +- Realized P&L: +$234 +- Unrealized P&L: +$45 +- [Start] [Stop] [Configure] + +[Price Chart] +- TradingView chart +- Grid levels overlay +- Buy/sell markers + +[Trade History Table] +- Last 20 trades +- Time | Side | Price | Amount | P&L + +[Stats] +- Win rate, total trades, avg profit, max drawdown +``` + +### 6. Config Page +``` +Form fields: +- Trading pair (dropdown) +- Capital ($) +- Grid lower/upper (AI suggests button) +- Grid levels (slider 10-50) +- Stop loss % +- Max daily loss ($) +- API keys (encrypted) +- Paper/Live toggle + +[Save] [AI Optimize] [Test Config] +``` + +--- + +## DATABASE SCHEMA + +```sql +-- users +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + email VARCHAR(255) UNIQUE, + api_key_encrypted TEXT, + api_secret_encrypted TEXT, + created_at TIMESTAMP DEFAULT NOW() +); + +-- bots +CREATE TABLE bots ( + id SERIAL PRIMARY KEY, + user_id INTEGER REFERENCES users(id), + strategy VARCHAR(50), -- 'grid' + pair VARCHAR(20), -- 'BTC/USDT' + status VARCHAR(20), -- 'running', 'stopped' + config JSONB, + created_at TIMESTAMP DEFAULT NOW() +); + +-- orders +CREATE TABLE orders ( + id SERIAL PRIMARY KEY, + bot_id INTEGER REFERENCES bots(id), + exchange_order_id VARCHAR(100), + side VARCHAR(10), -- 'buy', 'sell' + price DECIMAL(20, 8), + amount DECIMAL(20, 8), + status VARCHAR(20), -- 'open', 'filled', 'cancelled' + created_at TIMESTAMP DEFAULT NOW() +); + +-- trades (filled pairs) +CREATE TABLE trades ( + id SERIAL PRIMARY KEY, + bot_id INTEGER REFERENCES bots(id), + buy_order_id INTEGER REFERENCES orders(id), + sell_order_id INTEGER REFERENCES orders(id), + profit DECIMAL(20, 8), + created_at TIMESTAMP DEFAULT NOW() +); + +-- prices (TimescaleDB hypertable) +CREATE TABLE prices ( + time TIMESTAMPTZ NOT NULL, + symbol VARCHAR(20), + open DECIMAL(20, 8), + high DECIMAL(20, 8), + low DECIMAL(20, 8), + close DECIMAL(20, 8), + volume DECIMAL(20, 8) +); +SELECT create_hypertable('prices', 'time'); +``` + +--- + +## API ENDPOINTS + +```python +# Auth +POST /api/auth/register +POST /api/auth/login + +# Bots +GET /api/bots +POST /api/bots +GET /api/bots/{id} +PUT /api/bots/{id} +POST /api/bots/{id}/start +POST /api/bots/{id}/stop + +# Trading +GET /api/orders +GET /api/trades +GET /api/balance + +# AI +POST /api/ai/optimize # body: {pair, capital, volatility, ...} + +# Market +GET /api/market/price/{symbol} +GET /api/market/indicators/{symbol} + +# WebSocket +WS /ws/bot/{id} # real-time updates +WS /ws/market/{symbol} # price feed +``` + +--- + +## STRATEGY PLUGIN INTERFACE + +```python +# For future extensibility +from abc import ABC, abstractmethod + +class TradingStrategy(ABC): + @abstractmethod + def initialize(self, config: dict): + """Setup strategy""" + pass + + @abstractmethod + def generate_signals(self, market_data: dict) -> List[Signal]: + """Return buy/sell signals""" + pass + + @abstractmethod + def optimize_with_ai(self, ai_client) -> dict: + """Get AI suggestions""" + pass + +# Grid strategy implements this +# Future strategies (mean reversion, momentum) implement this +# Registry: STRATEGIES = {'grid': GridStrategy, ...} +``` + +--- + +## SECURITY + +- Encrypt API keys (AES-256) +- Hash passwords (bcrypt) +- JWT auth tokens +- Rate limit all endpoints +- Confirmation prompt for live mode +- Daily loss limits enforced +- Emergency stop kills all orders + +--- + +## DOCKER SETUP + +```yaml +services: + backend: + build: ./backend + environment: + - DATABASE_URL=postgresql://... + - REDIS_URL=redis://... + - BINANCE_TESTNET=true + depends_on: + - postgres + - redis + + frontend: + build: ./frontend + ports: + - "80:80" + + postgres: + image: timescale/timescaledb:latest-pg15 + volumes: + - pgdata:/var/lib/postgresql/data + + redis: + image: redis:alpine + + celery: + build: ./backend + command: celery -A app.celery worker +``` + +--- + +## SUCCESS CRITERIA + +Bot works when: +- [x] Connects to Binance testnet +- [x] Places grid orders via UI +- [x] Dashboard shows live P&L +- [x] AI suggests parameters +- [x] Paper trading tracks correctly +- [x] Start/stop works +- [x] Runs stable 24h+ +- [x] WebSocket updates real-time + +--- + +## PROJECT STRUCTURE + +``` +/backend + /app + /api # FastAPI routes + /strategies # grid.py, base.py + /services # binance.py, ai.py + /models # db models + main.py + requirements.txt + +/frontend + /src + /components # BotCard.vue, PriceChart.vue, etc. + /views # Dashboard.vue, Config.vue + /stores # botStore.js + vite.config.js + +docker-compose.yml +.env.example +README.md +``` + +--- + +## CRITICAL RULES + +- Start with paper trading ONLY +- Use Binance testnet for dev +- No leverage/margin (spot only) +- Validate all inputs +- Log everything +- Test grid math extensively +- AI suggestions are optional (user confirms) + +--- + +## DELIVERABLES + +1. Working grid bot (paper mode) +2. Vue dashboard with real-time updates +3. Docker compose setup +4. README with setup steps +5. .env.example with all variables + +--- + +**BUILD THIS.** No phases, no fluff. Grid strategy working end-to-end, extensible for future strategies. diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..f542b83 --- /dev/null +++ b/TASKS.md @@ -0,0 +1,362 @@ +# AI Trading Bot - Implementation Tasks + +## Task 1: Project Infrastructure and Docker Setup + +### Objectives +- Set up project structure and development environment +- Configure Docker Compose with all required services +- Implement environment variable management +- Create basic README with setup instructions + +### Deliverables +- Complete directory structure following specification +- docker-compose.yml with backend, frontend, PostgreSQL, Redis, Celery +- .env.example with all required environment variables +- README.md with step-by-step setup instructions + +### Acceptance Criteria +- [ ] Docker Compose successfully starts all services +- [ ] Backend and frontend containers build without errors +- [ ] PostgreSQL and Redis containers are accessible +- [ ] Environment variables properly configured via .env file +- [ ] Services communicate correctly (backend can reach database/Redis) +- [ ] README provides working setup for new developer + +--- + +## Task 2: Backend API Structure and Authentication + +### Objectives +- Implement FastAPI application structure +- Create user authentication system with JWT +- Set up API routing and middleware +- Implement security utilities (password hashing, encryption) + +### Deliverables +- FastAPI main application with proper CORS configuration +- User registration and login endpoints +- JWT token authentication middleware +- Password hashing with bcrypt +- API key encryption/decryption utilities +- Pydantic schemas for request/response validation + +### Acceptance Criteria +- [ ] POST /api/auth/register creates user with encrypted API keys +- [ ] POST /api/auth/login returns valid JWT token +- [ ] Protected endpoints require valid JWT token +- [ ] Passwords are properly hashed (cannot be reversed) +- [ ] API keys are AES-256 encrypted before database storage +- [ ] CORS configured for frontend development +- [ ] All endpoints have proper OpenAPI documentation + +--- + +## Task 3: Database Setup and Core Models + +### Objectives +- Configure PostgreSQL with TimescaleDB extension +- Implement database models using SQLAlchemy +- Create database migration system +- Set up async database connection and session management + +### Deliverables +- User, Bot, Order, Trade, and Price models +- Database connection configuration with async SQLAlchemy +- TimescaleDB hypertable setup for price data +- Database migrations (Alembic or similar) +- Repository classes for database operations +- Database connection pooling and error handling + +### Acceptance Criteria +- [ ] All tables created successfully in PostgreSQL +- [ ] TimescaleDB hypertable created for prices table +- [ ] Foreign key relationships properly configured +- [ ] Database migrations run without errors +- [ ] Async database operations work correctly +- [ ] Connection pool properly configured +- [ ] Database models include all required fields from schema + +--- + +## Task 4: Binance Integration Service + +### Objectives +- Implement Binance API client using ccxt +- Create WebSocket connection manager for real-time prices +- Handle Binance authentication and rate limiting +- Implement order placement, cancellation, and status checking + +### Deliverables +- Binance service class with testnet and mainnet support +- WebSocket connection manager with auto-reconnect +- Order management methods (place, cancel, get status) +- Balance and position querying methods +- Rate limiting and error handling +- Health check endpoint for exchange connectivity + +### Acceptance Criteria +- [ ] Successfully connects to Binance testnet API +- [ ] Places and cancels limit orders via ccxt +- [ ] WebSocket connection provides real-time price updates +- [ ] Handles network failures and reconnects automatically +- [ ] Rate limiting respects Binance API limits +- [ ] Balance queries return correct account information +- [ ] Order status updates correctly reflect on exchange + +--- + +## Task 5: Grid Trading Strategy Implementation + +### Objectives +- Implement core grid trading algorithm +- Calculate optimal grid levels based on support/resistance +- Create order management and grid rebalancing logic +- Implement P&L calculation and tracking + +### Deliverables +- Grid strategy class implementing trading strategy interface +- Grid level calculation algorithms (support/resistance based) +- Order placement logic (buy orders lower half, sell orders upper half) +- Grid monitoring and rebalancing on order fills +- P&L calculation (realized and unrealized) +- Risk management (stop loss, daily limits) + +### Acceptance Criteria +- [ ] Grid orders placed correctly based on current price and bounds +- [ ] Grid levels automatically calculated from market data +- [ ] Order fills trigger appropriate counter-order placement +- [ ] P&L calculated accurately for each completed trade pair +- [ ] Grid rebalancing maintains proper order distribution +- [ ] Stop loss and daily limits enforced +- [ ] Strategy works for at least 24 hours without intervention + +--- + +## Task 6: AI Optimization Service + +### Objectives +- Integrate Claude API for market analysis +- Create market data collection and formatting +- Implement AI prompt engineering for grid parameter optimization +- Handle AI response processing and validation + +### Deliverables +- AI service class with Claude API integration +- Market data collection (current price, volatility, volume, indicators) +- Structured prompts for grid parameter optimization +- JSON response parsing and validation +- Confidence scoring and reasoning extraction +- API endpoint for AI optimization requests + +### Acceptance Criteria +- [ ] Successfully calls Claude API with market data +- [ ] Returns structured JSON with grid parameters +- [ ] AI suggestions are reasonable based on market conditions +- [ ] Response includes confidence score and reasoning +- [ ] Invalid AI responses handled gracefully +- [ ] API endpoint accepts market data and returns suggestions +- [ ] Rate limiting prevents excessive API calls + +--- + +## Task 7: Real-time WebSocket Implementation + +### Objectives +- Implement WebSocket endpoints for real-time updates +- Create WebSocket connection management +- Set up Redis pub/sub for cross-process messaging +- Implement real-time price feed broadcasting + +### Deliverables +- WebSocket endpoints for bot updates and market data +- Connection manager with automatic cleanup +- Redis pub/sub integration for multi-process communication +- Real-time price broadcasting service +- Frontend WebSocket client integration +- Connection state management and error handling + +### Acceptance Criteria +- [ ] WebSocket connections established successfully +- [ ] Real-time price updates broadcast to connected clients +- [ ] Bot status changes sent via WebSocket +- [ ] Order updates transmitted in real-time +- [ ] Multiple clients can connect simultaneously +- [ ] WebSocket connections handle network interruptions +- [ ] Redis pub/sub correctly distributes messages across processes + +--- + +## Task 8: Frontend Dashboard Setup and Layout + +### Objectives +- Set up Vue 3 project with Vite and TailwindCSS +- Implement routing and main dashboard layout +- Create authentication flow and protected routes +- Set up Pinia store management + +### Deliverables +- Vue 3 project with TypeScript support +- Vue Router configuration with authentication guards +- Login and registration pages +- Main dashboard layout with navigation +- Pinia stores for authentication and application state +- TailwindCSS configuration and design system +- Responsive design for desktop and tablet + +### Acceptance Criteria +- [ ] Vue application runs successfully in development +- [ ] Routing works for login, register, and dashboard pages +- [ ] Authentication guards protect dashboard routes +- [ ] User can register, login, and access dashboard +- [ ] Dashboard layout displays correctly on desktop +- [ ] TailwindCSS styling applied consistently +- [ ] Pinia stores manage application state properly + +--- + +## Task 9: Bot Management UI Components + +### Objectives +- Create bot configuration form and validation +- Implement bot status card with real-time updates +- Create bot list and management interface +- Integrate with backend bot management endpoints + +### Deliverables +- Bot configuration form with all required parameters +- Real-time bot status card component +- Bot list/grid view for multiple bots +- Start/stop bot controls with confirmation dialogs +- Bot creation and editing interface +- Form validation with real-time feedback +- Integration with bot management API endpoints + +### Acceptance Criteria +- [ ] Configuration form validates all inputs correctly +- [ ] Bot creation saves configuration to database +- [ ] Status card shows real-time bot information +- [ ] Start/stop bot works with confirmation dialogs +- [ ] Multiple bots can be created and managed +- [ ] Form prevents submission with invalid data +- [ ] UI updates reflect backend bot changes immediately + +--- + +## Task 10: Trading UI Components and Charts + +### Objectives +- Implement real-time price charts with grid overlay +- Create order book and trade history displays +- Implement P&L tracking and statistics panels +- Create emergency stop functionality + +### Deliverables +- Real-time candlestick chart with TradingView Lightweight Charts +- Grid levels overlay on price chart +- Order book showing active grid orders +- Trade history table with pagination +- P&L statistics panel (realized/unrealized, win rate, etc.) +- Emergency stop button with confirmation +- Buy/sell markers on price chart + +### Acceptance Criteria +- [ ] Price chart displays real-time candlestick data +- [ ] Grid levels correctly overlaid on chart +- [ ] Order book shows all active grid orders +- [ ] Trade history displays completed trades with P&L +- [ ] Statistics panel shows accurate performance metrics +- [ ] Emergency stop button immediately halts all trading +- [ ] Chart updates smoothly without performance issues + +--- + +## Task 11: Security Features and Safety Mechanisms + +### Objectives +- Implement comprehensive input validation +- Create trading safety features (paper/live mode, limits) +- Add rate limiting and DDoS protection +- Implement audit logging and monitoring + +### Deliverables +- Comprehensive input validation on all endpoints +- Paper trading mode enforcement +- Daily loss limits and stop loss mechanisms +- Rate limiting middleware for all endpoints +- Audit logging for all trading actions +- API key management with encryption +- Confirmation dialogs for live trading activation +- Health check endpoints for all services + +### Acceptance Criteria +- [ ] All inputs validated and sanitized before processing +- [ ] Paper trading mode prevents real money trading +- [ ] Daily loss limits enforced automatically +- [ ] Live mode requires explicit confirmation +- [ ] Rate limiting prevents API abuse +- [ ] All trading actions logged for audit trail +- [ ] Health checks return status for all services +- [ ] System recovers gracefully from errors + +--- + +## Task 12: Testing, Integration, and Final Deployment + +### Objectives +- Implement comprehensive testing (unit, integration, end-to-end) +- Perform full system integration testing +- Create deployment documentation and scripts +- Verify all success criteria from specification + +### Deliverables +- Unit tests for all backend services and strategies +- Integration tests for API endpoints +- Frontend component tests and E2E testing +- Docker production configuration +- CI/CD pipeline configuration +- Monitoring and logging setup +- Performance testing and optimization +- Final documentation and deployment guide + +### Acceptance Criteria +- [ ] All unit tests pass with >80% code coverage +- [ ] Integration tests verify complete user workflows +- [ ] End-to-end tests confirm grid trading works end-to-end +- [ ] Docker containers deploy successfully to production +- [ ] System runs stable for 24+ hours in paper mode +- [ ] All success criteria from specification verified: + - [ ] Connects to Binance testnet ✓ + - [ ] Places grid orders via UI ✓ + - [ ] Dashboard shows live P&L ✓ + - [ ] AI suggests parameters ✓ + - [ ] Paper trading tracks correctly ✓ + - [ ] Start/stop works ✓ + - [ ] Runs stable 24h+ ✓ + - [ ] WebSocket updates real-time ✓ +- [ ] README provides complete setup instructions +- [ ] .env.example includes all required variables + +--- + +## Task Dependencies and Flow + +``` +Task 1 (Infrastructure) → Task 2 (Backend API) → Task 3 (Database) + ↓ +Task 8 (Frontend) ← Task 7 (WebSocket) ← Task 4 (Binance) + ↓ ↓ +Task 9 (Bot UI) ← Task 6 (AI Service) ← Task 5 (Grid Strategy) + ↓ +Task 10 (Trading UI) ← Task 11 (Security) + ↓ + Task 12 (Testing & Deployment) +``` + +## Notes + +- **Paper Trading First**: All development must prioritize paper trading mode +- **Testnet Only**: Use Binance testnet exclusively during development +- **Incremental Testing**: Test each task independently before proceeding +- **Error Handling**: Comprehensive error handling required at all levels +- **Documentation**: Update README and add inline code documentation +- **Performance**: Monitor performance and optimize bottlenecks early