crypto_trader/docs/deployment/web_architecture.md

Web Architecture Deployment Guide

This guide covers deploying the new web-based architecture for Crypto Trader.

Overview

The application has been migrated from PyQt6 desktop app to a modern web-based architecture:

• Frontend: React + TypeScript + Material-UI
• Backend: FastAPI (Python)
• Deployment: Docker

Architecture

┌─────────────────────────────────────────┐
│         Web Browser (Client)            │
│  React + Material-UI + TypeScript        │
└─────────────────┬───────────────────────┘
                  │ HTTP/WebSocket
┌─────────────────▼───────────────────────┐
│      Python Backend API (FastAPI)       │
│  - Trading Engine (existing code)       │
│  - Strategy Framework (existing code)   │
│  - Portfolio Management (existing code) │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Database (SQLite/PostgreSQL)    │
└─────────────────────────────────────────┘

Quick Start

Development

1. Start Backend:

   cd backend
   python -m uvicorn main:app --reload --port 8000
   

2. Start Frontend:

   cd frontend
   npm install
   npm run dev
   

3. Access Application:

   • Frontend: http://localhost:3000
   • API Docs: http://localhost:8000/docs
   • API: http://localhost:8000/api

Docker Deployment

1. Build and Run:

   docker-compose up --build
   

2. Access Application:

   • Application: http://localhost:8000
   • API Docs: http://localhost:8000/docs

API Endpoints

Trading

• POST /api/trading/orders - Create order
• GET /api/trading/orders - List orders
• GET /api/trading/orders/{id} - Get order
• POST /api/trading/orders/{id}/cancel - Cancel order
• GET /api/trading/positions - Get positions
• GET /api/trading/balance - Get balance

Portfolio

• GET /api/portfolio/current - Get current portfolio
• GET /api/portfolio/history - Get portfolio history
• POST /api/portfolio/positions/update-prices - Update prices

Strategies

• GET /api/strategies/ - List strategies
• GET /api/strategies/available - List available strategy types
• POST /api/strategies/ - Create strategy
• GET /api/strategies/{id} - Get strategy
• PUT /api/strategies/{id} - Update strategy
• DELETE /api/strategies/{id} - Delete strategy
• POST /api/strategies/{id}/start - Start strategy
• POST /api/strategies/{id}/stop - Stop strategy

Backtesting

• POST /api/backtesting/run - Run backtest
• GET /api/backtesting/results/{id} - Get backtest results

Exchanges

• GET /api/exchanges/ - List exchanges
• GET /api/exchanges/{id} - Get exchange

WebSocket

• WS /ws/ - WebSocket connection for real-time updates

Configuration

Environment Variables

Create .env file:

# API Configuration
VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000/ws/

# Database (optional)
DATABASE_URL=sqlite:///./data/crypto_trader.db

Docker Environment

Environment variables can be set in docker-compose.yml:

environment:
  - DATABASE_URL=sqlite:///./data/crypto_trader.db
  - PYTHONPATH=/app

Data Persistence

Data is stored in the ./data directory, which is mounted as a volume in Docker:

volumes:
  - ./data:/app/data

Development

Backend Development

1. Install dependencies:

   pip install -r requirements.txt
   pip install -r backend/requirements.txt
   

2. Run with hot-reload:

   python -m uvicorn backend.main:app --reload
   

Frontend Development

1. Install dependencies:

   cd frontend
   npm install
   

2. Run development server:

   npm run dev
   

3. Build for production:

   npm run build
   

Production Deployment

Docker Production

1. Build production image:

   docker build -t crypto-trader:latest .
   

2. Run container:

   docker run -d \
     -p 8000:8000 \
     -v $(pwd)/data:/app/data \
     -v $(pwd)/config:/app/config \
     --name crypto-trader \
     crypto-trader:latest
   

Reverse Proxy (Nginx)

Example Nginx configuration:

server {
    listen 80;
    server_name crypto-trader.example.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws/ {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Migration from PyQt6

The existing Python code has been preserved:

• Trading engine (src/trading/)
• Strategy framework (src/strategies/)
• Portfolio tracker (src/portfolio/)
• Backtesting engine (src/backtesting/)
• All other core modules

Only the UI layer has been replaced with a web interface.

Troubleshooting

Backend Issues

• Port already in use: Change port in docker-compose.yml or use --port flag
• Database errors: Check database file permissions in ./data directory
• Import errors: Ensure PYTHONPATH=/app is set

Frontend Issues

• API connection errors: Check VITE_API_URL in .env file
• WebSocket connection fails: Verify WebSocket URL and backend is running
• Build errors: Clear node_modules and reinstall: rm -rf node_modules && npm install

Docker Issues

• Build fails: Check Dockerfile syntax and dependencies
• Container won't start: Check logs: docker-compose logs
• Volume permissions: Ensure ./data directory is writable

Benefits of Web Architecture

1. Modern UI: Access to entire web ecosystem (Material-UI, charts, etc.)
2. Cross-platform: Works on any device with a browser
3. Easier deployment: Docker is simpler than AppImage
4. Better development: Hot-reload, better tooling
5. Maintainability: Easier to update and deploy
6. Accessibility: Access from anywhere via browser

Next Steps

1. Add authentication (JWT tokens)
2. Implement WebSocket price updates
3. Add more charting capabilities
4. Enhance strategy management UI
5. Add mobile-responsive design