robinhood/docs/archive/FILE_REFERENCE_GUIDE.md

# 📁 File Reference Guide - Intelligent Automation System

This guide helps you quickly locate the files you need for different tasks.

---

## 🚀 Getting Started

**Start here**: `QUICKSTART_AUTOMATION.md`  
**Overview**: `README_AUTOMATION.md`  
**Complete details**: `INTELLIGENT_AUTOMATION_IMPLEMENTATION.md`

---

## 🗂️ Backend Files

### Core API Endpoints

#### Smart Trade Hub (Phase 1)
**File**: `backend/app/api/smart_trade_hub.py` (655 lines)

**What it does**:
- Unified trade execution
- ATR-based guard calculation
- Pre-fill suggestions
- Trade history by source

**Key endpoints**:
- `POST /api/smart-trade-hub/execute` - Execute trade
- `POST /api/smart-trade-hub/prefill` - Get smart suggestions
- `GET /api/smart-trade-hub/suggestions` - Get AI guards
- `GET /api/smart-trade-hub/history` - Trade history

**Test it**:
```bash
curl -X POST http://localhost:8000/api/smart-trade-hub/execute \
  -H "Content-Type: application/json" \
  -d '{"action": "BUY", "symbol": "XAU/USD", "apply_smart_guards": true}'
```

---

#### Live Performance Dashboard (Phase 5)
**File**: `backend/app/api/live_dashboard.py` (450 lines)

**What it does**:
- Real-time plan monitoring
- Alert generation
- Limit checking
- Session summaries

**Key endpoints**:
- `GET /api/live-dashboard/status` - Current status
- `GET /api/live-dashboard/widget` - Widget data
- `POST /api/live-dashboard/check-limits` - Validate trading
- `GET /api/live-dashboard/session-summary` - AI coaching

**Test it**:
```bash
curl http://localhost:8000/api/live-dashboard/status
```

---

### Supporting Services

#### Price Anchor Service
**File**: `backend/app/services/price_anchor.py` (modified)

**What it does**:
- Fetches current gold prices
- Caches prices for 30 seconds
- Provides synchronous access for guard calculations

**Usage**:
```python
from app.services.price_anchor import price_anchor_service

price = price_anchor_service.get_anchor_price_sync("XAUUSD")
```

---

#### Main Application
**File**: `backend/app/main.py` (modified)

**What changed**:
- Added `smart_trade_hub` router
- Added `live_dashboard` router

**Lines changed**:
```python
from app.api import smart_trade_hub, live_dashboard

app.include_router(smart_trade_hub.router)
app.include_router(live_dashboard.router)
```

---

## 🎨 Frontend Files

### Core Components

#### Smart Trade Hub
**File**: `frontend/src/components/SmartTradeHub.tsx` (580 lines)

**What it does**:
- Unified trade entry interface
- Smart guard visualization
- Auto-fill from last trade
- Manual override controls

**Props**:
```tsx
interface SmartTradeHubProps {
  currentPrice?: number;
  onTradeExecuted?: (trade: TradeResponse) => void;
}
```

**Usage**:
```tsx
<SmartTradeHub 
  currentPrice={2034.25}
  onTradeExecuted={(trade) => {
    console.log('Trade executed:', trade);
    refreshPortfolio();
  }}
/>
```

---

#### Live Performance Dashboard
**File**: `frontend/src/components/LivePerformanceDashboard.tsx` (450 lines)

**What it does**:
- Sticky performance widget
- Real-time progress bars
- Alert cards
- Recommendations

**Props**:
```tsx
interface LivePerformanceDashboardProps {
  refreshInterval?: number;           // Default: 5000ms
  position?: 'sticky' | 'inline';     // Default: 'sticky'
  onLimitReached?: () => void;
}
```

**Usage**:
```tsx
<LivePerformanceDashboard 
  position="sticky"
  refreshInterval={5000}
  onLimitReached={() => {
    alert('Daily limits reached!');
  }}
/>
```

---

## 📚 Documentation Files

### Quick References

#### 1. Quick Start (5 minutes)
**File**: `QUICKSTART_AUTOMATION.md`

**Use when**: You want to get up and running quickly

