trading-platform/docs/ARCHITECTURE.md

id	title	type	project	version	updated_date
ARCHITECTURE	Architecture	Documentation	trading-platform	1.0.0	2026-01-04

Architecture

Overview

Trading Platform es una plataforma integral de gestión de inversiones asistida por inteligencia artificial que combina money management automatizado, educación en trading, visualización de mercados y un sistema SaaS completo.

La arquitectura es de microservicios heterogéneos con servicios Node.js (backend/frontend) y Python (ML, LLM, trading agents, data) comunicándose vía REST APIs y WebSockets.

Tech Stack

Backend & Frontend

• Backend API: Express.js 5 + TypeScript + Node.js 20
• Frontend: React 18 + TypeScript + Tailwind CSS + Vite
• WebSocket: Socket.io (real-time charts, notifications)
• Database: PostgreSQL 16 (trading_platform)
• Cache: Redis 7
• Auth: JWT + Passport.js (local, OAuth2)

AI/ML Services (Python)

• ML Engine: FastAPI + PyTorch + XGBoost + scikit-learn
• LLM Agent: FastAPI + Ollama (Llama 3.1, Qwen 2.5)
• Trading Agents: FastAPI + CCXT (exchange integration)
• Data Service: FastAPI + pandas + numpy

External Services

• Payments: Stripe
• Exchanges: Binance, Bybit, OKX (via CCXT)
• LLM Models: Ollama (local deployment)

Module Structure

trading-platform/
├── apps/
│   ├── backend/                    # Express.js API (TypeScript)
│   │   └── src/
│   │       ├── modules/            # Feature modules
│   │       │   ├── auth/           # Authentication (JWT, OAuth2)
│   │       │   ├── users/          # User management
│   │       │   ├── trading/        # Trading operations
│   │       │   ├── portfolio/      # Portfolio management
│   │       │   ├── investment/     # PAMM products
│   │       │   ├── education/      # Courses & gamification
│   │       │   ├── payments/       # Stripe integration
│   │       │   ├── ml/             # ML integration
│   │       │   ├── llm/            # LLM integration
│   │       │   ├── agents/         # Trading agents management
│   │       │   └── admin/          # Admin dashboard
│   │       ├── shared/             # Shared utilities
│   │       ├── config/             # Configuration
│   │       └── core/               # Core services
│   │
│   ├── frontend/                   # React SPA
│   │   └── src/
│   │       ├── modules/            # Feature modules
│   │       │   ├── auth/           # Login, register
│   │       │   ├── dashboard/      # Main dashboard
│   │       │   ├── trading/        # Trading interface
│   │       │   ├── charts/         # TradingView-like charts
│   │       │   ├── portfolio/      # Portfolio view
│   │       │   ├── education/      # Courses
│   │       │   ├── agents/         # Agent monitoring
│   │       │   └── admin/          # Admin panel
│   │       ├── shared/             # Shared components
│   │       └── lib/                # Utilities
│   │
│   ├── ml-engine/                  # Python ML Service
│   │   └── src/
│   │       ├── models/             # ML models
│   │       │   ├── amd_detector/   # Smart Money detector (CNN+LSTM+XGBoost)
│   │       │   ├── range_predictor/ # Price range prediction
│   │       │   └── signal_generator/ # Trading signals
│   │       ├── pipelines/          # Training pipelines
│   │       ├── backtesting/        # Backtesting engine
│   │       ├── features/           # Feature engineering
│   │       └── api/                # FastAPI endpoints
│   │
│   ├── llm-agent/                  # Python LLM Service (Copilot)
│   │   └── src/
│   │       ├── core/               # LLM core (Ollama client)
│   │       ├── tools/              # 12 trading tools
│   │       │   ├── market_analysis.py
│   │       │   ├── technical_indicators.py
│   │       │   ├── sentiment_analysis.py
│   │       │   └── ...
│   │       ├── prompts/            # System prompts
│   │       └── api/                # FastAPI endpoints
│   │
│   ├── trading-agents/             # Python Trading Agents (Atlas, Orion, Nova)
│   │   └── src/
│   │       ├── agents/             # Agent implementations
│   │       │   ├── atlas/          # Conservador (3-5% mensual)
│   │       │   ├── orion/          # Moderado (5-10% mensual)
│   │       │   └── nova/           # Agresivo (10%+ mensual)
│   │       ├── strategies/         # Trading strategies
│   │       │   ├── mean_reversion.py
│   │       │   ├── trend_following.py
│   │       │   ├── breakout.py
│   │       │   └── ...
│   │       ├── exchange/           # Exchange integration (CCXT)
│   │       └── risk/               # Risk management
│   │
│   ├── data-service/               # Python Data Service (⚠️ 20% completo)
│   │   └── src/
│   │       ├── providers/          # Data providers
│   │       │   ├── binance.py
│   │       │   ├── yahoo_finance.py
│   │       │   └── ...
│   │       ├── aggregation/        # Data aggregation
│   │       └── api/                # FastAPI endpoints
│   │
│   └── database/                   # PostgreSQL
│       └── ddl/
│           └── schemas/            # 8 schemas, 98 tables
│               ├── auth/
│               ├── trading/
│               ├── investment/
│               ├── financial/
│               ├── education/
│               ├── llm/
│               ├── ml/
│               └── audit/
│
├── packages/                       # Shared code
│   ├── sdk-typescript/             # SDK for Node.js
│   ├── sdk-python/                 # SDK for Python services
│   ├── config/                     # Shared configuration
│   └── types/                      # Shared types
│
├── docker/                         # Docker configurations
├── docs/                           # Documentation
└── orchestration/                  # NEXUS agent system

