# System Architecture: Indicator Preferences & AI Plans

## 🏗️ Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                        FRONTEND                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          User Interface Components                      │ │
│  │                                                         │ │
│  │  ┌───────────────────┐    ┌──────────────────────┐   │ │
│  │  │ IndicatorPreferences│    │ DailyTradingPlan    │   │ │
│  │  │   Component        │    │   Component          │   │ │
│  │  │                    │    │                      │   │ │
│  │  │ • Select indicators│    │ • [AI Plan] button  │   │ │
│  │  │ • Set priorities   │    │ • Plan form          │   │ │
│  │  │ • Enable/disable   │    │ • Edit fields        │   │ │
│  │  │ • Add notes        │    │ • Save plan          │   │ │
│  │  └─────────┬──────────┘    └──────────┬───────────┘   │ │
│  │            │                           │               │ │
│  │            └───────────┬───────────────┘               │ │
│  │                        │                               │ │
│  │  ┌─────────────────────▼─────────────────────────┐   │ │
│  │  │         API Service (api.ts)                   │   │ │
│  │  │                                                │   │ │
│  │  │  settingsApi.getIndicatorPreferences()        │   │ │
│  │  │  settingsApi.createIndicatorPreference()      │   │ │
│  │  │  aiApi.generateTradingPlan()                  │   │ │
│  │  │  aiApi.getPlanHistory()                       │   │ │
│  │  └────────────────────┬───────────────────────────┘   │ │
│  └─────────────────────────┼──────────────────────────────┘ │
└────────────────────────────┼─────────────────────────────────┘
                             │ HTTP Requests
                             │ (REST API)
┌────────────────────────────▼─────────────────────────────────┐
│                        BACKEND                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │               FastAPI Routes                            │  │
│  │                                                         │  │
│  │  ┌─────────────────────┐    ┌────────────────────┐   │  │
│  │  │ /settings/indicators│    │ /ai/generate-plan  │   │  │
│  │  │  /preferences       │    │ /ai/plans/history  │   │  │
│  │  │                     │    │ /ai/plans/feedback │   │  │
│  │  │  GET, POST,         │    │                    │   │  │
│  │  │  PUT, DELETE        │    │  POST, GET         │   │  │
│  │  └──────────┬──────────┘    └─────────┬──────────┘   │  │
│  └─────────────┼─────────────────────────┼───────────────┘  │
│                │                         │                   │
│  ┌─────────────▼─────────────────────────▼───────────────┐  │
│  │                Service Layer                           │  │
│  │                                                        │  │
│  │  ┌──────────────────────┐   ┌──────────────────────┐ │  │
│  │  │   AIPlanService      │   │  OpenRouterService   │ │  │
│  │  │                      │   │                      │ │  │
│  │  │ generate_plan()      │◄──┤ generate_trading_    │ │  │
│  │  │ get_plan_history()   │   │   plan()             │ │  │
│  │  │ submit_feedback()    │   │                      │ │  │
│  │  │                      │   │ Claude 3.5 Sonnet    │ │  │
│  │  └──────────┬───────────┘   └──────────────────────┘ │  │
│  └─────────────┼─────────────────────────────────────────┘  │
│                │                                             │
│  ┌─────────────▼─────────────────────────────────────────┐  │
│  │              Database Layer (SQLAlchemy)              │  │
│  │                                                       │  │
│  │  ┌──────────────────────┐   ┌─────────────────────┐ │  │
│  │  │ UserIndicator        │   │  AIPlanGeneration   │ │  │
│  │  │   Preferences        │   │                     │ │  │
│  │  │                      │   │                     │ │  │
│  │  │ • indicator_name     │   │ • market_bias       │ │  │
│  │  │ • enabled            │   │ • confidence        │ │  │
│  │  │ • priority           │   │ • entry_zone        │ │  │
│  │  │ • parameters         │   │ • target_price      │ │  │
│  │  │ • notes              │   │ • stop_loss         │ │  │
│  │  └──────────┬───────────┘   └─────────┬───────────┘ │  │
│  └─────────────┼─────────────────────────┼─────────────┘  │
└────────────────┼─────────────────────────┼─────────────────┘
                 │                         │
┌────────────────▼─────────────────────────▼─────────────────┐
│                    PostgreSQL Database                       │
│                                                              │
│  ┌─────────────────────────┐  ┌─────────────────────────┐  │
│  │ user_indicator_          │  │ ai_plan_generations     │  │
│  │   preferences            │  │                         │  │
│  └──────────────────────────┘  └─────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                              
┌──────────────────────────────────────────────────────────────┐
│                   External Services                           │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │           OpenRouter API                               │  │
│  │           (Claude 3.5 Sonnet)                         │  │
│  │                                                       │  │
│  │  Receives: Trading plan generation prompt            │  │
│  │  Returns: JSON with plan details                     │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
```

## 🔄 Data Flow: AI Plan Generation

```
1. USER ACTION
   │
   ├─► User clicks "AI Plan" button
   │
   └─► Frontend: DailyTradingPlan.tsx
       │
       └─► handleGenerateWithAI()

2. API CALL
   │
   ├─► Frontend: api.ts
   │   └─► aiApi.generateTradingPlan({
   │         current_price: 2025.50,
   │         risk_tolerance: "moderate",
   │         use_indicator_preferences: true
   │       })
   │
   └─► HTTP POST /ai/generate-plan

