================================================================================
AGENT 5 - TRADE COMMAND ARCHITECTURE
================================================================================

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER CLI INPUT                                  │
│                         tli trade ml submit ...                              │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           tli/src/main.rs                                    │
│                         (Clap CLI Parsing)                                   │
│                                                                              │
│  #[derive(Parser)]                                                           │
│  enum Commands {                                                             │
│      Trade {                                                                 │
│          #[command(flatten)]                                                 │
│          trade_args: TradeArgs,  ◄─── NEW: Using TradeArgs                 │
│      }                                                                       │
│  }                                                                           │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    tli/src/main.rs (Match Handler)                           │
│                                                                              │
│  Commands::Trade { trade_args } => {                                         │
│      let jwt_token = load_jwt_token(...).await?;                            │
│      return execute_trade_command(                                           │
│          trade_args,                ◄─── NEW: Clean routing                │
│          &cli.api_gateway_url,                                              │
│          &jwt_token                                                          │
│      ).await;                                                                │
│  }                                                                           │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                  tli/src/commands/trade.rs (NEW MODULE)                      │
│                       (Routing Layer)                                        │
│                                                                              │
│  pub struct TradeArgs {                                                      │
│      pub command: TradeCommand,                                              │
│  }                                                                           │
│                                                                              │
│  pub enum TradeCommand {                                                     │
│      Ml(TradeMlArgs),  ◄─── Currently: ML only                             │
│      // Future: Manual, Modify, Cancel                                      │
│  }                                                                           │
│                                                                              │
│  pub async fn execute_trade_command(...) -> Result<()> {                    │
│      match args.command {                                                    │
│          TradeCommand::Ml(ml_args) =>                                        │
│              execute_trade_ml_command(ml_args, ...).await,                  │
│      }                                                                       │
│  }                                                                           │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                  tli/src/commands/trade_ml.rs (Agent 1)                      │
│                         (ML Trading Logic)                                   │
│                                                                              │
│  pub struct TradeMlArgs {                                                    │
│      pub command: TradeMlCommand,                                            │
│  }                                                                           │
│                                                                              │
│  pub enum TradeMlCommand {                                                   │
│      Submit { ... },      ◄─── Submit ML order                             │
│      Predictions { ... }, ◄─── View ML prediction history                  │
│      Performance { ... }, ◄─── View ML model performance                   │
│  }                                                                           │
│                                                                              │
│  pub async fn execute_trade_ml_command(...) -> Result<()> {                 │
│      args.execute(api_gateway_url, jwt_token).await                         │
│  }                                                                           │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         API Gateway (gRPC)                                   │
│                         http://localhost:50051                               │
│                                                                              │
│  - JWT Authentication                                                        │
│  - Rate Limiting                                                             │
│  - Audit Logging                                                             │
│  - Service Routing                                                           │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       Trading Service (gRPC)                                 │
│                         http://localhost:50052                               │
│                                                                              │
│  - ML Ensemble Voting                                                        │
│  - Order Submission                                                          │
│  - Prediction Storage                                                        │
│  - Performance Metrics                                                       │
└─────────────────────────────────────────────────────────────────────────────┘

================================================================================
MODULE REGISTRATION (commands/mod.rs)
================================================================================

pub mod trade;        ◄─── NEW: Trade routing module
pub mod trade_ml;     ◄─── Existing: ML logic module

pub use trade::{TradeArgs, execute_trade_command};
pub use trade_ml::{TradeMlArgs, execute_trade_ml_command};

================================================================================
AGENT COORDINATION
================================================================================

Agent 1: Implements trade_ml.rs (ML trading logic)
         ├─ Submit ML orders
         ├─ View predictions
         └─ View performance

Agent 5: Implements trade.rs (routing layer) ◄─── YOU ARE HERE
         ├─ Routes to trade_ml.rs
         ├─ Handles JWT tokens
         └─ Integrates with main.rs

Agent 2: Implements format_ml_order_submission() (rich terminal output)
Agent 3: Implements format_ml_predictions() (rich terminal output)
Agent 4: Implements format_ml_performance() (rich terminal output)

================================================================================
FUTURE EXTENSIBILITY
================================================================================

pub enum TradeCommand {
    Ml(TradeMlArgs),              ◄─── Phase 1: ML Trading (CURRENT)
    Manual(ManualOrderArgs),      ◄─── Phase 2: Manual orders
    Modify(ModifyOrderArgs),      ◄─── Phase 3: Order modifications
    Cancel(CancelOrderArgs),      ◄─── Phase 4: Order cancellations
    Portfolio(PortfolioArgs),     ◄─── Phase 5: Portfolio operations
}

================================================================================
KEY ARCHITECTURAL BENEFITS
================================================================================

✅ Separation of Concerns:
   - trade.rs = routing
   - trade_ml.rs = ML logic
   - main.rs = CLI parsing

✅ Extensibility:
   - Easy to add new TradeCommand variants
   - No changes to main.rs needed for new subcommands

✅ Consistency:
   - Follows same pattern as tune, auth, agent commands
   - Predictable structure for developers

✅ Testability:
   - Each module can be tested independently
   - Clear boundaries for unit tests

✅ Clean Imports:
   - main.rs imports from commands::trade
   - No deep nesting or inline definitions

================================================================================