Database Schemas (8 schemas, 98 tables)

Schema	Purpose	Tables	Key Entities
auth	Authentication & Users	10	users, sessions, oauth_accounts, roles
trading	Trading Operations	10	orders, positions, symbols, trades
investment	PAMM Products	7	pamm_accounts, investors, performance
financial	Payments & Wallets	10	wallets, transactions, stripe_payments
education	Courses & Gamification	14	courses, lessons, quizzes, achievements
llm	LLM Conversations	5	conversations, messages, tools_usage
ml	ML Models & Predictions	5	models, predictions, backtests
audit	Logs & Auditing	7	api_logs, user_activity, system_events

Data Flow Architecture

┌──────────────┐
│   Frontend   │ (React SPA - Port 3080)
│  (Browser)   │
└──────┬───────┘
       │ HTTP/WebSocket
       ▼
┌─────────────────────────────────────────────┐
│         Backend API (Express.js)            │
│              Port 3081                      │
│  ┌─────────────────────────────────────┐   │
│  │     REST Controllers                │   │
│  └──────┬─────────────────────┬────────┘   │
│         │                     │             │
│         ▼                     ▼             │
│  ┌─────────────┐      ┌─────────────┐      │
│  │  Services   │      │  Services   │      │
│  │  (Auth,     │      │  (Trading,  │      │
│  │   Users)    │      │   Payments) │      │
│  └─────┬───────┘      └──────┬──────┘      │
│        │                     │              │
└────────┼─────────────────────┼──────────────┘
         │                     │
         │   ┌─────────────────┼──────────────┐
         │   │                 │              │
         ▼   ▼                 ▼              ▼
┌─────────────────┐    ┌──────────────┐  ┌──────────────┐
│   PostgreSQL    │    │  ML Engine   │  │  LLM Agent   │
│   (Database)    │    │  (Python)    │  │  (Python)    │
│                 │    │  Port 3083   │  │  Port 3085   │
└─────────────────┘    └──────┬───────┘  └──────┬───────┘
                              │                 │
                              ▼                 ▼
                       ┌──────────────┐  ┌──────────────┐
                       │ Data Service │  │    Ollama    │
                       │  (Python)    │  │   WebUI      │
                       │  Port 3084   │  │  Port 3087   │
                       └──────────────┘  └──────────────┘

Service Communication

Frontend (3080)
    ↓ HTTP/WS
Backend API (3081)
    ↓ HTTP
    ├─→ ML Engine (3083)      [Price predictions, AMD detection]
    ├─→ LLM Agent (3085)      [Trading copilot, analysis]
    ├─→ Trading Agents (3086) [Automated trading]
    └─→ Data Service (3084)   [Market data]

Trading Agents (3086)
    ↓ CCXT
    └─→ Exchanges (Binance, Bybit, OKX)

LLM Agent (3085)
    ↓ HTTP
    └─→ Ollama (8000)         [Local LLM inference]

Real-time Data Flow

Exchange WebSocket (Binance)
    ↓
Data Service (3084)
    ↓ Process & Normalize
Backend API (3081)
    ↓ WebSocket
Frontend (3080)
    ↓ Render
TradingView-like Charts

Key Design Decisions

1. Microservices Architecture (Heterogeneous)

