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

# 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** | 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**:
  ```bash
  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**:
  ```bash
  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**:
  ```bash
  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://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=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
```bash
# 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
```bash
# 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
```bash
# Encontrar PID
lsof -t -i :4000

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

### Script de Verificación

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

```bash
#!/bin/bash

echo "=== Trading Platform 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:
```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 :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`:
```bash
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 Trading Platform