301 lines
10 KiB
Markdown
301 lines
10 KiB
Markdown
# Setup Notes & Architecture
|
|
|
|
## Environment Variables Reference
|
|
|
|
### Backend (.env)
|
|
```bash
|
|
# Required
|
|
ALPHA_VANTAGE_API_KEY=your_key # Get from alphavantage.co
|
|
OPENROUTER_API_KEY=your_key # Get from openrouter.ai
|
|
|
|
# Database
|
|
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/gold_trading_db
|
|
|
|
# Optional - defaults work fine
|
|
APP_ENV=development
|
|
DEBUG=True
|
|
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
|
|
HOST=0.0.0.0
|
|
PORT=8000
|
|
```
|
|
|
|
### Frontend (.env)
|
|
```bash
|
|
# Required - points to backend API
|
|
VITE_API_URL=http://localhost:8000/api
|
|
|
|
# Optional - only if you want direct frontend calls (not recommended)
|
|
VITE_ALPHA_VANTAGE_API_KEY=your_key
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Browser (Port 3000) │
|
|
│ ┌────────────┐ ┌─────────────┐ ┌──────────────────────┐ │
|
|
│ │ Chart │ │ Trade Panel │ │ Portfolio Tracker │ │
|
|
│ │ Component │ │ Component │ │ Component │ │
|
|
│ └────────────┘ └─────────────┘ └──────────────────────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────┴────────────────────┘ │
|
|
│ │ │
|
|
│ API Service │
|
|
│ │ │
|
|
└──────────────────────────┼───────────────────────────────────┘
|
|
│ HTTP/REST
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FastAPI Backend (Port 8000) │
|
|
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ /api/market│ │ /api/trading │ │ /api/ai │ │
|
|
│ │ endpoints │ │ endpoints │ │ endpoints │ │
|
|
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ Alpha │ │ In-memory │ │ OpenRouter │ │
|
|
│ │ Vantage │ │ Trading │ │ Service │ │
|
|
│ │ Service │ │ State (MVP) │ │ (Claude 3.5) │ │
|
|
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌────────────────────────┐
|
|
│ Alpha Vantage │ │ OpenRouter API │
|
|
│ API │ │ (Claude 3.5 Sonnet) │
|
|
│ (Market Data) │ │ (AI Analysis) │
|
|
└──────────────────┘ └────────────────────────┘
|
|
|
|
│
|
|
▼
|
|
┌──────────────────────────────────┐
|
|
│ PostgreSQL Database │
|
|
│ (Port 5432 - Docker) │
|
|
│ ┌──────────────────────────────┐│
|
|
│ │ Tables (for Phase 2): ││
|
|
│ │ - simulations ││
|
|
│ │ - trades ││
|
|
│ │ - positions ││
|
|
│ │ - ai_analysis_logs ││
|
|
│ └──────────────────────────────┘│
|
|
└──────────────────────────────────┘
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
### 1. Loading Historical Data
|
|
```
|
|
Browser → GET /api/market/gold/history
|
|
↓
|
|
FastAPI → Alpha Vantage Service
|
|
↓
|
|
Alpha Vantage API (XAU/USD daily data)
|
|
↓
|
|
Transform to PriceData[]
|
|
↓
|
|
Calculate SMA(50) in frontend
|
|
↓
|
|
Render with Lightweight Charts
|
|
```
|
|
|
|
### 2. Executing Trade
|
|
```
|
|
User clicks "Buy" → POST to local state (MVP)
|
|
↓
|
|
Update portfolio state
|
|
↓
|
|
Recalculate P&L
|
|
↓
|
|
Update UI components
|
|
```
|
|
|
|
### 3. AI Analysis
|
|
```
|
|
User clicks "AI Analysis" → Gather context:
|
|
- Last 50 price points
|
|
- Current indicators
|
|
- Current price
|
|
↓
|
|
POST /api/ai/analyze
|
|
↓
|
|
OpenRouter Service → Claude 3.5 Sonnet
|
|
↓
|
|
Parse JSON response
|
|
↓
|
|
Return AIAnalysisResponse
|
|
↓
|
|
Display in AIAnalysisPanel
|
|
```
|
|
|
|
## Technology Choices Explained
|
|
|
|
### Why Lightweight Charts?
|
|
- **Optimized for trading:** Built by TradingView specifically for financial data
|
|
- **Performance:** Can handle 10,000+ candles smoothly
|
|
- **Size:** Only 35KB gzipped
|
|
- **Free:** Apache 2.0 license, no restrictions
|
|
|
|
### Why Alpha Vantage?
|
|
- **Free tier:** 500 calls/day is plenty for development
|
|
- **Forex data:** Includes XAU/USD (gold) out of the box
|
|
- **Reliability:** Industry-standard data provider
|
|
- **No credit card:** Instant API key
|
|
|
|
### Why OpenRouter + Claude?
|
|
- **Best reasoning:** Claude 3.5 Sonnet > GPT-4o for complex analysis
|
|
- **Pay-per-use:** No monthly subscription
|
|
- **Unified API:** Access 400+ models through one endpoint
|
|
- **OpenAI-compatible:** Easy migration if needed
|
|
|
|
### Why FastAPI?
|
|
- **Speed:** 3x faster than Flask for async operations
|
|
- **Type safety:** Pydantic schemas ensure data validation
|
|
- **Auto docs:** Swagger UI at /docs
|
|
- **Modern:** Async/await throughout
|
|
|
|
### Why PostgreSQL?
|
|
- **Reliability:** Production-grade ACID compliance
|
|
- **Time-series:** Works well with TimescaleDB extension (future)
|
|
- **JSON support:** Flexible for evolving schemas
|
|
- **Free:** Open source forever
|
|
|
|
## MVP vs. Future Phases
|
|
|
|
### MVP (Current) - In-Memory State
|
|
```python
|
|
# backend/app/api/trading.py
|
|
simulation_state = {
|
|
"cash": 100000.0,
|
|
"position": None,
|
|
"trades": []
|
|
}
|
|
```
|
|
|
|
**Pros:**
|
|
- Fast to implement
|
|
- No database setup issues
|
|
- Perfect for testing
|
|
|
|
**Cons:**
|
|
- Resets on server restart
|
|
- Single user only
|
|
- No historical analysis
|
|
|
|
### Phase 2 - Database Persistence
|
|
```python
|
|
# Future implementation
|
|
@router.post("/execute")
|
|
async def execute_trade(trade: TradeCreate, db: Session = Depends(get_db)):
|
|
# Save to PostgreSQL
|
|
db_trade = Trade(**trade.dict())
|
|
db.add(db_trade)
|
|
db.commit()
|
|
return db_trade
|
|
```
|
|
|
|
**Benefits:**
|
|
- Persistent across restarts
|
|
- Multi-user support
|
|
- Historical backtesting
|
|
- Advanced analytics
|
|
|
|
## API Rate Limits
|
|
|
|
### Alpha Vantage Free Tier
|
|
- **5 calls/minute**
|
|
- **500 calls/day**
|
|
- **Strategy:** Cache aggressively, use `compact` output for development
|
|
|
|
### OpenRouter (Pay-per-use)
|
|
- **No rate limit** (reasonable use)
|
|
- **Cost per analysis:** ~$0.01-0.05
|
|
- **Strategy:** User-initiated only, no auto-refresh
|
|
|
|
## Security Considerations
|
|
|
|
### Current (Development)
|
|
- API keys in `.env` files
|
|
- CORS restricted to localhost
|
|
- No authentication
|
|
|
|
### Production Requirements
|
|
- **Environment variables** from secrets manager (AWS Secrets Manager, etc.)
|
|
- **HTTPS** for all connections
|
|
- **JWT authentication** for users
|
|
- **Rate limiting** per IP/user
|
|
- **API key rotation** policy
|
|
- **Input validation** on all endpoints
|
|
|
|
## Performance Metrics
|
|
|
|
### Expected Response Times
|
|
- Market data endpoint: 200-500ms (Alpha Vantage)
|
|
- Trading execute: <10ms (in-memory)
|
|
- AI analysis: 3-10 seconds (Claude API)
|
|
|
|
### Optimization Opportunities
|
|
1. **Redis caching** for market data (reduce API calls)
|
|
2. **WebSocket** for real-time updates (future)
|
|
3. **CDN** for frontend static assets
|
|
4. **Database indexes** on frequently queried fields
|
|
5. **Connection pooling** for PostgreSQL
|
|
|
|
## Monitoring & Debugging
|
|
|
|
### Backend Logs
|
|
```bash
|
|
# Watch backend logs
|
|
cd backend
|
|
source venv/bin/activate
|
|
python -m app.main
|
|
|
|
# Look for:
|
|
# - API call patterns
|
|
# - Error traces
|
|
# - Response times
|
|
```
|
|
|
|
### Frontend Console
|
|
```javascript
|
|
// Browser console (F12)
|
|
// Network tab shows API calls
|
|
// Console shows React errors
|
|
```
|
|
|
|
### Database Queries
|
|
```bash
|
|
# Connect to PostgreSQL
|
|
docker exec -it gold_trading_db psql -U postgres -d gold_trading_db
|
|
|
|
# Useful commands:
|
|
\dt # List tables
|
|
\d simulations # Describe table
|
|
SELECT COUNT(*) FROM trades;
|
|
```
|
|
|
|
## Common Development Workflows
|
|
|
|
### Adding a New Indicator
|
|
1. Create calculation function in `frontend/src/utils/indicators.ts`
|
|
2. Add to chart component state
|
|
3. Create line series in chart
|
|
4. Add toggle in UI
|
|
|
|
### Adding a New API Endpoint
|
|
1. Define schema in `backend/app/schemas/schemas.py`
|
|
2. Create route in appropriate `backend/app/api/*.py`
|
|
3. Add service method if needed
|
|
4. Update frontend API service
|
|
5. Create React hook for data fetching
|
|
|
|
### Database Schema Changes
|
|
1. Update model in `backend/app/models/models.py`
|
|
2. Create Alembic migration (future)
|
|
3. Run migration
|
|
4. Update schemas and routes
|
|
|
|
---
|
|
|
|
This completes the comprehensive setup and architecture documentation!
|