# Contexto del Proyecto - Trading Platform

## Identificación

| Campo | Valor |
|-------|-------|
| **Nombre** | Trading Platform - Trading Platform |
| **Código** | trading-platform |
| **Estado** | En Desarrollo (MVP + Fase 2) |
| **Creado** | 2025-12-05 |
| **Actualizado** | 2025-12-12 |
| **Fase Actual** | Fase 1 - MVP (expandido) + Trading Execution |

---

## Descripción

Trading Platform es una plataforma integral de gestión de inversiones asistida por inteligencia artificial, similar a Trade Republic pero potenciada con IA. Combina:

- **Money Manager con IA**: Agentes automáticos (Atlas, Orion, Nova) con diferentes perfiles de riesgo que operan en nombre del usuario
- **Plataforma Educativa**: Cursos de trading con gamificación
- **TradingView Clone con ML**: Charts profesionales con indicadores predictivos del modelo ML
- **Copiloto de Trading (LLM)**: Agente conversacional que interpreta señales y sugiere estrategias
- **Portfolio Manager**: Gestión de carteras a largo plazo con rebalanceo automático
- **Sistema SaaS**: Suscripciones, pagos con Stripe, wallets internos

---

## Visión

> "Ser la plataforma de trading más accesible e inteligente de Latinoamérica, democratizando el acceso a herramientas de inversión profesional"

## Misión

Empoderar a personas a invertir de manera inteligente, combinando educación de calidad con herramientas de IA de nivel institucional para optimizar sus decisiones de inversión.

---

## Activos Existentes

### TradingAgent (ML Engine)

**Ubicación:** `[LEGACY: apps/ml-engine - migrado desde TradingAgent]`

Sistema de ML ya desarrollado con:
- **Modelos XGBoost/GRU/Transformer** para predicción de precios
- **RangePredictor**: Predicción de rangos (85.9% accuracy)
- **TPSLClassifier**: Clasificación TP/SL (0.94 AUC)
- **AMDDetector**: Detección de fases de mercado (Accumulation/Manipulation/Distribution)
- **SignalGenerator**: Generación de señales en formato JSON
- **10+ años de datos históricos**: XAUUSD, EURUSD, GBPUSD, USDJPY
- **API FastAPI** + Dashboard real-time

---

## Stack Tecnológico

| Capa | Tecnología |
|------|------------|
| **Frontend** | React 18 + TypeScript + Vite + Tailwind CSS |
| **Backend** | Express.js + TypeScript |
| **Database** | PostgreSQL 15+ |
| **Cache** | Redis 7 |
| **ML Engine** | Python 3.11 + FastAPI + XGBoost (TradingAgent) |
| **LLM** | Claude API / OpenAI API |
| **Pagos** | Stripe |
| **Auth** | JWT + Passport + OAuth (Google, Facebook, X, Apple, GitHub) |
| **Broker** | MT4 (EBC Financial Group) via EA Bridge |
| **Data Provider** | Polygon.io / Massive.com (5 req/min) |
| **MT4 Gateway** | Python/FastAPI (puerto 8090) |

---

## Estructura del Proyecto (9 Épicas)

### Épicas MVP (Fase 1)

| Código | Nombre | SP | Estado | Descripción |
|--------|--------|-----|--------|-------------|
| OQI-001 | Fundamentos y Auth | 50 | ✅ Completado | OAuth, JWT, 2FA |
| OQI-002 | Módulo Educativo | 45 | Parcial | Cursos, quizzes |
| OQI-003 | Trading y Charts | 55 | En Desarrollo | TradingView clone |
| OQI-004 | Cuentas de Inversión | 57 | Pendiente | Money Manager |
| OQI-005 | Pagos y Stripe | 40 | Parcial | Suscripciones |
| OQI-006 | Señales ML | 40 | ML Engine listo (70%) | Predicciones AMD, Range, TPSL |

### Épicas Fase 2 (Avanzadas)

| Código | Nombre | SP | Estado | Descripción |
|--------|--------|-----|--------|-------------|
| **OQI-007** | **LLM Strategy Agent** | **55** | **Planificado (20%)** | Copiloto de trading IA |
| **OQI-008** | **Portfolio Manager** | **65** | **Planificado (10%)** | Gestión de carteras |
| **OQI-009** | **Trading Execution (MT4 Gateway)** | **45** | **En Desarrollo (30%)** | Multi-agente MT4 execution |