Decision: Separar servicios por lenguaje según especialización.

Rationale:

• Node.js para API y web (mejor I/O async)
• Python para ML/AI (ecosistema superior: PyTorch, scikit-learn, CCXT)
• Escalabilidad independiente por servicio
• Equipos especializados por stack

Trade-offs:

• Mayor complejidad operacional
• Necesita orquestación (Docker Compose)
• Múltiples runtimes (Node.js + Python)

2. Multi-Agent Trading System (Atlas, Orion, Nova)

Decision: 3 agentes con perfiles de riesgo diferenciados.

Rationale:

• Diversificación de estrategias
• Atractivo para diferentes tipos de inversionistas
• Competencia interna mejora algoritmos

Profiles:

• Atlas (Conservador): Target 3-5% mensual, max drawdown 5%
• Orion (Moderado): Target 5-10% mensual, max drawdown 10%
• Nova (Agresivo): Target 10%+ mensual, max drawdown 20%

3. Ensemble ML Models (CNN + LSTM + XGBoost)

Decision: Combinar múltiples modelos para detección AMD (Smart Money).

Rationale:

• CNN detecta patrones visuales en charts
• LSTM captura series temporales
• XGBoost para features tabulares
• Ensemble reduce overfitting

Accuracy: ~75% en backtesting (2020-2024)

4. Local LLM with Ollama

Decision: Usar Ollama para deployment local de LLMs (Llama 3.1, Qwen 2.5).

Rationale:

• Privacidad (no enviar datos a APIs externas)
• Costos predecibles (no pagar por token)
• Latencia baja
• Control total sobre modelos

Trade-off: Requiere GPU para inference rápida

5. PAMM (Percentage Allocation Management Module)

Decision: Implementar sistema PAMM para inversión colectiva.

Rationale:

• Permite a usuarios sin conocimiento invertir con los agentes
• Comisiones por performance (incentiva buenos resultados)
• Escalabilidad del modelo de negocio

Status: 60% implementado

6. Gamified Education Platform

Decision: Gamificar cursos de trading con puntos, logros y rankings.

Rationale:

• Aumenta engagement
• Acelera aprendizaje
• Atrae usuarios jóvenes
• Diferenciador vs competencia

7. PostgreSQL with Schema-based Multi-tenancy

Decision: Usar schemas PostgreSQL para separación lógica.

Rationale:

• Aislamiento claro por dominio
• Facilita migraciones por schema
• Mejor organización que tablas planas
• RLS (Row-Level Security) para multi-tenancy futuro

Dependencies

Critical External Dependencies

Dependency	Purpose	Criticality	Replacement
PostgreSQL 16	Database	CRITICAL	MySQL, MongoDB
Redis 7	Caching, sessions	HIGH	Memcached
Stripe	Payments	CRITICAL	PayPal, Razorpay
CCXT	Exchange APIs	CRITICAL	Custom integration
Ollama	Local LLM	HIGH	OpenAI API, Claude
Binance API	Market data	CRITICAL	Yahoo Finance, Alpha Vantage

Internal Service Dependencies

Backend API depends on:
    ├─ PostgreSQL (database)
    ├─ Redis (cache)
    ├─ ML Engine (predictions)
    ├─ LLM Agent (copilot)
    └─ Trading Agents (automated trading)

ML Engine depends on:
    ├─ PostgreSQL (model storage)
    └─ Data Service (market data)

LLM Agent depends on:
    ├─ Ollama (LLM inference)
    └─ Backend API (user context)

Trading Agents depend on:
    ├─ PostgreSQL (orders, positions)
    ├─ ML Engine (signals)
    └─ Exchanges (CCXT)

Security Considerations

Ver documentación completa: SECURITY.md

Highlights:

• JWT authentication con refresh tokens
• OAuth2 (Google, Facebook, Apple, GitHub)
• 2FA con TOTP (Speakeasy)
• API rate limiting (express-rate-limit)
• Helmet.js para headers de seguridad
• Password hashing con bcrypt
• Input validation con Zod
• SQL injection protection (parameterized queries)
• CORS configurado por entorno
• Stripe webhooks con signature verification
• API keys para servicios internos

Performance Optimizations

Backend

• Redis caching para queries frecuentes
• Connection pooling (PostgreSQL)
• Compression middleware
• Response pagination
• WebSocket para real-time (evita polling)

ML Engine

• Model caching (evita reload)
• Batch predictions
• Feature pre-computation
• GPU acceleration (PyTorch CUDA)

