# OrbiQuant IA - Services Architecture

## Servicios Principales

### Puertos de Desarrollo

| Servicio | Puerto | Descripción |
|----------|--------|-------------|
| Frontend | 5173 | React + Vite |
| Backend | 3000 | Express.js API |
| ML Engine | 8001 | FastAPI - Señales ML |
| Data Service | 8002 | FastAPI - Datos de mercado |
| LLM Agent | 8003 | FastAPI - Copiloto IA |
| Trading Agents | 8004 | FastAPI - Atlas/Orion/Nova |
| PostgreSQL | 5432 | Base de datos |
| Redis | 6379 | Cache y pub/sub |
| Ollama | 11434 | LLM local |
| Ollama WebUI | 3001 | UI para testing LLM |

---

## Arquitectura de Comunicación

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND (5173)                                 │
│                           React + TailwindCSS                                │
└────────────────┬────────────────┬────────────────┬──────────────────────────┘
                 │                │                │
                 ▼                ▼                ▼
┌────────────────────┐ ┌─────────────────┐ ┌─────────────────────────────────┐
│   BACKEND (3000)   │ │ LLM AGENT (8003)│ │      DATA SERVICE (8002)        │
│    Express.js      │ │   FastAPI       │ │         FastAPI                 │
│  - Auth            │ │  - Chat         │ │  - Precios real-time            │
│  - Users           │ │  - Análisis     │ │  - Históricos                   │
│  - Investment      │ │  - Estrategias  │ │  - WebSocket feeds              │
│  - Payments        │ │  - Trading Tools│ │                                 │
└─────────┬──────────┘ └────────┬────────┘ └─────────────────────────────────┘
          │                     │
          │                     │
          ▼                     ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                           ML ENGINE (8001)                                    │
│                              FastAPI                                          │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│  │  AMDDetector    │ │ RangePredictor  │ │        TPSLClassifier           │ │
│  │  (fases mercado)│ │ (ΔHigh/ΔLow)    │ │      (TP vs SL prob)            │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────────────────────┘ │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│  │ SignalGenerator │ │   Backtesting   │ │      Walk-Forward Training      │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────────────────────┘ │
└──────────────────────────────────┬───────────────────────────────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                        TRADING AGENTS (8004)                                  │
│                              FastAPI                                          │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│  │     ATLAS       │ │     ORION       │ │            NOVA                 │ │
│  │  Conservador    │ │    Moderado     │ │          Agresivo               │ │
│  │  Mean Reversion │ │ Trend Following │ │         Momentum                │ │
│  │  Grid Trading   │ │    Breakouts    │ │         Scalping                │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────────────────────┘ │
│                              │                                                │
│                              ▼                                                │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                     BINANCE CLIENT (Testnet/Mainnet)                   │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                           OLLAMA (11434)                                      │
│                         LLM Local con GPU                                     │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                     Llama 3 8B (RTX 5060 Ti)                           │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## Flujo de Datos

### 1. Usuario solicita señal de trading
```
Frontend → LLM Agent → ML Engine → SignalGenerator
    ↓
LLM Agent interpreta y responde en lenguaje natural
```

### 2. Trading automático
```
ML Engine (señales) → Trading Agents (filtros + estrategia) → Binance (ejecución)
    ↓
Backend (registro) → PostgreSQL (persistencia)
```

### 3. Chat con copiloto
```
Frontend → LLM Agent → Ollama (Llama 3) → Tools (ML Engine, Backend, Data Service)
    ↓
Respuesta enriquecida con datos reales
```

---

## URLs de Integración

### Desarrollo Local

```yaml
# Frontend (.env)
VITE_API_URL=http://localhost:3000
VITE_WS_URL=ws://localhost:3000
VITE_LLM_URL=http://localhost:8003

# Backend (.env)
ML_ENGINE_URL=http://localhost:8001
DATA_SERVICE_URL=http://localhost:8002
LLM_AGENT_URL=http://localhost:8003
TRADING_AGENTS_URL=http://localhost:8004
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orbiquant
REDIS_URL=redis://localhost:6379

# ML Engine (.env)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orbiquant
REDIS_URL=redis://localhost:6379/0

# LLM Agent (.env)
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=llama3:8b
ML_ENGINE_URL=http://localhost:8001
BACKEND_URL=http://localhost:3000
DATA_SERVICE_URL=http://localhost:8002

# Trading Agents (.env)
ML_ENGINE_URL=http://localhost:8001
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orbiquant
REDIS_URL=redis://localhost:6379/2
BINANCE_TESTNET=true
```

### Docker Compose

```yaml
# Dentro de la red Docker (orbiquant-network)
ML_ENGINE_URL=http://ml-engine:8000
LLM_AGENT_URL=http://llm-agent:8000
TRADING_AGENTS_URL=http://trading-agents:8000
OLLAMA_BASE_URL=http://ollama:11434
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/orbiquant
REDIS_URL=redis://redis:6379
```

---

## Comandos de Inicio

### Desarrollo (Sin Docker)

```bash
# Terminal 1 - PostgreSQL y Redis
docker-compose -f docker-compose.dev.yml up postgres redis

# Terminal 2 - ML Engine
cd apps/ml-engine
source venv/bin/activate  # o conda activate orbiquant-ml
uvicorn src.api.main:app --reload --port 8001

# Terminal 3 - LLM Agent + Ollama
docker-compose -f apps/llm-agent/docker-compose.ollama.yml up -d
cd apps/llm-agent
source venv/bin/activate
uvicorn src.main:app --reload --port 8003

# Terminal 4 - Trading Agents
cd apps/trading-agents
source venv/bin/activate
uvicorn src.api.main:app --reload --port 8004

# Terminal 5 - Backend
cd apps/backend
npm run dev

# Terminal 6 - Frontend
cd apps/frontend
npm run dev
```

### Producción (Docker Compose)

```bash
# Iniciar todos los servicios
docker-compose -f docker-compose.services.yml up -d

# Ver logs
docker-compose -f docker-compose.services.yml logs -f

# Detener
docker-compose -f docker-compose.services.yml down
```

---

## Health Checks

```bash
# ML Engine
curl http://localhost:8001/health

# LLM Agent
curl http://localhost:8003/health

# Trading Agents
curl http://localhost:8004/health

# Ollama
curl http://localhost:11434/api/tags

# Backend
curl http://localhost:3000/health

# Data Service
curl http://localhost:8002/health
```

---

## Recursos del Sistema

### GPU (RTX 5060 Ti - 16GB VRAM)

| Servicio | VRAM Usado | Notas |
|----------|------------|-------|
| Ollama (Llama 3 8B) | ~10GB | Modelo principal |
| XGBoost CUDA | ~2GB | Entrenamiento ML |
| Reserva | ~4GB | Otros procesos |

### Memoria RAM Recomendada

- Desarrollo: 16GB mínimo
- Producción: 32GB recomendado

### CPU

- 4 cores mínimo
- 8 cores recomendado para múltiples agentes

---

## Monitoreo

### Métricas Clave

1. **ML Engine**: Latencia de predicción, precisión de señales
2. **LLM Agent**: Tiempo de respuesta, tokens/segundo
3. **Trading Agents**: Win rate, drawdown, PnL
4. **Sistema**: CPU, RAM, GPU utilization

### Logs

```bash
# Ubicación de logs
apps/ml-engine/logs/
apps/llm-agent/logs/
apps/trading-agents/logs/
apps/backend/logs/
```

---

*Documentación de Servicios - OrbiQuant IA*
*Actualizado: 2025-12-07*