**Total: 452 Story Points**

---

## Productos de Inversión (Agentes IA)

| Agente | Perfil | Target Mensual | Max Drawdown | Capital Inicial | Puerto MT4 |
|--------|--------|----------------|--------------|-----------------|------------|
| **Atlas** | Conservador | 3-5% | 5% | $200 USD | 8081 |
| **Orion** | Moderado | 5-10% | 10% | $500 USD | 8082 |
| **Nova** | Agresivo | 10-15% | 15% | $1,000 USD | 8083 |

### Estrategias por Agente (Forex/Metales)

- **Atlas**: AMD Strategy conservador (solo XAUUSD) - 1% risk/trade, max 1 posición
- **Orion**: ICT Strategy moderado (EURUSD, GBPUSD) - 1.5% risk/trade, max 2 posiciones
- **Nova**: Mixed Strategy agresivo (XAUUSD, EURUSD, GBPUSD, USDJPY) - 2% risk/trade, max 3 posiciones

### Instrumentos Iniciales

| Instrumento | Tipo | Spread Típico | Agentes |
|-------------|------|---------------|---------|
| XAUUSD | Metal (Oro) | 20-50 pips | Atlas, Nova |
| EURUSD | Forex Major | 0.5-2 pips | Orion, Nova |
| GBPUSD | Forex Major | 1-3 pips | Orion, Nova |
| USDJPY | Forex Major | 0.5-2 pips | Nova |

---

## Planes de Suscripción

| Plan | Precio | Features Clave |
|------|--------|----------------|
| **Free** | $0/mes | Paper trading, cursos básicos, 3 señales/día |
| **Basic** | $19/mes | Trading real, 10 señales/día, 1 agente (Atlas) |
| **Pro** | $49/mes | Señales ilimitadas, 3 agentes, LLM copiloto |
| **Premium** | $99/mes | API access, Portfolio Manager, soporte dedicado |

---

## Funcionalidades Clave

### 1. TradingView Clone con ML
- Charts profesionales (Lightweight Charts)
- Indicadores técnicos tradicionales
- **Indicadores predictivos ML** superpuestos
- Señales de entrada/salida visualizadas
- Alertas personalizables

### 2. Money Manager (Agentes)
- Fondear cuenta de inversión
- Seleccionar agente por perfil de riesgo
- Trading automático 24/7
- Dashboard de rendimiento
- Solicitar retiros
- Distribución de ganancias (80% reinversión / 20% usuario)

### 3. LLM Copiloto de Trading
- Chat conversacional
- Interpretación de señales ML en lenguaje natural
- Sugerencias de estrategias personalizadas
- Explicación de decisiones de trading
- Modo proactivo (alertas)

### 4. Portfolio Manager
- Cuestionario de perfil de riesgo
- Asignación automática entre agentes
- Rebalanceo automático
- Proyecciones Monte Carlo
- Metas de inversión
- Reportes fiscales

---

## Arquitectura de Alto Nivel

```
┌─────────────────────────────────────────────────────────────────┐
│                      FRONTEND (React :5173)                      │
│   Auth │ Education │ Trading │ Investment │ LLM Chat │ Admin    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                    BACKEND (Express.js :3001)                    │
│   API Gateway │ WebSocket │ ML Integration │ Payments │ Admin   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
    ┌──────────────┬──────────┼───────────┬─────────────┐
    │              │          │           │             │
┌───▼────┐   ┌─────▼─────┐ ┌──▼───┐ ┌────▼────┐  ┌─────▼─────┐
│ML ENGINE│   │DATA SERVICE│ │ LLM  │ │MT4 GATE-│  │   DB +    │
│ :8000  │   │   :8001   │ │AGENT │ │  WAY    │  │  CACHE    │
│-XGBoost│   │-Polygon API│ │:8002 │ │ :8090   │  │PostgreSQL │
│-AMD    │   │-Spreads   │ │-Claude│ │-Router  │  │  Redis    │
│-TPSL   │   │-OHLCV     │ │-GPT-4 │ │-Risk Mgr│  │           │
└───┬────┘   └─────┬─────┘ └──┬───┘ └────┬────┘  └───────────┘
    │              │          │          │
    └──────────────┴──────────┴──────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
        ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
        │MT4 TERMINAL│   │MT4 TERMINAL│   │MT4 TERMINAL│
        │  Agent 1   │   │  Agent 2   │   │  Agent 3   │
        │  (Atlas)   │   │  (Orion)   │   │   (Nova)   │
        │  :8081     │   │  :8082     │   │   :8083    │
        │EA Bridge   │   │EA Bridge   │   │ EA Bridge  │
        └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
              │               │               │
              └───────────────┼───────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   EBC FINANCIAL   │
                    │   GROUP (BROKER)  │
                    │  MT4 Demo Server  │
                    └───────────────────┘
```