Frontend

• Code splitting (React lazy)
• Image optimization
• Service Worker (PWA)
• Debouncing en inputs
• Virtual scrolling para listas largas

Database

• Indexes en columnas frecuentes
• Partitioning en tablas grandes
• EXPLAIN ANALYZE para optimización
• Connection pooling

Deployment Strategy

Current: Development environment con Docker Compose

Puertos:

• Frontend: 3080
• Backend: 3081
• WebSocket: 3082
• ML Engine: 3083
• Data Service: 3084
• LLM Agent: 3085
• Trading Agents: 3086
• Ollama WebUI: 3087

Future Production:

• Kubernetes para orquestación
• Load balancer (Nginx/Traefik)
• Auto-scaling por servicio
• Multi-region deployment

Monitoring & Observability

Implemented:

• Winston logging (Backend)
• Python logging (ML services)
• Health check endpoints

Planned:

• Prometheus + Grafana
• Sentry error tracking
• Datadog APM
• Custom dashboards por agente de trading

ML Models Overview

1. AMD Detector (Accumulation-Manipulation-Distribution)

Purpose: Detectar fases de Smart Money en el mercado

Architecture:

• CNN: Detecta patrones en candlestick charts (imágenes)
• LSTM: Series temporales de precio/volumen
• XGBoost: Features técnicos (RSI, MACD, etc.)
• Ensemble: Voting classifier

Input:

• Historical OHLCV (200 candles)
• Technical indicators (20+)
• Volume profile

Output:

• Phase: Accumulation | Manipulation | Distribution | Re-accumulation
• Confidence: 0.0 - 1.0

Training: Supervised learning con datos etiquetados manualmente (2020-2024)

2. Range Predictor

Purpose: Predecir rango de precio futuro (soporte/resistencia)

Algorithm: XGBoost Regressor

Features:

• Fibonacci levels
• Previous support/resistance
• Volume at price
• Market structure

Output:

• Support level (precio)
• Resistance level (precio)
• Probability distribution

3. Signal Generator

Purpose: Generar señales de compra/venta

Architecture: Neural Network + Technical Analysis

Inputs:

• AMD phase
• Predicted range
• Technical indicators
• Sentiment analysis

Output:

• Signal: BUY | SELL | HOLD
• Strength: 0-100
• Entry/Stop/Target prices

Trading Agents Strategies

Atlas (Conservador)

Strategies:

• Mean Reversion en rangos
• Grid Trading en lateralización
• High probability setups only

Risk Management:

• Max 2% por trade
• Stop loss estricto
• Daily drawdown limit: 1%

Orion (Moderado)

Strategies:

• Trend Following
• Breakout trading
• Swing trading

Risk Management:

• Max 3% por trade
• Trailing stops
• Weekly drawdown limit: 5%

Nova (Agresivo)

Strategies:

• Momentum scalping
• High frequency entries
• Leverage (2x-5x)

Risk Management:

• Max 5% por trade
• Wide stops
• Monthly drawdown limit: 15%

LLM Agent (Copilot) Tools

El copiloto tiene 12 herramientas especializadas:

1. market_analysis - Análisis técnico completo
2. technical_indicators - Cálculo de indicadores
3. sentiment_analysis - Sentiment de noticias/social
4. price_prediction - Predicciones ML
5. risk_calculator - Cálculo de riesgo/recompensa
6. portfolio_optimizer - Optimización de portafolio
7. backtest_strategy - Backtesting de estrategias
8. news_fetcher - Noticias relevantes
9. correlation_matrix - Correlación entre activos
10. volatility_analyzer - Análisis de volatilidad
11. order_book_analyzer - Análisis de order book
12. whale_tracker - Tracking de movimientos grandes

Future Improvements

Short-term (Q1 2025)

• Completar data-service (actualmente 20%)
• Implementar tests unitarios (Jest, Pytest)
• Agregar retry/circuit breaker entre servicios
• Documentar APIs con OpenAPI/Swagger

Medium-term (Q2-Q3 2025)

• Implementar KYC/AML compliance
• Agregar más exchanges (Kraken, Coinbase)
• Mobile app (React Native)
• Notificaciones push
• Sistema de referidos

Long-term (Q4 2025+)

• Copy trading entre usuarios
• Social trading features
• Marketplace de estrategias
• API pública para terceros
• White-label solution

References

• API Documentation
• Security Guide
• Services Overview
• Database Schema
• ML Models Documentation
• Trading Agents Documentation