rckrdmrd
c1b5081208
ML Engine Updates: - Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records - Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence) - Backtest results: +176.71R profit with aggressive_filter strategy Documentation Consolidation: - Created docs/99-analisis/_MAP.md index with 13 new analysis documents - Consolidated inventories: removed duplicates from orchestration/inventarios/ - Updated ML_INVENTORY.yml with BTCUSD metrics and training results - Added execution reports: FASE11-BTCUSD, correction issues, alignment validation Architecture & Integration: - Updated all module documentation with NEXUS v3.4 frontmatter - Fixed _MAP.md indexes across all folders - Updated orchestration plans and traces Files: 229 changed, 5064 insertions(+), 1872 deletions(-) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
897 lines
38 KiB
Markdown
897 lines
38 KiB
Markdown
---
|
|
id: "DIAGRAMA-INTEGRACIONES"
|
|
title: "Diagrama de Integraciones - Trading Platform"
|
|
type: "Documentation"
|
|
project: "trading-platform"
|
|
version: "1.0.0"
|
|
updated_date: "2026-01-04"
|
|
---
|
|
|
|
# Diagrama de Integraciones - Trading Platform
|
|
|
|
**Version:** 1.0.0
|
|
**Fecha:** 2025-12-05
|
|
**Autor:** Agente de Documentacion y Planificacion
|
|
**Estado:** Aprobado
|
|
|
|
---
|
|
|
|
## 1. Resumen Ejecutivo
|
|
|
|
Este documento detalla todos los flujos de integracion entre componentes del sistema Trading Platform, incluyendo:
|
|
- **Flujos de datos** entre servicios
|
|
- **APIs y endpoints** disponibles
|
|
- **Eventos y webhooks** para comunicacion asincrona
|
|
- **Protocolos** utilizados (REST, WebSocket, gRPC)
|
|
|
|
---
|
|
|
|
## 2. Arquitectura de Integracion Global
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ FRONTEND LAYER │
|
|
│ React 18 + TypeScript + Vite │
|
|
│ │
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────┐│
|
|
│ │ Auth UI │ │ Education │ │ Trading │ │ Investment │ │ LLM ││
|
|
│ │ Pages │ │ Platform │ │ Charts │ │ Dashboard │ │ Chat ││
|
|
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └───┬────┘│
|
|
│ │ │ │ │ │ │
|
|
│ └────────────────┴────────────────┴────────────────┴────────────┘ │
|
|
│ │ │
|
|
│ REST + WebSocket │
|
|
└──────────────────────────────────────┼────────────────────────────────────────┘
|
|
│
|
|
┌──────────────────────────────────────▼────────────────────────────────────────┐
|
|
│ API GATEWAY │
|
|
│ Express.js + TypeScript │
|
|
│ Port: 3001 │
|
|
│ │
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────┐│
|
|
│ │ /auth │ │ /education │ │ /trading │ │/investment │ │ /agent ││
|
|
│ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ Routes ││
|
|
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └───┬────┘│
|
|
│ │ │ │ │ │ │
|
|
│ │ ┌───────┴────────────────┴────────────────┴───────┐ │ │
|
|
│ │ │ SHARED SERVICES │ │ │
|
|
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │
|
|
│ │ │ │ Redis │ │WebSocket │ │ Rate │ │ │ │
|
|
│ │ │ │ Client │ │ Server │ │ Limiter │ │ │ │
|
|
│ │ │ └──────────┘ └──────────┘ └──────────────┘ │ │ │
|
|
│ │ └─────────────────────────────────────────────────┘ │ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────────────┐ ┌────────────────┐│
|
|
│ │ Auth Service │ │ LLM Service ││
|
|
│ │ ┌────────────┐ │ │ Claude 3.5 ││
|
|
│ │ │ JWT, OAuth │ │ │ / GPT-4 ││
|
|
│ │ │ 2FA, RBAC │ │ │ + Tools ││
|
|
│ │ └────────────┘ │ └────────────────┘│
|
|
│ └──────────────────┘ │
|
|
└────────────────────┬──────────────────┬──────────────────┬───────────────────┘
|
|
│ │ │
|
|
┌───────────┼──────────────────┼──────────────────┼───────────┐
|
|
│ │ │ │ │
|
|
▼ ▼ ▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
|
|
│ PostgreSQL │ │ Redis │ │ ML Engine │ │ Data Service │ │ Stripe │
|
|
│ Primary │ │ Cache + │ │ FastAPI │ │ Python │ │ API │
|
|
│ Database │ │ Pub/Sub │ │ Port: 8000 │ │ Port: 8001 │ │ HTTPS │
|
|
│ Port: 5432 │ │Port:6379│ │ │ │ │ │ │
|
|
└─────────────┘ └─────────┘ └──────┬───────┘ └──────┬───────┘ └──────────┘
|
|
│ │
|
|
┌──────┴──────────────────┴──────┐
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────┐ ┌─────────────────────┐
|
|
│ Polygon.io API │ │ MetaAPI / MT4 │
|
|
│ Market Data │ │ Broker Integration │
|
|
│ HTTPS │ │ HTTPS + WebSocket │
|
|
└─────────────────┘ └─────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Flujos de Datos Criticos
|
|
|
|
### 3.1 Flujo de Inversion (Usuario → Wallet → Agente → MT4 → Trading)
|
|
|
|
```
|
|
┌──────────┐
|
|
│ USUARIO │ "Quiero invertir $1000 en Atlas (conservador)"
|
|
└────┬─────┘
|
|
│ POST /investment/accounts
|
|
▼
|
|
┌─────────────────┐
|
|
│ Backend Express │ 1. Verifica KYC aprobado
|
|
│ Investment │ 2. Valida saldo wallet >= $1000
|
|
│ Service │ 3. Crea registro en investment.accounts
|
|
└────┬────────────┘
|
|
│ SQL INSERT
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ accounts table:
|
|
│ investment │ - user_id
|
|
│ schema │ - product_id (Atlas)
|
|
└────┬────────────┘ - initial_balance: $1000
|
|
│ - status: pending_deposit
|
|
│
|
|
│ 4. Transferir desde wallet
|
|
▼
|
|
┌─────────────────┐
|
|
│ Financial │ wallet_transactions:
|
|
│ Schema │ - type: investment_deposit
|
|
└────┬────────────┘ - amount: -$1000
|
|
│ - status: completed
|
|
│
|
|
│ 5. Asignar trading agent
|
|
▼
|
|
┌─────────────────┐
|
|
│ Trading │ bots table:
|
|
│ Schema │ - name: "Atlas Conservative"
|
|
└────┬────────────┘ - strategy_id: 1
|
|
│ - status: active
|
|
│
|
|
│ 6. Conectar con broker
|
|
▼
|
|
┌─────────────────┐
|
|
│ Broker │ broker_accounts:
|
|
│ Integration │ - metaapi_account_id
|
|
│ Schema │ - balance: $1000
|
|
└────┬────────────┘ - equity: $1000
|
|
│
|
|
│ 7. Esperar señal ML
|
|
▼
|
|
┌─────────────────┐
|
|
│ ML Engine │ POST /signals
|
|
│ FastAPI │ Returns: {
|
|
└────┬────────────┘ "signal": "LONG",
|
|
│ "symbol": "EURUSD",
|
|
│ "entry": 1.0550,
|
|
│ "sl": 1.0500,
|
|
│ "tp": 1.0650
|
|
│ }
|
|
│
|
|
│ 8. Agent evalua señal
|
|
▼
|
|
┌─────────────────┐
|
|
│ Atlas Agent │ Risk check:
|
|
│ Python │ - Max position size: 1%
|
|
└────┬────────────┘ - Correlation check: OK
|
|
│ - Drawdown check: OK
|
|
│
|
|
│ 9. Ejecutar orden
|
|
▼
|
|
┌─────────────────┐
|
|
│ MetaAPI Client │ POST /accounts/{id}/trade
|
|
│ HTTP │ {
|
|
└────┬────────────┘ "actionType": "POSITION_TYPE_BUY",
|
|
│ "symbol": "EURUSD",
|
|
│ "volume": 0.01,
|
|
│ "stopLoss": 1.0500,
|
|
│ "takeProfit": 1.0650
|
|
│ }
|
|
│
|
|
│ 10. Confirmar ejecución
|
|
▼
|
|
┌─────────────────┐
|
|
│ MT4 Broker │ Order filled:
|
|
│ Server │ - Ticket: #123456789
|
|
└────┬────────────┘ - Entry: 1.05502 (slippage)
|
|
│ - Spread: 0.00003
|
|
│
|
|
│ 11. Log trade execution
|
|
▼
|
|
┌─────────────────┐
|
|
│ broker_integration
|
|
│ trade_execution │ - signal_id
|
|
│ table │ - broker_account_id
|
|
└────┬────────────┘ - entry_price: 1.05502
|
|
│ - pnl: 0 (open)
|
|
│
|
|
│ 12. Notificar usuario
|
|
▼
|
|
┌─────────────────┐
|
|
│ WebSocket │ Event: "trade_executed"
|
|
│ Server │ → Frontend
|
|
└────┬────────────┘ → Notification UI
|
|
│
|
|
▼
|
|
┌──────────┐
|
|
│ USUARIO │ "Trade ejecutado: EURUSD LONG @ 1.05502"
|
|
└──────────┘
|
|
```
|
|
|
|
**Protocolo:** REST (pasos 1-9, 11) + WebSocket (paso 12)
|
|
**Latencia Total:** ~2-5 segundos
|
|
|
|
---
|
|
|
|
### 3.2 Flujo de Predicciones (Data Service → PostgreSQL → ML Engine → Señales → Frontend)
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Polygon.io API │ GET /v2/aggs/ticker/C:EURUSD/range/5/minute/...
|
|
└────┬────────────┘
|
|
│ JSON Response
|
|
▼
|
|
┌─────────────────┐
|
|
│ Data Service │ 1. Parse OHLCV data
|
|
│ Python │ 2. Transform to internal format
|
|
└────┬────────────┘ 3. Bulk insert
|
|
│
|
|
│ SQL INSERT (batch 10k records)
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ market_data.ohlcv_5m:
|
|
│ market_data │ - ticker_id: 2 (EURUSD)
|
|
│ schema │ - timestamp: 2025-12-05 10:00
|
|
└────┬────────────┘ - open, high, low, close, volume
|
|
│
|
|
│ 4. Trigger: Calculate technical indicators
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ market_data.technical_indicators:
|
|
│ Function │ - sma_10, sma_20, sma_50
|
|
└────┬────────────┘ - rsi_14, macd, atr
|
|
│
|
|
│ 5. ML Engine scheduled job (every 15 min)
|
|
▼
|
|
┌─────────────────┐
|
|
│ ML Engine │ SELECT FROM market_data.ohlcv_5m
|
|
│ FastAPI │ WHERE timestamp > NOW() - INTERVAL '6 hours'
|
|
└────┬────────────┘
|
|
│ FeatureBuilder
|
|
▼
|
|
┌─────────────────┐
|
|
│ XGBoost Model │ Features (21):
|
|
│ GPU │ - volatility_10, volatility_20
|
|
└────┬────────────┘ - rsi, momentum, sma_ratios, etc.
|
|
│
|
|
│ 6. Predict delta_high, delta_low
|
|
▼
|
|
┌─────────────────┐
|
|
│ RangePredictor │ Prediction:
|
|
│ Python │ - predicted_high: +0.0042 (0.42%)
|
|
└────┬────────────┘ - predicted_low: -0.0031 (0.31%)
|
|
│ - confidence: 0.759
|
|
│
|
|
│ 7. TPSL Classifier
|
|
▼
|
|
┌─────────────────┐
|
|
│ TPSL Classifier│ prob_tp_first:
|
|
│ Model │ - RR 2:1 → 0.68
|
|
└────┬────────────┘ - RR 3:1 → 0.54
|
|
│
|
|
│ 8. Signal Generator
|
|
▼
|
|
┌─────────────────┐
|
|
│ SignalGenerator│ Signal:
|
|
│ Python │ {
|
|
└────┬────────────┘ "type": "LONG",
|
|
│ "entry": 1.0550,
|
|
│ "sl": 1.0500,
|
|
│ "tp": 1.0650,
|
|
│ "rr_ratio": 2.0,
|
|
│ "prob_tp": 0.68
|
|
│ }
|
|
│
|
|
│ SQL INSERT
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ ml_predictions.entry_signals:
|
|
│ ml_predictions │ - ticker_id: 2
|
|
│ schema │ - signal_timestamp
|
|
└────┬────────────┘ - entry, sl, tp
|
|
│
|
|
│ 9. Publish to Redis
|
|
▼
|
|
┌─────────────────┐
|
|
│ Redis Pub/Sub │ PUBLISH signals:EURUSD
|
|
│ │ { signal JSON }
|
|
└────┬────────────┘
|
|
│
|
|
│ 10. Backend subscribes
|
|
▼
|
|
┌─────────────────┐
|
|
│ Express │ Redis subscriber
|
|
│ WebSocket │ ON MESSAGE: broadcast to clients
|
|
│ Service │
|
|
└────┬────────────┘
|
|
│ WebSocket emit
|
|
▼
|
|
┌─────────────────┐
|
|
│ Frontend │ Event: "ml_signal_new"
|
|
│ React │ → Show notification
|
|
└────┬────────────┘ → Update chart overlay
|
|
│
|
|
▼
|
|
┌──────────┐
|
|
│ USUARIO │ "Nueva señal: EURUSD LONG con R:R 2:1"
|
|
└──────────┘
|
|
```
|
|
|
|
**Protocolo:** HTTP (Data Service → DB) + SQL (ML queries) + Redis Pub/Sub + WebSocket
|
|
**Frecuencia:** Cada 15 minutos
|
|
**Latencia Signal:** <2 segundos (desde insert en DB hasta frontend)
|
|
|
|
---
|
|
|
|
### 3.3 Flujo de Pagos (Usuario → Stripe → Webhook → Backend → Wallet)
|
|
|
|
```
|
|
┌──────────┐
|
|
│ USUARIO │ "Comprar plan Pro - $49/mes"
|
|
└────┬─────┘
|
|
│ POST /payments/checkout
|
|
▼
|
|
┌─────────────────┐
|
|
│ Backend Express │ 1. Crear Stripe customer (si no existe)
|
|
│ Payment │ 2. Crear Checkout Session
|
|
│ Service │
|
|
└────┬────────────┘
|
|
│ Stripe API call
|
|
▼
|
|
┌─────────────────┐
|
|
│ Stripe API │ POST /v1/checkout/sessions
|
|
│ HTTPS │ {
|
|
└────┬────────────┘ "mode": "subscription",
|
|
│ "line_items": [{ price: "price_pro" }],
|
|
│ "success_url": "https://app.trading.com/success",
|
|
│ "cancel_url": "https://app.trading.com/cancel"
|
|
│ }
|
|
│
|
|
│ Response: { url: "checkout.stripe.com/..." }
|
|
▼
|
|
┌─────────────────┐
|
|
│ Backend Express │ Return: { checkout_url }
|
|
│ │
|
|
└────┬────────────┘
|
|
│ 3. Redirect frontend
|
|
▼
|
|
┌─────────────────┐
|
|
│ Frontend │ window.location = checkout_url
|
|
│ React │
|
|
└────┬────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Stripe Hosted │ Usuario ingresa tarjeta
|
|
│ Checkout Page │ - Card number
|
|
└────┬────────────┘ - CVC, expiry
|
|
│ - Billing info
|
|
│
|
|
│ 4. Payment submitted
|
|
▼
|
|
┌─────────────────┐
|
|
│ Stripe │ Process payment
|
|
│ Payment Engine │ → Success
|
|
└────┬────────────┘
|
|
│
|
|
│ 5. Webhook trigger (async)
|
|
▼
|
|
┌─────────────────┐
|
|
│ Stripe │ POST https://api.trading.com/payments/webhook
|
|
│ Webhook │ Headers:
|
|
└────┬────────────┘ Stripe-Signature: t=...,v1=...
|
|
│ Body:
|
|
│ {
|
|
│ "type": "checkout.session.completed",
|
|
│ "data": { subscription_id, customer_id }
|
|
│ }
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Backend Express │ 6. Verify webhook signature
|
|
│ Webhook │ 7. Parse event type
|
|
│ Handler │
|
|
└────┬────────────┘
|
|
│ 8. Process subscription.created
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ financial.subscriptions:
|
|
│ financial │ - user_id
|
|
│ schema │ - stripe_subscription_id
|
|
└────┬────────────┘ - plan: "pro"
|
|
│ - status: "active"
|
|
│ - current_period_end
|
|
│
|
|
│ 9. Update user role
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ UPDATE public.users
|
|
│ public.users │ SET plan = 'pro'
|
|
└────┬────────────┘ WHERE id = user_id
|
|
│
|
|
│ 10. Grant access
|
|
▼
|
|
┌─────────────────┐
|
|
│ Cache │ SET user:{id}:plan = "pro"
|
|
│ Redis │ EXPIRE 3600
|
|
└────┬────────────┘
|
|
│
|
|
│ 11. Notify user
|
|
▼
|
|
┌─────────────────┐
|
|
│ Email Service │ Send "Welcome to Pro" email
|
|
│ (Twilio/SES) │
|
|
└────┬────────────┘
|
|
│
|
|
│ 12. WebSocket notification
|
|
▼
|
|
┌─────────────────┐
|
|
│ Frontend │ Event: "subscription_activated"
|
|
│ React │ → Refresh UI
|
|
└────┬────────────┘ → Show Pro features
|
|
│
|
|
▼
|
|
┌──────────┐
|
|
│ USUARIO │ "Ahora eres usuario Pro!"
|
|
└──────────┘
|
|
```
|
|
|
|
**Protocolo:** REST (checkout) + Webhook (confirmacion)
|
|
**Seguridad:** Stripe-Signature verification (HMAC SHA256)
|
|
**Latencia:** 2-5 segundos (checkout) + 1-3 segundos (webhook processing)
|
|
|
|
---
|
|
|
|
### 3.4 Flujo LLM Agent (Usuario → Chat → LLM → Tools → MT4/ML → Respuesta)
|
|
|
|
```
|
|
┌──────────┐
|
|
│ USUARIO │ "Analiza EURUSD y dame una señal"
|
|
└────┬─────┘
|
|
│ POST /agent/chat
|
|
▼
|
|
┌─────────────────┐
|
|
│ Backend Express │ 1. Validate auth
|
|
│ LLM Service │ 2. Load conversation history
|
|
└────┬────────────┘ 3. Rate limit check (10 msg/min)
|
|
│
|
|
│ 4. Build context
|
|
▼
|
|
┌─────────────────┐
|
|
│ Context │ System prompt + conversation history
|
|
│ Builder │ User profile + risk preferences
|
|
└────┬────────────┘ Available tools definition
|
|
│
|
|
│ 5. Call LLM API
|
|
▼
|
|
┌─────────────────┐
|
|
│ Claude 3.5 API │ POST /v1/messages
|
|
│ (Anthropic) │ {
|
|
└────┬────────────┘ "model": "claude-3-5-sonnet-20250929",
|
|
│ "messages": [...],
|
|
│ "tools": [
|
|
│ { "name": "get_ml_signal", ... },
|
|
│ { "name": "analyze_chart", ... }
|
|
│ ]
|
|
│ }
|
|
│
|
|
│ 6. LLM decides to use tool
|
|
▼
|
|
┌─────────────────┐
|
|
│ Claude Response│ {
|
|
│ │ "content": [
|
|
└────┬────────────┘ {
|
|
│ "type": "tool_use",
|
|
│ "name": "get_ml_signal",
|
|
│ "input": { "symbol": "EURUSD", "horizon": 18 }
|
|
│ }
|
|
│ ]
|
|
│ }
|
|
│
|
|
│ 7. Execute tool
|
|
▼
|
|
┌─────────────────┐
|
|
│ Tool Executor │ Call: get_ml_signal("EURUSD", 18)
|
|
│ Backend │
|
|
└────┬────────────┘
|
|
│ HTTP request to ML Engine
|
|
▼
|
|
┌─────────────────┐
|
|
│ ML Engine │ POST /signals
|
|
│ FastAPI │ {
|
|
└────┬────────────┘ "symbol": "EURUSD",
|
|
│ "horizon": 18
|
|
│ }
|
|
│
|
|
│ 8. Get prediction
|
|
▼
|
|
┌─────────────────┐
|
|
│ XGBoost + │ Prediction result:
|
|
│ TPSL Classifier│ {
|
|
└────┬────────────┘ "signal": "LONG",
|
|
│ "entry": 1.0550,
|
|
│ "sl": 1.0500,
|
|
│ "tp": 1.0650,
|
|
│ "prob_tp_first": 0.68,
|
|
│ "amd_phase": "accumulation"
|
|
│ }
|
|
│
|
|
│ 9. Return tool result
|
|
▼
|
|
┌─────────────────┐
|
|
│ Tool Executor │ Format tool result:
|
|
│ Backend │ {
|
|
└────┬────────────┘ "type": "tool_result",
|
|
│ "tool_use_id": "...",
|
|
│ "content": [{ ML signal JSON }]
|
|
│ }
|
|
│
|
|
│ 10. Send back to Claude
|
|
▼
|
|
┌─────────────────┐
|
|
│ Claude 3.5 API │ POST /v1/messages (continuation)
|
|
│ │ {
|
|
└────┬────────────┘ "messages": [..., tool_result]
|
|
│ }
|
|
│
|
|
│ 11. Claude generates final response
|
|
▼
|
|
┌─────────────────┐
|
|
│ Claude Response│ {
|
|
│ │ "content": [
|
|
└────┬────────────┘ {
|
|
│ "type": "text",
|
|
│ "text": "Análisis de EURUSD:
|
|
│ - Fase AMD: Acumulación
|
|
│ - Señal: LONG @ 1.0550
|
|
│ - R:R 2:1 con prob 68%
|
|
│ - Recomiendo entrada con 1% del capital"
|
|
│ }
|
|
│ ]
|
|
│ }
|
|
│
|
|
│ 12. Save conversation
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │ INSERT INTO llm.messages
|
|
│ llm schema │ - conversation_id
|
|
└────┬────────────┘ - role: "assistant"
|
|
│ - content
|
|
│ - tools_used: ["get_ml_signal"]
|
|
│
|
|
│ 13. Stream response
|
|
▼
|
|
┌─────────────────┐
|
|
│ WebSocket │ Emit chunk-by-chunk
|
|
│ Server │ → Frontend
|
|
└────┬────────────┘
|
|
│
|
|
▼
|
|
┌──────────┐
|
|
│ USUARIO │ Ve la respuesta aparecer en tiempo real
|
|
└──────────┘
|
|
```
|
|
|
|
**Protocolo:** REST + WebSocket (streaming)
|
|
**Tools Disponibles:**
|
|
- `get_ml_signal(symbol, horizon)` → ML Engine
|
|
- `analyze_chart(symbol, timeframe)` → PostgreSQL
|
|
- `execute_paper_trade(symbol, side, amount)` → Trading Service
|
|
- `get_portfolio_status()` → Investment Service
|
|
- `search_education(query)` → Education Service
|
|
|
|
**Latencia:** 3-8 segundos (depende de tool execution)
|
|
|
|
---
|
|
|
|
## 4. APIs y Endpoints
|
|
|
|
### 4.1 Backend Express (Puerto 3001)
|
|
|
|
#### Autenticacion
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| POST | `/auth/register` | `{ email, password, firstName, lastName }` | `{ user, tokens }` | No |
|
|
| POST | `/auth/login` | `{ email, password }` | `{ user, tokens }` | No |
|
|
| POST | `/auth/oauth/:provider` | `{ code }` | `{ user, tokens }` | No |
|
|
| POST | `/auth/2fa/setup` | - | `{ secret, qr_code }` | Yes |
|
|
| POST | `/auth/2fa/verify` | `{ token }` | `{ success }` | Yes |
|
|
| POST | `/auth/refresh` | `{ refresh_token }` | `{ access_token }` | No |
|
|
|
|
#### Educacion
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/education/courses` | Query: `{ level?, category? }` | `{ courses[] }` | Yes |
|
|
| GET | `/education/courses/:slug` | - | `{ course, modules[] }` | Yes |
|
|
| POST | `/education/courses/:id/enroll` | - | `{ enrollment }` | Yes |
|
|
| GET | `/education/lessons/:id` | - | `{ lesson, content }` | Yes |
|
|
| POST | `/education/lessons/:id/progress` | `{ completed, time_spent }` | `{ updated }` | Yes |
|
|
| POST | `/education/quizzes/:id/submit` | `{ answers[] }` | `{ score, correct_answers }` | Yes |
|
|
|
|
#### Trading
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/trading/symbols` | Query: `{ asset_type? }` | `{ symbols[] }` | Yes |
|
|
| GET | `/trading/candles/:symbol` | Query: `{ tf, from, to }` | `{ candles[] }` | Yes |
|
|
| WS | `/trading/stream/:symbol` | - | Stream: `{ price, volume }` | Yes |
|
|
| GET | `/trading/watchlists` | - | `{ watchlists[] }` | Yes |
|
|
| POST | `/trading/paper/orders` | `{ symbol, side, amount }` | `{ order }` | Yes |
|
|
| GET | `/trading/paper/positions` | - | `{ positions[] }` | Yes |
|
|
|
|
#### Investment
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/investment/products` | - | `{ products[] }` | Yes |
|
|
| GET | `/investment/accounts` | - | `{ accounts[] }` | Yes |
|
|
| POST | `/investment/accounts` | `{ product_id, amount }` | `{ account }` | Yes |
|
|
| POST | `/investment/accounts/:id/deposit` | `{ amount }` | `{ transaction }` | Yes |
|
|
| POST | `/investment/accounts/:id/withdraw` | `{ amount }` | `{ request }` | Yes |
|
|
| GET | `/investment/accounts/:id/performance` | Query: `{ from, to }` | `{ snapshots[] }` | Yes |
|
|
|
|
#### Payments
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/payments/plans` | - | `{ plans[] }` | No |
|
|
| POST | `/payments/checkout` | `{ plan_id, promo_code? }` | `{ checkout_url }` | Yes |
|
|
| GET | `/payments/subscription` | - | `{ subscription }` | Yes |
|
|
| POST | `/payments/subscription/cancel` | - | `{ canceled }` | Yes |
|
|
| GET | `/payments/wallet` | - | `{ balance, transactions[] }` | Yes |
|
|
| POST | `/payments/wallet/deposit` | `{ amount, method }` | `{ payment_intent }` | Yes |
|
|
| POST | `/payments/webhook` | Stripe event | `{ received: true }` | No (Signature) |
|
|
|
|
#### ML Proxy
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/ml/signals/:symbol` | Query: `{ horizon? }` | `{ signals[] }` | Yes |
|
|
| GET | `/ml/predictions/:symbol` | Query: `{ horizon }` | `{ prediction }` | Yes |
|
|
| GET | `/ml/indicators/:symbol` | Query: `{ timeframe }` | `{ indicators }` | Yes |
|
|
|
|
#### LLM Agent
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| POST | `/agent/chat` | `{ message, conversation_id? }` | Stream: `{ chunks }` | Yes |
|
|
| GET | `/agent/conversations` | - | `{ conversations[] }` | Yes |
|
|
| GET | `/agent/conversations/:id` | - | `{ messages[] }` | Yes |
|
|
| DELETE | `/agent/conversations/:id` | - | `{ deleted: true }` | Yes |
|
|
|
|
---
|
|
|
|
### 4.2 ML Engine FastAPI (Puerto 8000)
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| POST | `/predictions` | `{ symbol, horizon }` | `{ predicted_high, predicted_low, confidence }` | API Key |
|
|
| POST | `/signals` | `{ symbol, horizon, include_range, include_tpsl }` | `{ signal, entry, sl, tp, prob_tp_first }` | API Key |
|
|
| GET | `/indicators` | Query: `{ symbol }` | `{ sma, rsi, macd, atr, amd_phase }` | API Key |
|
|
| GET | `/models/status` | - | `{ models[] }` | API Key |
|
|
| GET | `/models/:name/metrics` | - | `{ mae, accuracy, auc }` | API Key |
|
|
| GET | `/health` | - | `{ status: "ok", gpu: true }` | No |
|
|
| WS | `/ws/:symbol` | - | Stream: `{ predictions }` | API Key |
|
|
|
|
**Authentication:** Header `X-API-Key: {api_key}`
|
|
|
|
---
|
|
|
|
### 4.3 Data Service Python (Puerto 8001)
|
|
|
|
| Method | Endpoint | Request | Response | Auth |
|
|
|--------|----------|---------|----------|------|
|
|
| GET | `/sync/status` | - | `{ tickers[] }` | API Key |
|
|
| POST | `/sync/trigger` | `{ ticker_id }` | `{ job_id }` | API Key |
|
|
| GET | `/sync/history/:ticker_id` | - | `{ last_sync, records_count }` | API Key |
|
|
| GET | `/spreads/:ticker_id` | Query: `{ session }` | `{ avg_spread, min, max }` | API Key |
|
|
| GET | `/health` | - | `{ status: "ok", providers[] }` | No |
|
|
|
|
---
|
|
|
|
## 5. Eventos y Webhooks
|
|
|
|
### 5.1 Webhooks Entrantes
|
|
|
|
| Proveedor | Endpoint | Evento | Accion |
|
|
|-----------|----------|--------|--------|
|
|
| Stripe | `/payments/webhook` | `checkout.session.completed` | Activar suscripcion |
|
|
| Stripe | `/payments/webhook` | `invoice.payment_succeeded` | Renovar suscripcion |
|
|
| Stripe | `/payments/webhook` | `customer.subscription.deleted` | Cancelar suscripcion |
|
|
| Stripe | `/payments/webhook` | `invoice.payment_failed` | Marcar pago fallido |
|
|
| MetaAPI | `/broker/webhook` | `trade_executed` | Log trade en BD |
|
|
| MetaAPI | `/broker/webhook` | `position_closed` | Calcular PnL |
|
|
|
|
**Seguridad:** Verificacion de firma HMAC
|
|
|
|
---
|
|
|
|
### 5.2 WebSocket Events (Frontend ← Backend)
|
|
|
|
| Event | Channel | Payload | Trigger |
|
|
|-------|---------|---------|---------|
|
|
| `price_update` | `ticker:{symbol}` | `{ bid, ask, timestamp }` | Cada 1s (market hours) |
|
|
| `ml_signal_new` | `signals:{symbol}` | `{ signal, entry, sl, tp }` | ML Engine genera senal |
|
|
| `trade_executed` | `user:{id}:trades` | `{ trade_id, status }` | Orden ejecutada en broker |
|
|
| `position_closed` | `user:{id}:positions` | `{ position_id, pnl }` | TP/SL alcanzado |
|
|
| `subscription_activated` | `user:{id}:notifications` | `{ plan }` | Webhook Stripe procesado |
|
|
| `llm_response_chunk` | `chat:{conversation_id}` | `{ chunk }` | Claude streaming |
|
|
|
|
**Protocolo:** Socket.IO (WebSocket + fallbacks)
|
|
|
|
---
|
|
|
|
## 6. Protocolos por Componente
|
|
|
|
### 6.1 Matriz de Protocolos
|
|
|
|
| Origen | Destino | Protocolo | Puerto | Uso |
|
|
|--------|---------|-----------|--------|-----|
|
|
| Frontend | Backend Express | HTTPS (REST) | 3001 | APIs CRUD |
|
|
| Frontend | Backend Express | WSS (WebSocket) | 3001 | Real-time updates |
|
|
| Backend | PostgreSQL | TCP (libpq) | 5432 | Database queries |
|
|
| Backend | Redis | TCP (RESP) | 6379 | Cache + Pub/Sub |
|
|
| Backend | ML Engine | HTTP (REST) | 8000 | ML predictions |
|
|
| Backend | Stripe | HTTPS (REST) | 443 | Payment processing |
|
|
| Backend | Claude API | HTTPS (REST) | 443 | LLM requests |
|
|
| ML Engine | PostgreSQL | TCP (libpq) | 5432 | Training data |
|
|
| ML Engine | Redis | TCP (RESP) | 6379 | Cache results |
|
|
| Data Service | Polygon API | HTTPS (REST) | 443 | Market data |
|
|
| Data Service | MetaAPI | HTTPS + WSS | 443 | Broker integration |
|
|
| Data Service | PostgreSQL | TCP (libpq) | 5432 | Insert OHLCV |
|
|
|
|
---
|
|
|
|
### 6.2 Formatos de Datos
|
|
|
|
| Componente | Request | Response | Schema |
|
|
|------------|---------|----------|--------|
|
|
| Backend Express | JSON | JSON | OpenAPI 3.0 |
|
|
| ML Engine | JSON | JSON | Pydantic models |
|
|
| PostgreSQL | SQL | Row sets | PostgreSQL types |
|
|
| Redis | RESP | RESP | Redis data types |
|
|
| WebSocket | JSON | JSON | Custom events |
|
|
| Stripe | JSON | JSON | Stripe API spec |
|
|
|
|
---
|
|
|
|
## 7. Seguridad de Integraciones
|
|
|
|
### 7.1 Autenticacion por Servicio
|
|
|
|
| Servicio | Metodo | Implementacion |
|
|
|----------|--------|----------------|
|
|
| Backend → Frontend | JWT | Access token (15 min) + Refresh (7 dias) |
|
|
| Backend → ML Engine | API Key | Header `X-API-Key` |
|
|
| Backend → Data Service | API Key | Header `X-API-Key` |
|
|
| Stripe → Backend | Signature | Header `Stripe-Signature` (HMAC) |
|
|
| Backend → Claude | API Key | Header `x-api-key` |
|
|
| Backend → Polygon | API Key | Query param `apiKey` |
|
|
| Backend → MetaAPI | Token | Header `auth-token` |
|
|
|
|
---
|
|
|
|
### 7.2 Rate Limiting
|
|
|
|
| Endpoint | Free | Basic | Pro | Premium |
|
|
|----------|------|-------|-----|---------|
|
|
| `/ml/*` | 3/dia | 10/dia | 100/dia | Unlimited |
|
|
| `/agent/chat` | 10/dia | 50/dia | 200/dia | Unlimited |
|
|
| `/trading/paper/*` | 10/min | 30/min | 100/min | 300/min |
|
|
| `/payments/*` | 5/min | 10/min | 20/min | 50/min |
|
|
|
|
**Implementacion:** Redis + express-rate-limit
|
|
|
|
---
|
|
|
|
## 8. Diagramas de Secuencia
|
|
|
|
### 8.1 Registro de Usuario
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as Usuario
|
|
participant F as Frontend
|
|
participant B as Backend
|
|
participant DB as PostgreSQL
|
|
participant E as Email Service
|
|
|
|
U->>F: Click "Registrarse"
|
|
F->>B: POST /auth/register
|
|
B->>DB: INSERT INTO users
|
|
DB-->>B: user_id
|
|
B->>E: Send verification email
|
|
B-->>F: { user, tokens }
|
|
F->>F: Store tokens localStorage
|
|
F-->>U: Redirect to dashboard
|
|
```
|
|
|
|
---
|
|
|
|
### 8.2 Ejecucion de Trade
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant ML as ML Engine
|
|
participant B as Backend
|
|
participant A as Trading Agent
|
|
participant M as MetaAPI
|
|
participant MT as MT4 Broker
|
|
participant DB as PostgreSQL
|
|
|
|
ML->>B: Publish signal to Redis
|
|
B->>A: Forward signal
|
|
A->>A: Risk check
|
|
A->>M: POST /trade
|
|
M->>MT: Execute order
|
|
MT-->>M: Order filled
|
|
M-->>A: Confirmation
|
|
A->>DB: Log execution
|
|
A->>B: Notify user
|
|
B->>Frontend: WebSocket event
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Contingencias
|
|
|
|
### 9.1 Fallback Strategies
|
|
|
|
| Servicio | Fallo | Fallback |
|
|
|----------|-------|----------|
|
|
| ML Engine | Down | Cache ultimas predicciones (Redis TTL 1h) |
|
|
| Polygon API | Rate limit | Usar datos MySQL legacy |
|
|
| MetaAPI | Timeout | Switch a investor mode (solo tracking) |
|
|
| Claude API | Error | Fallback a respuestas template |
|
|
| Stripe | Webhook miss | Polling manual cada 5 min |
|
|
|
|
---
|
|
|
|
### 9.2 Circuit Breakers
|
|
|
|
| Servicio | Threshold | Timeout | Reset |
|
|
|----------|-----------|---------|-------|
|
|
| ML Engine | 5 fallos | 30s | 60s |
|
|
| Polygon API | 3 fallos | 60s | 300s |
|
|
| MetaAPI | 10 fallos | 10s | 30s |
|
|
|
|
---
|
|
|
|
## 10. Monitoreo de Integraciones
|
|
|
|
### 10.1 Metricas Clave
|
|
|
|
| Metrica | Threshold | Alerta |
|
|
|---------|-----------|--------|
|
|
| API p95 latency | <200ms | Slack |
|
|
| ML prediction time | <2s | Email |
|
|
| WebSocket lag | <500ms | PagerDuty |
|
|
| Stripe webhook delay | <5s | Slack |
|
|
| Database query time | <100ms | Email |
|
|
|
|
---
|
|
|
|
### 10.2 Health Checks
|
|
|
|
| Servicio | Endpoint | Frecuencia |
|
|
|----------|----------|------------|
|
|
| Backend | `/health` | 30s |
|
|
| ML Engine | `/health` | 60s |
|
|
| Data Service | `/health` | 60s |
|
|
| PostgreSQL | TCP ping | 10s |
|
|
| Redis | PING | 10s |
|
|
|
|
---
|
|
|
|
## 11. Referencias
|
|
|
|
- [PLAN-DESARROLLO-DETALLADO.md](../roadmap/PLAN-DESARROLLO-DETALLADO.md)
|
|
- [MATRIZ-DEPENDENCIAS.yml](../inventarios/MATRIZ-DEPENDENCIAS.yml)
|
|
- [ARQUITECTURA-UNIFICADA.md](./ARQUITECTURA-UNIFICADA.md)
|
|
- [INT-DATA-001-data-service.md](../90-transversal/integraciones/INT-DATA-001-data-service.md)
|
|
|
|
---
|
|
|
|
**Version History:**
|
|
|
|
| Version | Fecha | Cambios |
|
|
|---------|-------|---------|
|
|
| 1.0.0 | 2025-12-05 | Creacion inicial |
|