3. BACKEND PROCESSING
   │
   ├─► Backend: ai.py
   │   └─► generate_trading_plan()
   │
   ├─► Backend: ai_plan_service.py
   │   └─► AIPlanService.generate_plan()
   │       │
   │       ├─► Load user's indicator preferences from DB
   │       │   (UserIndicatorPreferences table)
   │       │
   │       ├─► Build comprehensive AI prompt
   │       │   • Include current price
   │       │   • Include user's preferred indicators
   │       │   • Include indicator priorities
   │       │   • Include risk tolerance
   │       │
   │       └─► Call OpenRouter service
   │
   ├─► Backend: openrouter.py
   │   └─► OpenRouterService.generate_trading_plan()
   │       │
   │       ├─► Send to Claude 3.5 Sonnet
   │       │   POST https://openrouter.ai/api/v1/chat/completions
   │       │
   │       └─► Receive JSON response with plan
   │
   ├─► Backend: ai_plan_service.py
   │   └─► Parse AI response
   │       │
   │       └─► Save to database
   │           (AIPlanGeneration table)
   │
   └─► Return AIPlanGenerationResponse

4. FRONTEND UPDATE
   │
   ├─► Frontend: DailyTradingPlan.tsx
   │   └─► handleGenerateWithAI() continues
   │       │
   │       ├─► Map AI response to plan structure
   │       ├─► Update local state with new plan
   │       ├─► Switch to edit mode
   │       └─► Show success alert with confidence
   │
   └─► User sees populated plan ready for review
```

## 🗂️ File Structure

```
gold-trading-simulator/
│
├── backend/
│   ├── app/
│   │   ├── models/
│   │   │   └── models.py                    [+2 models]
│   │   ├── schemas/
│   │   │   └── schemas.py                   [+10 schemas]
│   │   ├── api/
│   │   │   ├── ai.py                        [+3 endpoints]
│   │   │   └── settings_api.py              [+5 endpoints]
│   │   └── services/
│   │       ├── ai_plan_service.py           [NEW FILE]
│   │       └── openrouter.py                [+1 method]
│   └── migrate_indicator_ai_tables.py       [NEW FILE]
│
├── frontend/
│   └── src/
│       ├── components/
│       │   ├── IndicatorPreferences.tsx     [NEW FILE]
│       │   ├── DailyTradingPlan.tsx         [ENHANCED]
│       │   └── SettingsPanel.tsx            [UPDATED]
│       └── services/
│           └── api.ts                       [+8 methods]
│
└── docs/
    ├── INDICATOR_AI_PLAN_IMPLEMENTATION.md  [NEW FILE]
    ├── QUICKSTART_AI_PLANS.md              [NEW FILE]
    └── IMPLEMENTATION_SUMMARY.md           [NEW FILE]
```

## 🎯 Component Relationships

```
┌──────────────────────────────────────────────────┐
│              App.tsx (Main)                      │
│                                                  │
│  ┌────────────────────────────────────────────┐ │
│  │         Settings Tab                       │ │
│  │                                            │ │
│  │  ┌──────────────────────────────────────┐ │ │
│  │  │      SettingsPanel                   │ │ │
│  │  │                                      │ │ │
│  │  │  ┌────────────────────────────────┐ │ │ │
│  │  │  │   IndicatorPreferences         │ │ │ │
│  │  │  │                                │ │ │ │
│  │  │  │  • Shows 10 indicators         │ │ │ │
│  │  │  │  • Priority sliders            │ │ │ │
│  │  │  │  • Enable/disable toggles      │ │ │ │
│  │  │  │  • Save button                 │ │ │ │
│  │  │  └────────────────────────────────┘ │ │ │
│  │  └──────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────┘ │
│                                                  │
│  ┌────────────────────────────────────────────┐ │
│  │         Daily Helper Tab                   │ │
│  │                                            │ │
│  │  ┌──────────────────────────────────────┐ │ │
│  │  │     DailyTradingPlan                 │ │ │
│  │  │                                      │ │ │
│  │  │  ┌─────────────┐   ┌──────────┐   │ │ │
│  │  │  │ [AI Plan] ✨│   │ [Edit]  │   │ │ │
│  │  │  └──────┬──────┘   └──────────┘   │ │ │
│  │  │         │                          │ │ │
│  │  │         └──► Calls AI API          │ │ │
│  │  │              Populates form        │ │ │
│  │  └──────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```

## 🔐 Security Layer

```
┌───────────────────────────────────────┐
│      Environment Variables             │
│                                       │
│  OPENROUTER_API_KEY (secret)         │
│  DATABASE_URL (connection string)    │
└───────────────┬───────────────────────┘
                │
┌───────────────▼───────────────────────┐
│      Backend Security                 │
│                                       │
│  • API key not exposed to frontend   │
│  • User-specific data isolation       │
│  • Input validation on all endpoints  │
│  • SQLAlchemy ORM (SQL injection      │
│    protection)                        │
└───────────────┬───────────────────────┘
                │
┌───────────────▼───────────────────────┐
│      Database Security                │
│                                       │
│  • User-scoped queries                │
│  • Proper indexing                    │
│  • Transaction management             │
└───────────────────────────────────────┘
```

---

## 📊 Key Metrics

```
┌─────────────────────────────────────────────┐
│         Implementation Metrics              │
├─────────────────────────────────────────────┤
│  Backend Files Created:        7            │
│  Frontend Files Created:       4            │
│  Documentation Files:          3            │
│  Total Lines of Code:          ~2,500       │
│  New API Endpoints:            8            │
│  Database Tables:              2            │
│  Components:                   2            │
│  Services:                     1            │
└─────────────────────────────────────────────┘
```

This visual architecture guide completes the implementation documentation!