trading-platform/docs/95-guias-desarrollo/PUERTOS-SERVICIOS.md

id	title	type	project	version	updated_date
PUERTOS-SERVICIOS	PUERTOS DE SERVICIOS - ORBIQUANT IA TRADING PLATFORM	Documentation	trading-platform	1.0.0	2026-01-04

PUERTOS DE SERVICIOS - ORBIQUANT IA TRADING PLATFORM

Documento: Asignación de Puertos para Desarrollo y Producción Proyecto: OrbiQuant IA Trading Platform Fecha: 2025-12-05 Estado: Activo

---

ÍNDICE

1. Resumen Ejecutivo
2. Tabla de Puertos
3. Servicios Detallados
4. Configuración por Entorno
5. Verificación de Puertos
6. Troubleshooting

---

RESUMEN EJECUTIVO

Este documento centraliza la asignación de puertos para todos los servicios del proyecto OrbiQuant IA Trading Platform. Los puertos están organizados por bloques funcionales para facilitar la gestión de firewall y evitar conflictos.

Principios de Asignación

• Rango 3100-3199: Servicios de Frontend (React/Vite)
• Rango 4000-4099: Servicios Backend (Node.js/Express)
• Rango 5000-5099: Servicios Python (FastAPI/AsyncIO)
• Rango 5432-5433: PostgreSQL (principal y testing)
• Puerto 6379: Redis (estándar)
• Rango 8000-8099: CI/CD y herramientas externas
• Rango 9000-9099: Monitoreo (Prometheus, Grafana)

Archivo de Configuración Central

Todos los puertos están definidos en:

/home/isem/workspace/projects/trading-platform/.env.ports

---

TABLA DE PUERTOS

Servicios de Aplicación

Servicio	Puerto	Protocolo	Estado	Descripción
Frontend Web	3100	HTTP	Activo	Aplicación React principal (Vite dev server)
Frontend Admin	3101	HTTP	Reservado	Panel de administración (futuro)
Frontend Preview	4173	HTTP	Dev	Preview de build de Vite
Backend API	4000	HTTP	Activo	API REST principal (Express)
Backend WebSocket	4001	WS	Activo	WebSocket para real-time updates
Backend Webhooks	4002	HTTP	Reservado	Endpoint para webhooks externos
ML Engine	5000	HTTP	Activo	API de predicciones (FastAPI)
Data Service	5001	TCP	Activo	Sincronización de datos de mercado
LLM Agent	5002	HTTP	Planeado	Asistente inteligente (FastAPI)
Portfolio Manager	5003	HTTP	Planeado	Gestión de portafolios (FastAPI)

Infraestructura

Servicio	Puerto	Protocolo	Estado	Descripción
PostgreSQL	5432	TCP	Activo	Base de datos principal
PostgreSQL Test	5433	TCP	Dev	Instancia para testing
Redis	6379	TCP	Activo	Cache y message queues
MySQL (Legacy)	3306	TCP	Temporal	Solo para migración

CI/CD y Monitoreo

Servicio	Puerto	Protocolo	Estado	Descripción
Jenkins	8080	HTTP	Planeado	CI/CD pipeline
Jenkins Agent	50000	TCP	Planeado	Comunicación con agentes
Prometheus	9090	HTTP	Opcional	Métricas del sistema
Grafana	3200	HTTP	Opcional	Dashboards de monitoreo

Herramientas de Desarrollo

Servicio	Puerto	Protocolo	Estado	Descripción
PgAdmin	5050	HTTP	Opcional	Administración de PostgreSQL
Mailhog SMTP	1025	SMTP	Opcional	Testing de emails (SMTP)
Mailhog Web	8025	HTTP	Opcional	Testing de emails (Web UI)

---

SERVICIOS DETALLADOS

Frontend Services

1. Frontend Web (React + Vite)

• Puerto: 3100
• Comando Dev: npm run dev -- --port 3100
• URL: http://localhost:3100
• Variables de Entorno:

  VITE_API_URL=http://localhost:4000/api/v1
  VITE_WS_URL=ws://localhost:4001
  

