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**:
   ```bash
   cd backend
   python -m uvicorn main:app --reload --port 8000
   ```

2. **Start Frontend**:
   ```bash
   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**:
   ```bash
   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:

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

```yaml
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:

```yaml
volumes:
  - ./data:/app/data
```

## Development

### Backend Development

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   pip install -r backend/requirements.txt
   ```

2. Run with hot-reload:
   ```bash
   python -m uvicorn backend.main:app --reload
   ```

### Frontend Development

1. Install dependencies:
   ```bash
   cd frontend
   npm install
   ```

2. Run development server:
   ```bash
   npm run dev
   ```

3. Build for production:
   ```bash
   npm run build
   ```

## Production Deployment

### Docker Production

1. Build production image:
   ```bash
   docker build -t crypto-trader:latest .
   ```

2. Run container:
   ```bash
   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:

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