diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index c653e18..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,576 +0,0 @@ ---- -id: "ARCHITECTURE" -title: "Architecture" -type: "Documentation" -project: "trading-platform" -version: "1.0.0" -updated_date: "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](./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](./API.md) -- [Security Guide](./SECURITY.md) -- [Services Overview](../SERVICES.md) -- [Database Schema](../apps/database/ddl/) -- [ML Models Documentation](../apps/ml-engine/docs/) -- [Trading Agents Documentation](../apps/trading-agents/docs/)