---

## Documentación Clave

| Documento | Ubicación |
|-----------|-----------|
| Mapa de Documentación | `docs/_MAP.md` |
| Arquitectura Unificada | `docs/01-arquitectura/ARQUITECTURA-UNIFICADA.md` |
| **Arquitectura Multi-Agente MT4** | `docs/01-arquitectura/ARQUITECTURA-MULTI-AGENTE-MT4.md` |
| Integración TradingAgent | `docs/01-arquitectura/INTEGRACION-TRADINGAGENT.md` |
| **INT-MT4-001 Gateway Service** | `docs/90-transversal/integraciones/INT-MT4-001-gateway-service.md` |
| **MT4 Gateway Inventory** | `docs/90-transversal/inventarios/MT4_GATEWAY_INVENTORY.yml` |
| **Matriz Dependencias Trading** | `docs/90-transversal/inventarios/MATRIZ-DEPENDENCIAS-TRADING.yml` |
| **ADR-002 MVP Trading** | `docs/97-adr/ADR-002-MVP-OPERATIVO-TRADING.md` |
| **Setup MT4 Trading** | `docs/90-transversal/setup/SETUP-MT4-TRADING.md` |
| Épicas MVP | `docs/02-definicion-modulos/OQI-001 a OQI-009` |
| Master Inventory | `orchestration/inventarios/MASTER_INVENTORY.yml` |

---

## Métricas del Proyecto

| Métrica | Target | Actual |
|---------|--------|--------|
| Story Points | 452 | 95 (21%) |
| Épicas documentadas | 9 | 9 (100%) |
| Épicas completadas | 9 | 1 (11%) |
| Épicas en desarrollo | - | 3 (OQI-003, OQI-006, OQI-009) |
| Servicios Python | 4 | 4 (ML, Data, MT4 GW, LLM) |
| Documentos técnicos | 200+ | 200+ |
| Cobertura tests | 80% | TBD |

---

## Roadmap

### Q1 2026
- Fase 1 completa (OQI-001 a OQI-006)
- MVP funcional

### Q2 2026
- Fase 2 (OQI-007 y OQI-008)
- LLM Agent + Portfolio Manager

### Q3 2026
- Beta pública
- Onboarding de usuarios

### Q4 2026
- Producción completa
- Expansión de features

---

## Servicios del Ecosistema de Trading

| Servicio | Puerto | Tipo | Estado | Función |
|----------|--------|------|--------|---------|
| ML Engine | 8000 | Python/FastAPI | Listo (70%) | Predicciones AMD, Range, TPSL |
| Data Service | 8001 | Python/FastAPI | Parcial (40%) | Datos Polygon/Massive, spreads |
| LLM Agent | 8002 | Python/FastAPI | Planificado (20%) | Análisis conversacional |
| MT4 Gateway | 8090 | Python/FastAPI | En Desarrollo (30%) | Router multi-agente MT4 |
| MT4 Agent 1 (Atlas) | 8081 | EA Bridge | Configurado | Trading conservador XAUUSD |
| MT4 Agent 2 (Orion) | 8082 | EA Bridge | Configurado | Trading moderado Forex |
| MT4 Agent 3 (Nova) | 8083 | EA Bridge | Configurado | Trading agresivo multi-par |

### Conexiones Externas

| Servicio | Tipo | Estado | Rate Limit |
|----------|------|--------|------------|
| Polygon.io / Massive.com | Data Provider | ✅ Verificado | 5 req/min |
| EBC Financial Group | Broker MT4 | ✅ Configurado | - |
| Claude API | LLM | Planificado | - |
| Stripe | Pagos | Parcial | - |

---

*Contexto del proyecto - Sistema NEXUS*
*Última actualización: 2025-12-12*