robinhood/docs/IMPLEMENTATION_NOTES.md

Implementation Notes - Trading Companion Evolution

Comprehensive guide to the platform's evolution from simulator to professional trading companion

---

🎯 Overview

This document tracks the transformation of the Gold Trading Simulator into a Trading Companion App - a professional journaling and decision support tool for traders executing on external broker platforms (MT5, cTrader, OANDA, Interactive Brokers, etc.).

---

📊 Platform Architecture Evolution

Phase 1: Basic Simulator (Initial Release)

• Simulated trading environment
• Basic buy/sell functionality
• Simple portfolio tracking
• Demo price feeds

Phase 2: Advanced Analytics (Q3 2024)

• 12+ technical indicators
• Advanced risk management
• Performance analytics
• AI-powered analysis

Phase 3: Trading Companion (Q4 2024)

• Manual trade logging
• Trading journal system
• Broker bridge integration
• Daily planning workflow
• Decision tracking
• Real market data integration

---

🗄️ Database Schema Extensions

New Models Added

1. TradingPlan Model

Purpose: Store daily/weekly trading plans (manual or AI-generated)

Fields:

class TradingPlan(Base):
    id: int
    user_id: int
    date: date
    plan_type: str  # 'daily' | 'weekly'
    market_bias: str  # 'BULLISH' | 'BEARISH' | 'NEUTRAL'
    bias_confidence: int  # 0-100

    # Key levels
    support_levels: JSON  # [2045.50, 2038.00, ...]
    resistance_levels: JSON  # [2067.50, 2075.00, ...]

    # Trade setups
    entry_zones: JSON
    target_levels: JSON
    stop_loss_levels: JSON

    # Risk parameters
    max_trades: int
    risk_per_trade: str
    max_daily_loss: str

    # Metadata
    notes: Text
    plan_text: Text  # Full AI-generated plan
    created_by_ai: bool
    ai_model: str  # e.g., 'claude-3.5-sonnet'

    # Performance tracking
    trades_taken: int
    plan_followed: bool
    actual_pnl: Decimal

    # Relationships
    trades: List[ManualTrade]  # Related trades

Location: backend/app/models/models.py Migration: backend/migrate_indicator_ai_tables.py

2. ManualTrade Model

Purpose: Log trades executed on external broker platforms

Fields:

class ManualTrade(Base):
    id: int
    user_id: int
    trading_plan_id: int  # Optional link to plan

    # Trade details
    symbol: str  # 'XAUUSD'
    direction: str  # 'LONG' | 'SHORT'
    entry_price: Decimal
    exit_price: Decimal
    quantity: Decimal

    # Timestamps
    entry_time: datetime
    exit_time: datetime

    # P&L
    gross_pnl: Decimal
    commission: Decimal
    net_pnl: Decimal

    # Broker info
    broker_name: str  # 'MT5' | 'cTrader' | 'OANDA' | etc.
    broker_ticket_id: str  # External trade ID

    # Documentation
    screenshot_url: str  # Path to trade screenshot
    notes: Text

    # Analysis
    followed_plan: bool
    ai_recommendation: str  # What AI suggested
    actual_action: str  # What trader did

    # Relationships
    plan: TradingPlan
    journal_entry: JournalEntry

Location: backend/app/models/models.py

3. JournalEntry Model

Purpose: Daily reflections and trading lessons

Fields:

class JournalEntry(Base):
    id: int
    user_id: int
    date: date

    # Emotional state
    mood: str  # 'excellent' | 'good' | 'neutral' | 'poor'
    energy_level: int  # 1-10
    stress_level: int  # 1-10

    # Reflections
    what_went_well: Text
    what_to_improve: Text
    lessons_learned: Text

    # Market observations
    market_notes: Text
    key_events: JSON  # Major news, economic data

    # Performance
    daily_pnl: Decimal
    trades_count: int
    wins: int
    losses: int

    # Relationships
    trades: List[ManualTrade]

Location: backend/app/models/models.py

4. DecisionLog Model

Purpose: Track AI recommendations vs actual trader actions

Fields:

class DecisionLog(Base):
    id: int
    user_id: int
    timestamp: datetime

    # AI recommendation
    ai_suggestion: str  # 'BUY' | 'SELL' | 'HOLD'
    ai_confidence: int  # 0-100
    ai_reasoning: Text
    suggested_entry: Decimal
    suggested_stop: Decimal
    suggested_target: Decimal

    # Trader action
    action_taken: str  # 'FOLLOWED' | 'IGNORED' | 'MODIFIED'
    actual_entry: Decimal
    actual_stop: Decimal
    actual_target: Decimal
    trader_reasoning: Text

    # Outcome
    trade_id: int  # Links to ManualTrade if executed
    outcome: str  # 'WIN' | 'LOSS' | 'BREAKEVEN' | 'NOT_TAKEN'
    outcome_pnl: Decimal

    # Analysis
    was_ai_correct: bool

