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:

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:

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:

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:

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:

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

Usage:

<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:

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

Usage:

<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:

   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

# 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

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):

if risk_percent > 2.0:
    adjusted_quantity = (equity * 0.02) / sl_distance
    risk_percent = 2.0

Change to:

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:

<LivePerformanceDashboard refreshInterval={10000} /> // 10 seconds

---

Task: Disable smart guards by default

Edit: frontend/src/components/SmartTradeHub.tsx

Find this line (around line 45):

const [useSmartGuards, setUseSmartGuards] = useState(true);

Change to:

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