Initial commit: Gold Trading Simulator with AI-powered analysis

2025-11-16 00:50:04 +02:00
commit 72c1d3adb7
128 changed files with 16232 additions and 0 deletions
@@ -0,0 +1,170 @@
+# 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!)