# Arquitectura Técnica — Plataforma de Trading Algorítmico Binance > **Disclaimer:** Este sistema opera con probabilidades y gestión de riesgo. No garantiza ganancias ni predice el mercado con certeza. Inicia siempre en TESTNET/PAPER TRADING. ## 1. Visión General Plataforma cloud para trading automático de criptomonedas con Binance, diseñada con separación de responsabilidades, auditabilidad y protección de capital. ### Principios de diseño | Principio | Implementación | |-----------|----------------| | Seguridad primero | Secretos en vault/env, JWT, roles, auditoría | | Fail-safe | Kill switch, límites diarios, modo solo lectura | | Auditabilidad | Cada decisión loggeada con razones matemáticas | | Probabilístico | Señales con confianza 0-100, nunca certeza | | Testnet por defecto | `TRADING_MODE=testnet` hasta activación manual | ## 2. Stack Tecnológico ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (React + Vite) │ │ Dashboard, configuración, kill switch, métricas │ └──────────────────────────┬──────────────────────────────────┘ │ HTTPS / JWT ┌──────────────────────────▼──────────────────────────────────┐ │ API Gateway (FastAPI) │ │ Auth, rate limiting, validación, REST + WebSocket │ └──────┬──────────────┬──────────────┬────────────────────────┘ │ │ │ ┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────────────────────────┐ │ Market │ │ Strategy │ │ Order Execution │ │ Worker │ │ Worker │ │ Worker │ │ (Celery) │ │ (Celery) │ │ (Celery) │ └──────┬──────┘ └─────┬─────┘ └─────┬─────────────────────────┘ │ │ │ ┌──────▼──────────────▼──────────────▼─────────────────────────┐ │ PostgreSQL │ Redis (cache + colas Celery) │ │ Datos persistentes │ Señales, locks, rate limit │ └──────────────────────┴───────────────────────────────────────┘ │ ┌──────▼───────────────────────────────────────────────────────┐ │ Binance API (Testnet / Spot) │ │ REST + WebSocket │ └──────────────────────────────────────────────────────────────┘ ``` | Componente | Tecnología | |------------|------------| | Backend API | Python 3.11 + FastAPI | | ORM / DB | SQLAlchemy 2 + PostgreSQL 15 | | Cache/Colas | Redis 7 + Celery 5 | | Indicadores | pandas, numpy, ta-lib compatible | | Frontend | React 18 + Vite + TailwindCSS | | Contenedores | Docker + docker-compose | | CI/CD | GitHub Actions | | Observabilidad | structlog + Prometheus metrics | | Notificaciones | SMTP, Telegram Bot API | ## 3. Diagrama de Módulos ```mermaid flowchart TB subgraph Client["Cliente"] DASH[Dashboard React] end subgraph API["API Layer"] AUTH[Auth JWT + RBAC] REST[REST Endpoints] WS[WebSocket Live] end subgraph Services["Domain Services"] BIN[Binance Service] MKT[Market Data Service] IND[Indicators Service] STAT[Statistics Service] STRAT[Strategy Engine] RISK[Risk Manager] BT[Backtesting Engine] PAPER[Paper Trading] NOTIF[Notification Service] end subgraph Workers["Celery Workers"] W1[market_worker] W2[strategy_worker] W3[order_worker] W4[backtest_worker] W5[notification_worker] end subgraph Data["Data Layer"] PG[(PostgreSQL)] RD[(Redis)] end subgraph External["External"] BN[Binance Testnet] TG[Telegram] EM[Email SMTP] end DASH --> AUTH AUTH --> REST REST --> Services WS --> MKT W1 --> BIN W1 --> MKT W2 --> IND W2 --> STAT W2 --> STRAT W2 --> RISK W3 --> BIN W3 --> PAPER W4 --> BT W5 --> NOTIF Services --> PG Workers --> RD Workers --> PG BIN --> BN NOTIF --> TG NOTIF --> EM ``` ## 4. Flujo de Decisión de Trading ```mermaid sequenceDiagram participant MW as Market Worker participant SW as Strategy Worker participant RM as Risk Manager participant OW as Order Worker participant DB as PostgreSQL participant BN as Binance MW->>BN: WebSocket precios + REST velas MW->>DB: Persistir OHLCV, trades, orderbook MW->>SW: Trigger evaluación (Redis queue) SW->>DB: Leer velas + indicadores cache SW->>SW: Calcular indicadores técnicos SW->>SW: Ejecutar estrategias (1-5) SW->>SW: Ensemble score 0-100 SW->>RM: Validar señal BUY/SELL/HOLD alt Bloqueado por riesgo RM->>DB: Log decisión HOLD + razón else Aprobado RM->>OW: Señal + tamaño posición + SL/TP OW->>DB: Crear orden (paper/testnet) OW->>BN: Enviar orden (si no paper) OW->>DB: Audit log + notificación end ``` ## 5. Componentes Cloud (AWS recomendado) | Servicio AWS | Uso | |--------------|-----| | ECS Fargate / EKS | Contenedores API + workers | | RDS PostgreSQL | Base de datos | | ElastiCache Redis | Cache y colas | | Secrets Manager | API keys Binance | | CloudWatch | Logs, métricas, alarmas | | ALB | Load balancer HTTPS | | S3 | Reportes backtesting, exports | | SES | Email notificaciones | | EventBridge | Scheduler backtesting diario | Alternativas equivalentes: Azure (AKS, Azure Database, Cache), GCP (GKE, Cloud SQL, Memorystore). ## 6. Modos de Operación ``` TESTNET (default) → PAPER TRADING (30+ días) → PRODUCTION (manual) ``` | Modo | Órdenes | Capital | Activación | |------|---------|---------|------------| | `testnet` | Binance Testnet API | Ficticio exchange | Automático | | `paper` | Simuladas internamente | Simulado DB | Config admin | | `production` | Binance Spot real | Real | Manual + checklist | ## 7. Seguridad - API keys: nunca en código; AWS Secrets Manager / `.env` local cifrado - Permisos Binance: `Enable Reading`, `Enable Spot & Margin Trading`; **Withdrawals OFF** - JWT con refresh tokens, expiración corta - Roles: `admin`, `analyst`, `viewer` - Rate limiting: 100 req/min por IP (API), respeto a límites Binance en servicio - Idempotencia: Redis lock por `(symbol, strategy, timestamp_bucket)` - Auditoría: tabla `audit_logs` inmutable append-only - Kill switch: flag Redis `trading:emergency_stop` + endpoint POST ## 8. Observabilidad - **Logs estructurados** (JSON): cada decisión con indicadores supporting/contradicting - **Métricas Prometheus**: `trades_total`, `signals_generated`, `api_errors`, `drawdown_current` - **Alertas**: pérdida diaria ≥ 2%, desconexión Binance > 60s, error crítico worker - **Health checks**: `/health`, `/ready` (DB + Redis + Binance ping) ## 9. Estructura del Repositorio ``` tradingbinance/ ├── docs/ARCHITECTURE.md ├── backend/ │ ├── app/ │ │ ├── api/ # Routers FastAPI │ │ ├── core/ # Config, security, deps │ │ ├── models/ # SQLAlchemy models │ │ ├── schemas/ # Pydantic schemas │ │ ├── services/ # Lógica de negocio │ │ └── workers/ # Celery tasks │ ├── tests/ │ ├── alembic/ │ ├── Dockerfile │ └── requirements.txt ├── frontend/ ├── docker-compose.yml ├── .env.example ├── postman/ └── README.md ``` ## 10. Límites de Riesgo (configurables) | Parámetro | Default | Rango | |-----------|---------|-------| | Riesgo por operación | 0.75% | 0.5% - 1% | | Pérdida máxima diaria | 2.5% | 2% - 3% | | Max trades/día | 10 | 1 - 50 | | Confianza mínima BUY | 75 | 60 - 90 | | Ensemble SELL threshold | 40 | 30 - 50 | | Pérdidas consecutivas bloqueo | 3 | 2 - 5 | | Kelly fraction cap | 0.25 | 0.1 - 0.5 | ## 11. Estrategias Implementadas 1. **Trend Following** — EMA crossover + RSI + ADX + volumen 2. **Mean Reversion** — Bollinger lower + RSI oversold + rebote 3. **Breakout** — Resistencia + volumen + ATR stop 4. **Conservative Scalping** — 1m/5m, spread bajo, volatilidad controlada 5. **Ensemble** — Score ponderado 0-100 de estrategias 1-4 ## 12. Criterios para Producción - [ ] Backtesting positivo vs buy-and-hold (neto de comisiones) - [ ] Paper trading ≥ 30 días con drawdown < límite - [ ] Win rate y profit factor dentro de umbrales configurados - [ ] Cero errores críticos en 7 días - [ ] Activación manual por admin con doble confirmación - [ ] Checklist de seguridad completado