# Gold Trading Simulator - Complete Documentation

**An AI-powered gold trading scenario simulator with professional-grade charting, analytics, and risk management tools.**

Welcome to the consolidated documentation for the Gold Trading Simulator. This comprehensive guide covers everything from quick setup to advanced features and daily workflows.

---

## 📋 Table of Contents

### Getting Started
- **[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes
- **[Setup Notes](./SETUP_NOTES.md)** - Detailed installation and configuration

### Core Features
- **[Enhancement Summary](./ENHANCEMENT_SUMMARY.md)** - Complete feature overview and capabilities
- **[Live Chart Implementation](./LIVE_CHART_IMPLEMENTATION.md)** - Real-time charting and data streaming
- **[Chart Fix Summary](./CHART_FIX_SUMMARY.md)** - Technical improvements and optimizations

### Trading Workflows
- **[Daily Trading Workflow](./DAILY_TRADING_WORKFLOW.md)** - Structured approach to daily trading
- **[Daily Trading Implementation](./DAILY_TRADING_IMPLEMENTATION.md)** - Technical implementation details

### Customization & Configuration
- **[Dashboard Customization Guide](./DASHBOARD_CUSTOMIZATION_GUIDE.md)** - Personalize your workspace
- **[Customization Visual Guide](./CUSTOMIZATION_VISUAL_GUIDE.md)** - Visual walkthrough
- **[Customization Implementation](./CUSTOMIZATION_IMPLEMENTATION.md)** - Technical details

### Data & Monitoring
- **[News & Alerts System](./NEWS_AND_ALERTS_GUIDE.md)** - Market news and price alerts
- **[Simulated Feed Guide](./SIMULATED_FEED_GUIDE.md)** - Market data simulation

### Quality Assurance
- **[Testing Checklist](./TESTING_CHECKLIST.md)** - Comprehensive testing procedures
- **[Production Ready Controls](./PRODUCTION_READY_CONTROLS.md)** - Production deployment guide

---

## 🏗️ Project Structure

```
gold-trading-simulator/
├── backend/              # FastAPI Python backend
│   ├── app/
│   │   ├── api/         # API endpoints (market, ai, trading, news, etc.)
│   │   ├── services/    # Business logic (price simulator, news, etc.)
│   │   ├── models/      # Database models
│   │   ├── schemas/     # Pydantic schemas
│   │   ├── streaming/   # WebSocket and live data
│   │   └── config/      # Configuration management
│   └── requirements.txt
├── frontend/            # React + TypeScript + Vite
│   ├── src/
│   │   ├── components/  # UI components (22+ trading components)
│   │   ├── services/    # API client services
│   │   ├── hooks/       # React hooks (live price, etc.)
│   │   ├── utils/       # Utilities (indicators, calculations)
│   │   └── types/       # TypeScript type definitions
│   └── package.json
├── database/            # Database initialization
├── docs/                # 📚 You are here!
├── ft_userdata/         # FreqTrade integration data
├── tools/               # Additional tools (FreqTrade)
└── docker-compose.yml   # PostgreSQL database

```

---

## 🚀 Quick Start

### Prerequisites
- **Node.js 18+** and **Python 3.11+**
- **Docker** for PostgreSQL database
- **API Keys**: Alpha Vantage (free) + OpenRouter (paid, ~$5 minimum)

### 3-Step Setup

```bash
# 1. Start database
docker-compose up -d

# 2. Start backend (Terminal 1)
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# Add API keys to backend/.env
python -m app.main

# 3. Start frontend (Terminal 2)
cd frontend
npm install && npm run dev
```

**Open**: http://localhost:3000

See [QUICKSTART.md](./QUICKSTART.md) for detailed instructions.

---

## 🎯 Key Features

### Professional Trading Interface
- **Real-time candlestick charts** with TradingView-quality rendering
- **22+ UI components** including live market panels, risk management, and analytics
- **Multiple timeframes**: 1min, 5min, 15min, 30min, 1hr, 4hr, 1D, 1W, 1M
- **WebSocket streaming** for live price updates

### Advanced Technical Analysis
- **9+ technical indicators**: SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Fibonacci, Stochastic, Pivot Points
- **Support/Resistance detection** with automated level identification
- **VWAP** for institutional-grade analysis
- **Customizable overlays** - enable/disable indicators on the fly

### AI-Powered Insights
- **AI trade recommendations** using Claude/GPT-4
- **Sentiment analysis** from market news
- **Daily market summaries** with AI-generated insights
- **Trading journal** with AI suggestions

### Risk Management & Analytics
- **Portfolio tracking** with real-time P&L
- **Advanced analytics**: Win rate, profit factor, Sharpe ratio, max drawdown
- **Risk management tools**: Position sizing, stop-loss recommendations
- **Trade history** with detailed performance metrics

### Customizable Dashboard
- **5+ layout presets**: Day Trading, Swing Trading, News Focused, Analytics Pro, Mobile Friendly
- **Save custom layouts** with personalized configurations
- **Component visibility controls** - show/hide any panel
- **Responsive design** - works on desktop, tablet, and mobile

### News & Alerts
- **Live financial news** from multiple sources
- **Price alerts** with custom thresholds
- **Market event notifications**
- **AI-powered news summarization**

---

## 🛠️ Technology Stack

### Backend
- **FastAPI** - Modern Python web framework
- **PostgreSQL** - Relational database
- **SQLAlchemy** - ORM for database operations
- **WebSockets** - Real-time data streaming
- **APScheduler** - Background task scheduling
- **Pandas/NumPy** - Data analysis and calculations

### Frontend
- **React 18** with TypeScript
- **Vite** - Lightning-fast build tool
- **TailwindCSS** - Utility-first styling
- **Lightweight Charts** - High-performance charting by TradingView
- **TanStack Query** - Data fetching and caching
- **Lucide React** - Modern icon library

### APIs & Services
- **Alpha Vantage** - Historical and real-time gold price data
- **OpenRouter** - AI analysis (Claude, GPT-4, etc.)
- **Custom price simulator** - Realistic market simulation

---

## 📡 API Endpoints

### Market Data
- `GET /api/market/gold/current` - Current gold price
- `GET /api/market/gold/historical` - Historical OHLCV data
- `GET /api/market/gold/intraday` - Intraday data with various intervals

### Trading
- `POST /api/trading/buy` - Execute buy order
- `POST /api/trading/sell` - Execute sell order
- `GET /api/trading/portfolio` - Get portfolio status
- `GET /api/trading/history` - Trade history

### AI & Analysis
- `POST /api/ai/analyze` - Get AI trade recommendation
- `POST /api/ai/summarize-news` - AI news summary

### News & Alerts
- `GET /api/news/headlines` - Latest financial news
- `POST /api/alerts/create` - Create price alert
- `GET /api/alerts` - List all alerts

### Live Data (WebSocket)
- `WS /api/stream/price` - Real-time price updates
- `GET /api/ohlcv/klines` - Live OHLCV/kline data

### Admin
- `GET /api/admin/metrics` - System metrics
- `POST /api/admin/data/refresh` - Force data refresh

---

## 📖 Documentation Quick Links

- **New User?** Start with [QUICKSTART.md](./QUICKSTART.md)
- **Daily Trading?** Follow [DAILY_TRADING_WORKFLOW.md](./DAILY_TRADING_WORKFLOW.md)
- **Customization?** See [DASHBOARD_CUSTOMIZATION_GUIDE.md](./DASHBOARD_CUSTOMIZATION_GUIDE.md)
- **Features?** Read [ENHANCEMENT_SUMMARY.md](./ENHANCEMENT_SUMMARY.md)
- **Production Deploy?** Check [PRODUCTION_READY_CONTROLS.md](./PRODUCTION_READY_CONTROLS.md)

---

## 🤝 Contributing

This is a demonstration project showcasing modern full-stack development practices. Feel free to fork, modify, and build upon it for your own trading simulations.

---

## ⚠️ Disclaimer

This is a **simulation** and **educational tool**. Not financial advice. Do not use for actual trading decisions. No real money is involved in this simulator.

---

**Last Updated**: November 2024  
**Version**: 1.0.0  
**Status**: Production-Ready