**Contents**:
- Step-by-step setup
- Testing instructions
- Common issues & fixes
- Success checklist

---

#### 2. Implementation Guide
**File**: `INTELLIGENT_AUTOMATION_IMPLEMENTATION.md`

**Use when**: You need detailed technical information

**Contents**:
- Architecture overview
- API reference with examples
- Integration instructions
- Performance metrics
- Success criteria

---

#### 3. Complete Roadmap
**File**: `INTELLIGENT_AUTOMATION_ROADMAP.md`

**Use when**: You want to see the big picture

**Contents**:
- All 8 phases explained
- Technical specifications
- Code examples for future phases
- Expected outcomes
- Timeline

---

#### 4. Delivery Summary
**File**: `DELIVERY_SUMMARY.md`

**Use when**: You need an executive overview

**Contents**:
- What was delivered
- Measurable results
- Time savings
- Success metrics
- Next steps

---

#### 5. Automation README
**File**: `README_AUTOMATION.md`

**Use when**: You want a high-level overview

**Contents**:
- Feature highlights
- Quick start
- API endpoints
- Coming soon features

---

## 🔧 How to Use This System

### Scenario 1: "I want to integrate the new components"

**Steps**:
1. Read: `QUICKSTART_AUTOMATION.md` (5 minutes)
2. Backend: Already integrated, just restart server
3. Frontend: Add these imports to `App.tsx`:
   ```tsx
   import SmartTradeHub from './components/SmartTradeHub';
   import LivePerformanceDashboard from './components/LivePerformanceDashboard';
   ```
4. Test: Follow the success checklist

**Files needed**:
- ✅ `QUICKSTART_AUTOMATION.md`
- ✅ `frontend/src/components/SmartTradeHub.tsx`
- ✅ `frontend/src/components/LivePerformanceDashboard.tsx`

---

### Scenario 2: "I want to understand the architecture"

**Steps**:
1. Read: `INTELLIGENT_AUTOMATION_IMPLEMENTATION.md`
2. Review: Backend files (`smart_trade_hub.py`, `live_dashboard.py`)
3. Review: Frontend files (`SmartTradeHub.tsx`, `LivePerformanceDashboard.tsx`)

**Files needed**:
- ✅ `INTELLIGENT_AUTOMATION_IMPLEMENTATION.md`
- ✅ `backend/app/api/smart_trade_hub.py`
- ✅ `backend/app/api/live_dashboard.py`
- ✅ `frontend/src/components/SmartTradeHub.tsx`
- ✅ `frontend/src/components/LivePerformanceDashboard.tsx`

---

### Scenario 3: "I want to see what's coming next"

**Steps**:
1. Read: `INTELLIGENT_AUTOMATION_ROADMAP.md`
2. Focus on: Phases 2-8 sections
3. Check: Timeline and expected outcomes

**Files needed**:
- ✅ `INTELLIGENT_AUTOMATION_ROADMAP.md`

---

### Scenario 4: "I need to customize the settings"

**Steps**:
1. Read: `QUICKSTART_AUTOMATION.md` → "Customization Examples"
2. Edit: Risk settings in `smart_trade_hub.py`
3. Edit: Dashboard colors in `LivePerformanceDashboard.tsx`

**Files to edit**:
- ✅ `backend/app/api/smart_trade_hub.py` (risk percentages, guard calculations)
- ✅ `backend/app/api/live_dashboard.py` (daily plan defaults)
- ✅ `frontend/src/components/LivePerformanceDashboard.tsx` (colors, refresh rate)
- ✅ `frontend/src/components/SmartTradeHub.tsx` (default toggles)

---

### Scenario 5: "I found a bug"

**Steps**:
1. Check: `QUICKSTART_AUTOMATION.md` → "Common Issues & Fixes"
2. Test: API endpoints with curl commands
3. Review: Backend logs for errors
4. Check: Browser console for frontend errors

**Files to check**:
- ✅ `QUICKSTART_AUTOMATION.md` (troubleshooting)
- ✅ `backend/app/api/smart_trade_hub.py` (backend logic)
- ✅ `backend/app/api/live_dashboard.py` (backend logic)
- ✅ Browser console (frontend errors)

