# Quick Start Guide - Gold Trading Simulator

Get up and running in 5 minutes!

## Prerequisites Checklist

- [ ] Node.js 18+ installed (`node --version`)
- [ ] Python 3.11+ installed (`python --version`)
- [ ] Docker installed (`docker --version`)
- [ ] Alpha Vantage API key (get free at https://www.alphavantage.co/support/#api-key)
- [ ] OpenRouter API key (get at https://openrouter.ai/)

## 5-Minute Setup

### 1. Start Database (1 minute)

```bash
cd gold-trading-simulator
docker-compose up -d
```

Wait for PostgreSQL to start:
```bash
docker logs gold_trading_db
# Should see: "database system is ready to accept connections"
```

### 2. Setup Backend (2 minutes)

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
nano .env  # or use your preferred editor
```

**Edit `.env` and add your API keys:**
```bash
ALPHA_VANTAGE_API_KEY=your_actual_key_here
OPENROUTER_API_KEY=your_actual_key_here
```

**Initialize database:**
```bash
python ../database/init_db.py
```

### 3. Setup Frontend (1 minute)

```bash
cd ../frontend

# Install dependencies
npm install

# Environment already configured in .env.example
# No changes needed unless you changed backend port
```

### 4. Start Application (1 minute)

**Terminal 1 - Backend:**
```bash
cd backend
source venv/bin/activate
python -m app.main
```

You should see:
```
INFO:     Uvicorn running on http://0.0.0.0:8000
```

**Terminal 2 - Frontend:**
```bash
cd frontend
npm run dev
```

You should see:
```
  VITE v5.x.x  ready in XXX ms

  ➜  Local:   http://localhost:3000/
```

### 5. Open Browser

Navigate to: **http://localhost:3000**

You should see the Gold Trading Simulator dashboard!

## First Steps in the App

1. **Wait for data to load** - The chart will populate with gold price history
2. **Explore the chart** - Hover over candles to see price details
3. **Execute a trade:**
   - Enter quantity (e.g., 10 oz)
   - Click "Buy" button
   - See position appear in portfolio
4. **Try AI analysis:**
   - Click "AI Analysis" button
   - Wait ~5-10 seconds
   - Review recommendation

## Troubleshooting

### "Error loading market data"
- **Check:** Alpha Vantage API key in `backend/.env`
- **Verify:** Backend is running on port 8000
- **Test:** `curl http://localhost:8000/health`

### "Backend connection failed"
- **Check:** Backend terminal for errors
- **Verify:** No other service using port 8000
- **Test:** `curl http://localhost:8000/api/market/gold/current`

### "AI analysis failed"
- **Check:** OpenRouter API key in `backend/.env`
- **Verify:** You have credits at https://openrouter.ai/
- **Check:** Backend logs for detailed error

### Database connection error
- **Check:** Docker container is running: `docker ps`
- **Restart:** `docker-compose restart`
- **Logs:** `docker logs gold_trading_db`

## API Key Setup Details

### Alpha Vantage (Free Tier)
1. Visit: https://www.alphavantage.co/support/#api-key
2. Enter your email
3. Get instant API key
4. **Limits:** 500 calls/day, 5 calls/minute
5. **Cost:** Free forever

### OpenRouter
1. Visit: https://openrouter.ai/
2. Sign up with GitHub/Google
3. Go to Keys section
4. Create new key
5. Add credits ($5 minimum)
6. **Cost:** ~$0.01-0.05 per AI analysis

## Next Steps

- Read [README.md](README.md) for full documentation
- Explore different trading strategies
- Check out the API endpoints
- Plan Phase 2 features (multiple timeframes, more indicators)

## Getting Help

If you run into issues:
1. Check the Troubleshooting section above
2. Review backend logs in the terminal
3. Check browser console for frontend errors (F12)
4. Verify all environment variables are set correctly

---

Happy Trading! (Virtually, of course!)