# Architecture

## Overview

**OrbiQuant IA** 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 (orbiquant_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/)