---

## 🎯 Common Tasks Quick Reference

### Task: Execute a test trade
```bash
# 1. Ensure backend is running
curl http://localhost:8000/health

# 2. Execute trade
curl -X POST http://localhost:8000/api/smart-trade-hub/execute \
  -H "Content-Type: application/json" \
  -d '{"action": "BUY", "symbol": "XAU/USD", "apply_smart_guards": true}'
```

**Files involved**:
- `backend/app/api/smart_trade_hub.py`

---

### Task: Check daily plan status
```bash
curl http://localhost:8000/api/live-dashboard/status
```

**Files involved**:
- `backend/app/api/live_dashboard.py`

---

### Task: Change max risk from 2% to 1%

**Edit**: `backend/app/api/smart_trade_hub.py`

Find this code (around line 250):
```python
if risk_percent > 2.0:
    adjusted_quantity = (equity * 0.02) / sl_distance
    risk_percent = 2.0
```

Change to:
```python
if risk_percent > 1.0:
    adjusted_quantity = (equity * 0.01) / sl_distance
    risk_percent = 1.0
```

**Restart backend** to apply changes.

---

### Task: Change dashboard refresh rate

**Edit**: `frontend/src/components/LivePerformanceDashboard.tsx`

Or in your usage:
```tsx
<LivePerformanceDashboard refreshInterval={10000} /> // 10 seconds
```

---

### Task: Disable smart guards by default

**Edit**: `frontend/src/components/SmartTradeHub.tsx`

Find this line (around line 45):
```tsx
const [useSmartGuards, setUseSmartGuards] = useState(true);
```

Change to:
```tsx
const [useSmartGuards, setUseSmartGuards] = useState(false);
```

---

## 📊 File Statistics

| Category | Files | Lines | Purpose |
|----------|-------|-------|---------|
| Backend API | 2 | 1,105 | Smart trading logic |
| Frontend Components | 2 | 1,030 | User interface |
| Documentation | 5 | ~5,000 | Guides & references |
| **Total** | **9** | **~7,135** | **Complete system** |

---

## 🔍 Find Code By Feature

### Feature: ATR-based stop loss calculation
**File**: `backend/app/api/smart_trade_hub.py`  
**Function**: `_calculate_smart_guards()` (line ~150)

### Feature: Daily limit checking
**File**: `backend/app/api/live_dashboard.py`  
**Function**: `check_trading_limits()` (line ~250)

### Feature: Trade auto-fill
**File**: `frontend/src/components/SmartTradeHub.tsx`  
**Function**: `loadPreFillData()` (line ~75)

### Feature: Progress bars
**File**: `frontend/src/components/LivePerformanceDashboard.tsx`  
**Component**: Progress bar rendering (line ~200)

### Feature: Smart alerts
**File**: `backend/app/api/live_dashboard.py`  
**Function**: `_generate_alerts()` (line ~80)

---

## 🆘 Need Help?

### Backend Issues
**Start here**: `backend/app/api/smart_trade_hub.py` docstrings  
**Logs**: Check terminal where `uvicorn` is running

### Frontend Issues
**Start here**: Browser console errors  
**Components**: `frontend/src/components/*.tsx` inline comments

### Integration Issues
**Start here**: `QUICKSTART_AUTOMATION.md` → "Common Issues"  
**API Testing**: Use curl commands from docs

### General Questions
**Start here**: `INTELLIGENT_AUTOMATION_IMPLEMENTATION.md`  
**Roadmap**: `INTELLIGENT_AUTOMATION_ROADMAP.md`

---

## ✅ Quick Checklist

Before asking for help, verify:

- [ ] Backend is running (`curl http://localhost:8000/health`)
- [ ] Frontend is running (`http://localhost:3000` loads)
- [ ] No console errors in browser
- [ ] No errors in backend terminal
- [ ] Checked "Common Issues" section in QUICKSTART
- [ ] Tried the relevant curl command

---

**Last Updated**: November 24, 2025  
**File Count**: 9 files delivered  
**Total Lines**: ~7,135 lines  
**Status**: ✅ Complete & Documented