Location: backend/app/models/models.py

5. WeeklyPlan Model

Purpose: Weekly macro outlook and strategy

Fields:

class WeeklyPlan(Base):
    id: int
    user_id: int
    week_start: date

    # Macro outlook
    weekly_bias: str
    key_economic_events: JSON
    major_levels: JSON

    # Strategy
    weekly_targets: JSON
    risk_limits: str
    focus_setups: Text

    # Review
    weekly_review: Text
    actual_pnl: Decimal
    goals_met: bool

    # Relationships
    daily_plans: List[TradingPlan]

Location: backend/app/models/models.py

---

🔌 API Endpoints

Journal API (/api/journal/*)

Trading Plans:

• POST /api/journal/plans - Create new plan
• GET /api/journal/plans/today - Get today's plan
• GET /api/journal/plans/date/{date} - Get plan by specific date
• GET /api/journal/plans - List recent plans (query params: limit, offset)
• PUT /api/journal/plans/{id} - Update plan
• DELETE /api/journal/plans/{id} - Delete plan

Manual Trades:

• POST /api/journal/trades - Log new trade
• GET /api/journal/trades - List all trades (filterable)
• GET /api/journal/trades/{id} - Get specific trade
• PUT /api/journal/trades/{id} - Update trade
• DELETE /api/journal/trades/{id} - Delete trade
• POST /api/journal/trades/bulk - Import multiple trades (CSV/JSON)

Journal Entries:

• POST /api/journal/entries - Create journal entry
• GET /api/journal/entries/today - Get today's entry
• GET /api/journal/entries/date/{date} - Get entry by date
• GET /api/journal/entries - List entries (date range)
• PUT /api/journal/entries/{id} - Update entry

Decision Logs:

• POST /api/journal/decisions - Log AI recommendation + action
• GET /api/journal/decisions - List decisions (filterable)
• GET /api/journal/decisions/analysis - Analyze AI accuracy

Weekly Plans:

• POST /api/journal/weekly-plans - Create weekly plan
• GET /api/journal/weekly-plans/current - Get current week plan
• GET /api/journal/weekly-plans - List weekly plans

File: backend/app/api/journal.py

Broker Bridge API (/api/brokers/*)

Purpose: Integrate with external broker platforms

Endpoints:

• GET /api/brokers/positions - Fetch current positions from broker
• POST /api/brokers/sync - Sync trades from broker to journal
• GET /api/brokers/supported - List supported broker platforms
• POST /api/brokers/connect - Connect to broker API
• GET /api/brokers/account - Get broker account info

Supported Brokers:

• MetaTrader 5 (via MT5 Python API)
• cTrader (via OpenAPI)
• OANDA (via REST API)
• Interactive Brokers (via TWS API)
• Manual CSV import

File: backend/app/api/brokers.py

Positions API Extensions (/api/positions/*)

New Endpoints:

• GET /api/positions/metrics - Advanced position metrics
  • Bollinger Bands guard rails (bb_upper, bb_lower, bb_signal)
  • Zero-lag LSMA trend (zlsma, zlsma_slope)
  • Chandelier Exit stops (long_stop, short_stop)
  • Candlestick pattern signals

File: backend/app/api/positions.py

---

🎨 Frontend Components

New Components

1. ManualTradeLogger

Purpose: Log trades from external broker

Features:

• Quick trade entry form
• Screenshot upload
• Broker platform selection
• Link to daily plan
• P&L calculation
• Tags and notes

File: frontend/src/components/ManualTradeLogger.tsx

2. IndicatorPreferences

Purpose: Configure preferred indicators for AI analysis

Features:

• Select favorite indicators
• Set custom parameters
• Save preferences per user
• Apply to AI plan generation

File: frontend/src/components/IndicatorPreferences.tsx

3. BrokerBridgePanel

Purpose: Connect to external broker APIs

Features:

• Broker selection
• API credential configuration
• Connection testing
• Auto-sync settings
• Position display

File: frontend/src/components/BrokerBridgePanel.tsx

4. BrokerPositionsPanel

Purpose: View live positions from connected broker

Features:

• Real-time position updates
• P&L tracking
• Risk metrics
• Quick close actions

File: frontend/src/components/BrokerPositionsPanel.tsx

Enhanced Components

DailyTradingPlan (Enhanced)

New Features:

• AI-generated plan display
• Manual plan creation
• Plan adherence tracking
• Performance comparison (planned vs actual)
• Integration with ManualTradeLogger

File: frontend/src/components/DailyTradingPlan.tsx

SettingsPanel (Enhanced)

New Sections:

• Indicator preferences
• Broker connections
• Journal preferences
• AI model selection

File: frontend/src/components/SettingsPanel.tsx

---

🔧 Backend Services

New Services

1. AI Plan Service

Purpose: Generate AI-powered daily trading plans

Features:

• User profile integration (capital, risk tolerance)
• Technical indicator analysis
• Multi-setup planning
• Session timing recommendations
• Contingency scenarios

File: backend/app/services/ai_plan_service.py

Key Methods:

async def generate_plan(db, request, user_id):
    """Generate comprehensive daily trading plan"""

async def analyze_trader_profile(user_id):
    """Analyze trader's historical performance"""

async def save_plan_to_db(plan_data, user_id):
    """Store plan in database"""

2. AI Context Builder

Purpose: Build rich context for AI prompts

Features:

• Position metrics calculation
• Bollinger Bands with RSI guard rails
• Zero-lag LSMA trend analysis
• Chandelier Exit stop levels
• Candlestick pattern detection

File: backend/app/services/ai_context_builder.py

Key Methods:

def build_context(price_data, indicators, positions):
    """Build comprehensive AI context"""

def calculate_position_metrics(current_price, positions):
    """Calculate advanced position metrics"""

def detect_candlestick_patterns(candles):
    """Detect major candlestick patterns"""

3. Broker Bridge Service

Purpose: Connect to external broker platforms

Features:

• Multi-broker support
• API abstraction layer
• Trade synchronization
• Position fetching
• Account info retrieval

File: backend/app/services/broker_bridge.py

Key Methods:

async def connect_broker(broker_type, credentials):
    """Establish broker connection"""

async def sync_trades(broker, start_date, end_date):
    """Sync trades from broker to journal"""

async def fetch_positions(broker):
    """Get current open positions"""

4. Candlestick Pattern Service

Purpose: Detect and analyze candlestick patterns

Features:

• 20+ pattern detection (Doji, Hammer, Engulfing, etc.)
• Pattern strength scoring
• Bullish/bearish classification
• Integration with AI context

File: backend/app/services/candlestick_patterns.py

Patterns Supported:

• Doji (Standard, Gravestone, Dragonfly)
• Hammer / Inverted Hammer
• Shooting Star
• Bullish / Bearish Engulfing
• Morning / Evening Star
• Tweezer Tops / Bottoms
• Long Upper / Lower Shadows
• Three White Soldiers / Black Crows

Enhanced Services

OpenRouter Service (Enhanced)

New Features:

• Gold-specific prompts
• Professional analyst persona
• Comprehensive market structure analysis
• Risk-aware recommendations
• Empty data graceful handling

File: backend/app/services/openrouter.py

---

📊 Data Integration

Real Market Data Sources

Current Implementations

1. GoldPrice.org

• Live spot prices
• No API key required
• Updates every few seconds
• Primary data source

File: backend/app/services/metals/goldprice.py

2. yfinance (Yahoo Finance)

• Historical gold data (GC=F futures)
• FX pairs (EURUSD, GBPUSD, etc.)
• No API key required
• Backup data source

File: backend/app/services/metals/yfinance_provider.py

3. Yahoo Finance REST API

• Alternative to yfinance library
• Direct HTTP requests
• OHLCV data
• Tertiary backup

File: backend/app/services/metals/yahoo_fx.py

4. Alpha Vantage (Optional)

• High-quality historical data
• Requires free API key
• Limited to 5 requests/minute (free tier)
• Quaternary backup

File: backend/app/streaming/alpha_hub.py

5. BullionVault (Optional)

• Real-time spot prices
• Bid/ask spreads
• Requires scraping or API key

File: backend/app/services/metals/bullionvault_service.py

Data Provider Fallback Chain

1. GoldPrice.org (live spot)
   ↓ (if fails)
2. yfinance (GC=F futures)
   ↓ (if fails)
3. Yahoo Finance REST
   ↓ (if fails)
4. Alpha Vantage (if API key set)
   ↓ (if fails)
5. Local Simulator (fallback)

Configuration:

# backend/.env
DATA_PROVIDER=auto  # Auto-selects best available
# Options: auto | goldprice | yfinance | yahoo | alphavantage | simulator

ALPHA_VANTAGE_API_KEY=your_key_here  # Optional

Alternative Data Feeds

MetaTrader 5 Integration

Purpose: Stream real-time data from MT5 terminal

Requirements:

• MT5 terminal installed
• MetaTrader5 Python package
• Active broker connection

Configuration:

DATA_PROVIDER=metatrader

# Optional MT5 settings
MT5_LOGIN=12345678
MT5_PASSWORD=yourpassword
MT5_SERVER=YourBroker-Live

File: backend/app/streaming/metatrader_feed.py

CSV Replay Feed

Purpose: Replay historical data from CSV/Parquet files

Use Cases:

• Backtesting
• Training
• Offline development
• Consistent testing data

Configuration:

DATA_PROVIDER=csv_replay

# Data location
CSV_DATA_DIR=data/parquet/live/
CSV_SYMBOL=XAUUSD
CSV_TIMEFRAME=1m

File: backend/app/streaming/csv_feed.py

Data Format:

data/parquet/live/XAUUSD_1m.parquet
Columns: timestamp, open, high, low, close, volume

---

🚀 Migration Scripts

Database Migrations

Indicator AI Tables Migration

Purpose: Add indicator preferences and AI plan tables

File: backend/migrate_indicator_ai_tables.py

Run:

cd backend
python migrate_indicator_ai_tables.py

Creates:

• indicator_preferences table
• trading_plans table (if not exists)
• Indexes for performance

Journal Tables Migration

Purpose: Add trading journal tables

File: backend/migrate_journal_tables.py

Run:

cd backend
python migrate_journal_tables.py

Creates:

• trading_plans table
• manual_trades table
• journal_entries table
• decision_logs table
• weekly_plans table
• Foreign key relationships
• Indexes

---

🎯 Usage Workflows

Daily Workflow (Trading Companion Mode)

Morning Routine:

1. Generate AI daily plan (/api/ai/daily-plan)
2. Review plan in DailyTradingPlan component
3. Adjust levels based on overnight news
4. Set up alerts for key levels
5. Open external broker platform (MT5, cTrader, etc.)

During Trading: 6. Monitor live charts in platform 7. Get AI scenario analysis for specific setups 8. Execute trades on external broker 9. Log trades via ManualTradeLogger component 10. Link trades to daily plan

End of Day: 11. Import trades from broker (auto-sync or CSV) 12. Create journal entry with reflections 13. Review plan adherence 14. Calculate actual vs planned performance 15. Note lessons learned

Weekly Review: 16. Create weekly plan for next week 17. Review all daily plans 18. Analyze DecisionLog (AI accuracy) 19. Identify patterns in performance 20. Adjust strategy based on results

---

📈 Performance Tracking

Key Metrics

Plan Adherence:

• % of trades following daily plan
• Deviation from planned entry/exit
• Risk rule compliance

AI Accuracy:

• AI recommendation vs actual outcome
• Confidence calibration
• Model comparison (Claude vs GPT-4)

Trading Performance:

• Win rate
• Profit factor
• Sharpe ratio
• Max drawdown
• Average R-multiple

Behavioral Analysis:

• Emotional state correlation with P&L
• Best/worst trading times
• Setup success rates
• Revenge trading detection

---

🔐 Security Considerations

API Key Management

Never Commit:

# Add to .gitignore
backend/.env
backend/app/config/secrets.py
**/credentials.json

Environment Variables:

• OPENROUTER_API_KEY - AI service
• ALPHA_VANTAGE_API_KEY - Market data (optional)
• MT5_PASSWORD - Broker connection (if used)
• OANDA_API_KEY - Broker API (if used)

Broker Credentials:

• Store encrypted in database
• Never log in plaintext
• Use app-specific API keys (not account password)
• Limit API permissions to read-only when possible

---

🧪 Testing

Test Scripts

# Test OpenRouter AI
python backend/test_openrouter.py

# Test improved prompts
python backend/test_improved_prompts.py

# Test position metrics with indicators
python backend/tests/test_position_metrics_indicators.py

# Test Phase 1 API endpoints
python backend/tests/test_phase1_api.py

---

📝 Future Enhancements

Planned Features

• Multi-account support
• Trade execution via broker API (not just logging)
• Automated strategy execution based on AI signals
• Social trading (share plans with community)
• Mobile app for trade logging
• Voice journaling
• Video trade review playback
• AI-powered pattern recognition training
• Correlation analysis with other markets
• Sentiment analysis from social media

---

📚 Related Documentation

• AI Features - AI capabilities and configuration
• Real Data Integration - Market data sources
• Enhancement Summary - All features overview
• Setup Notes - Installation and configuration

---

Status: ✅ Phase 3 Complete Version: 3.0 Last Updated: November 2025