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

---
id: "PUERTOS-SERVICIOS"
title: "PUERTOS DE SERVICIOS - TRADING PLATFORM"
type: "Documentation"
project: "trading-platform"
version: "1.0.0"
updated_date: "2026-02-06"
---

# PUERTOS DE SERVICIOS - TRADING PLATFORM

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

---

## ÍNDICE

1. [Resumen Ejecutivo](#resumen-ejecutivo)
2. [Tabla de Puertos](#tabla-de-puertos)
3. [Servicios Detallados](#servicios-detallados)
4. [Configuración por Entorno](#configuración-por-entorno)
5. [Verificación de Puertos](#verificación-de-puertos)
6. [Troubleshooting](#troubleshooting)

---

## RESUMEN EJECUTIVO

Este documento centraliza la asignación de puertos para todos los servicios del proyecto 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** | 3080 | HTTP | Activo | Aplicación React principal (Vite dev server) |
| **Backend API** | 3081 | HTTP | Activo | API REST principal (Express) |
| **Backend WebSocket** | 3082 | WS | Activo | WebSocket para real-time updates |
| **ML Engine** | 3083 | HTTP | Activo | API de predicciones (FastAPI) |
| **Data Service** | 3084 | TCP | Activo | Sincronización de datos de mercado |
| **LLM Agent** | 3085 | HTTP | Activo | Asistente inteligente (FastAPI) |
| **Trading Agents** | 3086 | HTTP | Activo | Trading bots (Python) |
| **MCP Wallet** | 3090 | HTTP | Activo | Wallet service |
| **MCP Products** | 3091 | HTTP | Activo | Products service |
| **MCP VIP** | 3092 | HTTP | Activo | VIP service |
| **MCP Investment** | 3093 | HTTP | Activo | Investment service |
| **MCP Predictions** | 3094 | HTTP | Activo | ML signals service |
| **MCP Auth** | 3095 | HTTP | Activo | Auth service |

### 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**: `3080`
- **Comando Dev**: `npm run dev -- --port 3080`
- **URL**: `http://localhost:3080`
- **Variables de Entorno**:
  ```bash
  VITE_API_URL=http://localhost:3081/api/v1
  VITE_WS_URL=ws://localhost:3082
  ```


### Backend Services

#### 1. Backend API (Express)
- **Puerto**: `3081`
- **Archivo**: `/apps/backend/src/index.ts`
- **Comando**: `npm run dev`
- **Endpoints**:
  - API REST: `http://localhost:3081/api/v1`
  - Health: `http://localhost:3081/health`
  - Docs: `http://localhost:3081/api/v1/docs`
- **Variables de Entorno**:
  ```bash
  PORT=3081
  DB_PORT=5432
  REDIS_PORT=6379
  ML_ENGINE_URL=http://localhost:3083
  ```

#### 2. WebSocket Server
- **Puerto**: `3082`
- **Protocolo**: WebSocket (WS/WSS)
- **Uso**: Real-time charts, notifications, live prices
- **Conexión**: `ws://localhost:3082`

### Python Services

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

#### 2. Data Service (Python AsyncIO)
- **Puerto**: `3084`
- **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**:
  ```bash
  POLYGON_API_KEY=your_key
  METAAPI_TOKEN=your_token
  SYNC_INTERVAL_MINUTES=5
  ```

#### 3. LLM Agent API
- **Puerto**: `3085`
- **Estado**: Activo
- **Función**: Asistente inteligente con Claude/GPT

#### 4. Trading Agents
- **Puerto**: `3086`
- **Estado**: Activo
- **Función**: Trading bots (ATLAS, ORION, NOVA)

### Infrastructure Services

#### 1. PostgreSQL
- **Puerto**: `5432`
- **Estado**: ACTIVO (No cambiar)
- **Conexión**: `postgresql://trading_user:password@localhost:5432/trading_data`
- **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:

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

# Variables de entorno específicas
NODE_ENV=development
POSTGRES_PASSWORD=trading_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:

```bash
# 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`:

```bash
NODE_ENV=production
FRONTEND_WEB_PORT=3080
BACKEND_API_PORT=3081
BACKEND_WS_PORT=3082
ML_ENGINE_PORT=3083
DATA_SERVICE_PORT=3084
LLM_AGENT_PORT=3085
TRADING_AGENTS_PORT=3086
POSTGRES_PORT=5432
REDIS_PORT=6379
```

---

## VERIFICACIÓN DE PUERTOS

### Comandos Útiles

#### Listar puertos en uso
```bash
# Todos los puertos TCP/UDP en escucha
ss -tuln | grep LISTEN

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

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

#### Verificar servicio en puerto
```bash
# Verificar con curl
curl http://localhost:3081/health

# Verificar con telnet
telnet localhost 4000

# Verificar proceso usando puerto
lsof -i :3081
```

#### Matar proceso en puerto
```bash
# Encontrar PID
lsof -t -i :3081

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

### Script de Verificación

Crear `/scripts/check-ports.sh`:

```bash
#!/bin/bash

echo "=== Trading Platform Port Status ==="
echo ""

declare -A services=(
  ["Frontend Web"]="3080"
  ["Backend API"]="3081"
  ["Backend WS"]="3082"
  ["ML Engine"]="3083"
  ["Data Service"]="3084"
  ["LLM Agent"]="3085"
  ["Trading Agents"]="3086"
  ["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:
```bash
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**:
```bash
# 1. Identificar proceso
lsof -i :3080

# 2. Matar proceso
kill -9 <PID>

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

### Problema: No se puede conectar al servicio

**Verificar**:
1. Servicio está corriendo: `ss -tuln | grep :3081`
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`:
```bash
CORS_ORIGINS=http://localhost:3080,http://localhost:4173
```

### Problema: WebSocket no conecta

**Verificar**:
1. Backend WS está corriendo en puerto 3082
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 Trading Platform