2. Frontend Admin Panel (Futuro)

• Puerto: 3101
• Estado: Reservado para separación de panel admin
• URL: http://localhost:3101

Backend Services

1. Backend API (Express)

• Puerto: 4000
• Archivo: /apps/backend/src/index.ts
• Comando: npm run dev
• Endpoints:
  • API REST: http://localhost:4000/api/v1
  • Health: http://localhost:4000/health
  • Docs: http://localhost:4000/api/v1/docs
• Variables de Entorno:

  PORT=4000
  DB_PORT=5432
  REDIS_PORT=6379
  ML_ENGINE_URL=http://localhost:5000
  

2. WebSocket Server

• Puerto: 4001
• Protocolo: WebSocket (WS/WSS)
• Uso: Real-time charts, notifications, live prices
• Conexión: ws://localhost:4001

Python Services

1. ML Engine (FastAPI)

• Puerto: 5000
• Archivo: /apps/ml-engine/src/api/main.py
• Comando: uvicorn src.api.main:app --host 0.0.0.0 --port 5000 --reload
• Endpoints:
  • API Docs: http://localhost:5000/docs
  • Health: http://localhost:5000/health
  • Predictions: http://localhost:5000/predict/range
• Modelos Servidos:
  • Range Predictor (ΔHigh/ΔLow)
  • TP/SL Classifier
  • Signal Generator

2. Data Service (Python AsyncIO)

• Puerto: 5001
• Archivo: /apps/data-service/src/main.py
• Comando: python -m src.main
• Funciones:
  • Sync de datos de Polygon.io cada 5min
  • Tracking de spreads desde MT4/MetaAPI
  • Entrenamiento de modelos de ajuste de precios
• Variables de Entorno:

  POLYGON_API_KEY=your_key
  METAAPI_TOKEN=your_token
  SYNC_INTERVAL_MINUTES=5
  

3. LLM Agent API (Futuro)

• Puerto: 5002
• Estado: Planeado (Módulo OQI-007)
• Función: Asistente inteligente con Claude/GPT

4. Portfolio Manager (Futuro)

• Puerto: 5003
• Estado: Planeado (Módulo OQI-008)
• Función: Gestión de portafolios de inversión

Infrastructure Services

1. PostgreSQL

• Puerto: 5432
• Estado: ACTIVO (No cambiar)
• Conexión: postgresql://orbiquant_user:password@localhost:5432/orbiquant_trading
• Schemas:
  • users - Usuarios y autenticación
  • market_data - Datos de mercado
  • trading - Señales y operaciones
  • education - Contenido educativo
  • investment - Cuentas de inversión
  • payments - Suscripciones y pagos
  • broker_integration - Integración con brokers

2. Redis

• Puerto: 6379
• Estado: ACTIVO (No cambiar)
• Conexión: redis://localhost:6379
• Uso:
  • Session storage
  • Cache de queries
  • Message queues para jobs
  • Rate limiting

---

CONFIGURACIÓN POR ENTORNO

Desarrollo Local

Crear archivo .env en la raíz del proyecto:

# Copiar plantilla de puertos
cp .env.ports .env.local

# Variables de entorno específicas
NODE_ENV=development
POSTGRES_PASSWORD=orbiquant_dev_2025
JWT_ACCESS_SECRET=your-secret-min-32-chars
JWT_REFRESH_SECRET=your-secret-min-32-chars
STRIPE_SECRET_KEY=sk_test_...
POLYGON_API_KEY=your_polygon_key

Docker Compose

El archivo docker-compose.yml usa los mismos puertos:

# Iniciar todos los servicios
docker-compose up -d

# Iniciar con herramientas de desarrollo
docker-compose --profile dev-tools up -d

# Ver logs
docker-compose logs -f backend

# Detener
docker-compose down

Producción (Jenkins)

Jenkins usará los mismos puertos. Configurar en .env.production:

