# Web UI Setup Guide

This guide covers setting up and running the Hyperliquid Trading Bot Web UI (Phase 1 implementation).

## 🚀 Quick Start

### 1. Install Dependencies

The web UI requires additional FastAPI dependencies that have been added to `pyproject.toml`:

```bash
# If using uv
uv install

# If using pip
pip install -e .
```

### 2. Configure Environment

Add the following web UI settings to your `.env` file:

```bash
# Web UI Configuration
WEB_ENABLED=true
WEB_HOST=127.0.0.1
WEB_PORT=8080
WEB_API_KEY=your_secure_api_key_here
WEB_CORS_ORIGINS=http://localhost:8080,http://127.0.0.1:8080
```

**Important**: Generate a secure API key for `WEB_API_KEY`. This will be used for authentication.

### 3. Start the Web Server

Run the web server alongside your existing Telegram bot:

```bash
python web_start.py
```

The web UI will be available at: `http://127.0.0.1:8080`

## 📊 Dashboard Features (Phase 1)

### Current Implementation

✅ **Account Summary**
- Account balance
- Total P&L and return percentage
- Win rate and profit factor
- Open positions count
- Max drawdown

✅ **Live Positions**
- Open positions with real-time P&L
- Entry price, mark price, leverage
- Side (long/short) indicators

✅ **Recent Trades**
- Last 10 completed trades
- P&L and ROE for each trade
- Trade timestamps

✅ **Market Overview**
- Real-time prices for major tokens (BTC, ETH, SOL, DOGE)
- 24-hour change percentages

✅ **Responsive Design**
- Mobile-friendly interface
- Tailwind CSS styling
- Auto-refresh functionality

### Authentication

The web UI uses simple Bearer token authentication with the API key you configure. Enter your API key in the dashboard to access the data.

### Copy Trading Tab Features

The copy trading tab provides comprehensive functionality including:

#### 4. Enhanced Account Analysis (NEW)
- **Clickable Analysis Results**: All account addresses in analysis results and leaderboard are now clickable
- **Deep Dive Analysis**: Click any address to open a detailed analysis modal showing:
  - **Account Overview**: Address, analysis period, last trade, trading type
  - **Score & Recommendation**: 0-100 relative score with color-coded recommendation
  - **Current Positions**: Real-time positions with P&L, leverage, and position details
  - **Performance Metrics**: Total P&L, win rate, trades, duration, drawdown, profit factor
  - **Trading Patterns**: Frequency, leverage usage, token diversity, directional capability
  - **Trading Style**: Pattern analysis and top traded tokens
  - **Recent Trading Activity**: Last 10 trades with timestamps
  - **Copy Trading Evaluation**: Specific evaluation points and copyability assessment
  - **Recommendations**: Portfolio allocation suggestions and leverage limits
  - **Quick Actions**: "Set as Copy Target" button for recommended accounts

#### Enhanced User Experience
- **Responsive Design**: Modal adapts to screen size with scrollable content
- **Visual Indicators**: Emojis and color coding for quick interpretation
- **Interactive Elements**: Clickable addresses throughout the interface
- **Real-time Data**: Fresh analysis with current positions and recent trades
- **Smart Recommendations**: Context-aware suggestions based on account performance

## 🔧 Technical Details

### Architecture

- **Backend**: FastAPI with async support
- **Frontend**: Vanilla JavaScript + Alpine.js + Tailwind CSS
- **Database**: Uses existing SQLite database
- **Real-time**: Auto-refresh every 30 seconds

### File Structure

```
src/web/
├── __init__.py
├── app.py                 # Main FastAPI application
├── dependencies.py        # Authentication and dependencies
├── routers/
│   ├── __init__.py
│   └── dashboard.py       # Dashboard API endpoints
├── templates/
│   ├── base.html         # Base template
│   └── dashboard.html    # Dashboard page
└── static/
    ├── css/
    │   └── app.css       # Custom styles
    └── js/
        └── app.js        # JavaScript functionality
```

### API Endpoints

- `GET /` - Dashboard page
- `GET /api/dashboard/summary` - Account summary data
- `GET /api/dashboard/positions` - Current positions
- `GET /api/dashboard/recent-trades` - Recent completed trades
- `GET /api/dashboard/market-overview` - Market data
- `GET /health` - Health check

## 🚀 Running with Telegram Bot

You can run both the Telegram bot and Web UI simultaneously:

**Terminal 1** (Telegram Bot):
```bash
python trading_bot.py
```

**Terminal 2** (Web UI):
```bash
python web_start.py
```

Both interfaces will access the same database and trading engine data.

## 🔍 Troubleshooting

### Common Issues

1. **Port already in use**
   - Change `WEB_PORT` in your `.env` file
   - Or stop the process using the port: `lsof -ti:8080 | xargs kill`

2. **API key authentication fails**
   - Ensure `WEB_API_KEY` is set in `.env`
   - Enter the correct API key in the dashboard

3. **Data not loading**
   - Check that your trading bot has data in the database
   - Verify API key is correctly entered
   - Check browser console for errors

4. **Configuration validation errors**
   - Ensure all required environment variables are set
   - Check that `WEB_ENABLED=true`

### Logs

Web UI logs are integrated with the existing logging system. Check:
- Console output when running `web_start.py`
- Log files in the `logs/` directory

## 🛣️ Roadmap

### Phase 2 (Next)
- Trading interface (place orders, close positions)
- Position management controls
- Real-time updates via WebSockets

### Phase 3
- Copy trading dashboard and controls
- Target trader monitoring
- Copy trading performance metrics

### Phase 4
- Advanced analytics and charts
- Performance visualizations
- Export functionality

## 🤝 Support

If you encounter issues:
1. Check the troubleshooting section above
2. Review logs for error messages
3. Ensure your `.env` configuration is correct
4. Verify the Telegram bot is working properly first