# Trading Platform Backend API

Backend API para la plataforma Trading Platform.

## Stack Tecnologico

- **Runtime:** Node.js >= 18.0.0
- **Framework:** Express.js 5.x
- **Lenguaje:** TypeScript 5.x
- **Base de Datos:** PostgreSQL 16 (pg driver)
- **Autenticacion:** JWT + Passport.js (OAuth2)
- **Validacion:** class-validator + zod
- **Documentacion API:** Swagger (OpenAPI 3.0)

## Estructura del Proyecto

```
src/
├── config/           # Configuracion (env, swagger, database)
├── middleware/       # Middleware Express (auth, rate-limit, cors)
├── modules/          # Modulos de negocio
│   ├── admin/        # Administracion del sistema
│   ├── agents/       # Agentes de trading
│   ├── auth/         # Autenticacion y autorizacion
│   ├── education/    # Modulo educativo (gamificacion, quizzes)
│   ├── investment/   # Gestion de inversiones
│   ├── llm/          # Integracion LLM (Anthropic, OpenAI)
│   ├── ml/           # Senales ML y predicciones
│   ├── payments/     # Pagos y suscripciones (Stripe)
│   ├── portfolio/    # Gestion de portafolios
│   ├── trading/      # Operaciones de trading
│   └── users/        # Gestion de usuarios
├── services/         # Servicios compartidos
├── types/            # Tipos TypeScript
├── utils/            # Utilidades
└── index.ts          # Entry point
```

## Instalacion

```bash
# Instalar dependencias
npm install

# Copiar variables de entorno
cp .env.example .env

# Editar .env con credenciales
```

## Variables de Entorno

```env
# Server
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/trading_platform

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

# OAuth (opcional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Stripe
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Redis (cache)
REDIS_URL=redis://localhost:6379
```

## Scripts Disponibles

| Script | Descripcion |
|--------|-------------|
| `npm run dev` | Desarrollo con hot-reload (tsx watch) |
| `npm run build` | Compilar TypeScript |
| `npm start` | Ejecutar build de produccion |
| `npm run lint` | Verificar codigo con ESLint |
| `npm run test` | Ejecutar tests con Jest |
| `npm run typecheck` | Verificar tipos TypeScript |

## API Documentation

Swagger UI disponible en desarrollo:

```
http://localhost:3000/api/v1/docs
```

## Modulos Principales

### Auth (`/api/v1/auth`)
- Login/Register con email
- OAuth2 (Google, Apple, Facebook, GitHub)
- 2FA (TOTP + SMS)
- Refresh tokens

### Trading (`/api/v1/trading`)
- Ordenes de compra/venta
- Historial de operaciones
- WebSocket para datos en tiempo real

### ML Signals (`/api/v1/ml`)
- Predicciones de mercado
- Senales de trading
- Metricas de modelos

### Payments (`/api/v1/payments`)
- Suscripciones con Stripe
- Facturacion
- Historial de pagos

## WebSocket

Endpoint WebSocket para datos en tiempo real:

```
ws://localhost:3000/ws
```

Eventos soportados:
- `market:ticker` - Precios en tiempo real
- `signals:update` - Nuevas senales ML
- `orders:update` - Actualizaciones de ordenes

## Testing

```bash
# Ejecutar todos los tests
npm test

# Tests con coverage
npm run test:coverage

# Tests en modo watch
npm run test:watch
```

## Docker

```bash
# Build imagen
docker build -t trading-backend .

# Ejecutar contenedor
docker run -p 3000:3000 --env-file .env trading-backend
```

## Documentacion Relacionada

- [Documentacion de Modulos](../../docs/02-definicion-modulos/)
- [Inventario Backend](../../docs/90-transversal/inventarios/BACKEND_INVENTORY.yml)
- [Especificaciones API](../../docs/02-definicion-modulos/OQI-001-fundamentos-auth/)

---

**Proyecto:** Trading Platform
**Version:** 0.1.0
**Actualizado:** 2026-01-07