NODE_ENV=production
FRONTEND_WEB_PORT=3100
BACKEND_API_PORT=4000
ML_ENGINE_PORT=5000
POSTGRES_PORT=5432
REDIS_PORT=6379

---

VERIFICACIÓN DE PUERTOS

Comandos Útiles

Listar puertos en uso

# Todos los puertos TCP/UDP en escucha
ss -tuln | grep LISTEN

# Específico de un puerto
ss -tuln | grep :4000

# Usando netstat (si está instalado)
netstat -tuln | grep LISTEN

Verificar servicio en puerto

# Verificar con curl
curl http://localhost:4000/health

# Verificar con telnet
telnet localhost 4000

# Verificar proceso usando puerto
lsof -i :4000

Matar proceso en puerto

# Encontrar PID
lsof -t -i :4000

# Matar proceso
kill -9 $(lsof -t -i :4000)

Script de Verificación

Crear /scripts/check-ports.sh:

#!/bin/bash

echo "=== OrbiQuant Port Status ==="
echo ""

declare -A services=(
  ["Frontend Web"]="3100"
  ["Backend API"]="4000"
  ["Backend WS"]="4001"
  ["ML Engine"]="5000"
  ["Data Service"]="5001"
  ["PostgreSQL"]="5432"
  ["Redis"]="6379"
)

for service in "${!services[@]}"; do
  port=${services[$service]}
  if ss -tuln | grep -q ":$port "; then
    echo "✓ $service (port $port) - RUNNING"
  else
    echo "✗ $service (port $port) - NOT RUNNING"
  fi
done

Ejecutar:

chmod +x scripts/check-ports.sh
./scripts/check-ports.sh

---

TROUBLESHOOTING

Problema: Puerto ya en uso

Síntoma: Error EADDRINUSE o Address already in use

Solución:

# 1. Identificar proceso
lsof -i :3100

# 2. Matar proceso
kill -9 <PID>

# 3. Usar puerto alternativo temporalmente
PORT=3200 npm run dev

Problema: No se puede conectar al servicio

Verificar:

1. Servicio está corriendo: ss -tuln | grep :4000
2. Firewall permite conexión: sudo ufw status
3. Variables de entorno correctas: echo $BACKEND_API_PORT
4. Logs del servicio: docker-compose logs backend

Problema: CORS en desarrollo

Causa: Frontend en puerto diferente al configurado

Solución: Actualizar CORS_ORIGINS en backend .env:

CORS_ORIGINS=http://localhost:3100,http://localhost:4173

Problema: WebSocket no conecta

Verificar:

1. Backend WS está corriendo en puerto 4001
2. Frontend usa ws:// (no wss://) en desarrollo
3. No hay proxy inverso bloqueando WS

---

ACTUALIZACIÓN DE PUERTOS

Si necesitas cambiar un puerto:

1. Actualizar /home/isem/workspace/projects/trading-platform/.env.ports
2. Actualizar este documento
3. Actualizar docker-compose.yml
4. Actualizar archivos .env de cada servicio:
   • /apps/backend/.env
   • /apps/frontend/.env
   • /apps/ml-engine/.env
   • /apps/data-service/.env
5. Reiniciar servicios afectados
6. Notificar al equipo del cambio

---

REFERENCIAS

• Archivo de puertos: /home/isem/workspace/projects/trading-platform/.env.ports
• Docker Compose: /home/isem/workspace/projects/trading-platform/docker-compose.yml
• Config Backend: /home/isem/workspace/projects/trading-platform/apps/backend/.env.example
• Config Frontend: /home/isem/workspace/projects/trading-platform/apps/frontend/vite.config.ts
• Config ML Engine: /home/isem/workspace/projects/trading-platform/apps/ml-engine/src/api/main.py
• Config Data Service: /home/isem/workspace/projects/trading-platform/apps/data-service/src/main.py

---

Última Actualización: 2025-12-05 Mantenedor: DevEnv Agent Contacto: Equipo de Desarrollo OrbiQuant