Integracion de pipeline de IA y pruebas de modelos en hf spaces, documentacion de modulos

.env.example

@@ -4,10 +4,22 @@
 # Nunca commitear el archivo .env real (debe estar en .gitignore).
 # Ubicacion recomendada: en la raiz del proyecto (al lado de docker-compose.yml).
 
-HF_TOKEN=                    # HuggingFace Pro API key (Inference API)
-OPENROUTER_API_KEY=          # Fallback LLM si HF esta saturado
-FINNHUB_API_KEY=             # Noticias financieras (finnhub.io)
-TELEGRAM_BOT_TOKEN=          # Bot de alertas (@BotFather)
-DATABASE_URL=file:./backend/prisma/polysignal.db   # SQLite local (relativo a backend/)
-PORT=7860                    # HuggingFace Spaces requiere 7860
+# HuggingFace
+HF_TOKEN=                          # HuggingFace Pro API key (Inference API)
+HF_SPACE_MODERNFINBERT_URL=blackmistcode/polysignal-modernfinbert
+HF_SPACE_QWEN_URL=blackmistcode/polysignal-qwen3-8b
+
+# Fallbacks y datos
+OPENROUTER_API_KEY=                # Fallback LLM si HF esta saturado
+FINNHUB_API_KEY=                   # Noticias financieras (finnhub.io)
+
+# Alertas
+TELEGRAM_BOT_TOKEN=                # Bot de alertas (@BotFather)
+
+# Base de datos y auth
+DATABASE_URL=file:./backend/prisma/polysignal.db
+JWT_SECRET=supersecreto-demasiado-largo-para-la-hackathon-2026
+
+# Servidor
+PORT=7860                          # HuggingFace Spaces requiere 7860
 NODE_ENV=production

README.md

@@ -8,55 +8,127 @@ PolySignal analiza mercados de Polymarket cruzando noticias de Finnhub con model
 
 **No ejecuta ordenes reales.** Es una herramienta de analisis e inteligencia.
 
-**Idioma:** Espanol.  
+**Idioma:** Espanol.
 **Moneda base:** Euro (€).
 
 ## Stack
 
 - **Backend:** Node.js 26 + Express.js 5 + Socket.io + node-cron
-- **ORM:** Prisma 7 + SQLite
-- **Frontend:** Vanilla JS + Vite 8 + Leaflet.js + Chart.js + Socket.io client
-- **IA:** HuggingFace Inference API (ModernFinBERT, Qwen3-8B) + OpenRouter fallback
+- **ORM:** Prisma 6 + SQLite
+- **Frontend:** Vanilla JS + Vite 7 + Leaflet.js + Chart.js + Socket.io client
+- **IA:** HuggingFace Spaces (ModernFinBERT + Qwen3-8B) + OpenRouter fallback
 - **Datos:** Polymarket Gamma API + Finnhub REST
 - **Deploy:** HuggingFace Spaces (Docker, puerto 7860)
 
 ## Estado del proyecto
 
-> **Nota importante:** El backend actualmente contiene solo stubs/documentacion JSDoc. El frontend funciona de forma independiente con **datos mock** realistas para la demo. Puedes ejecutar y visualizar todo el dashboard sin necesidad de configurar claves de API ni base de datos.
+El backend es **totalmente funcional**:
+
+- API REST completa con autenticacion JWT.
+- Pipeline de IA con cadena de fallback (Spaces HF → API HF → OpenRouter → rule-based).
+- Scheduler de tareas periodicas (sync mercados, generacion de senales, P&L, alertas).
+- WebSocket en tiempo real para precios y senales.
+- Base de datos SQLite con Prisma ORM.
+
+El frontend **consume datos reales del backend** y tiene **fallback a datos mock** cuando el backend no responde (modo demo sin configuracion).
 
 ## Estructura
 
 ```
 polysignal/
-├── backend/                 # API REST + Servicios + Scheduler (stubs)
+├── backend/                      # API REST + Servicios + Scheduler
 │   ├── package.json
 │   ├── prisma/
-│   │   └── schema.prisma    # Schema SQLite (Prisma)
+│   │   ├── schema.prisma         # Schema SQLite (User, Market, AISignal, Position, Watchlist, Alert)
+│   │   ├── migrations/           # Migraciones de Prisma
+│   │   └── seed.js               # Usuarios demo (admin + user)
 │   └── src/
-│       ├── index.js         # Entry point Express
-│       ├── config.js        # Variables de entorno
-│       ├── scheduler.js     # Jobs periodicos (cron)
-│       ├── routes/          # Endpoints REST (/api/v1)
-│       ├── services/        # Logica de negocio + integraciones
-│       └── socket/          # Eventos Socket.io
+│       ├── index.js              # Entry point: HTTP server + Socket.io + scheduler
+│       ├── app.js                # Express: middlewares + rutas + manejo de errores
+│       ├── config.js             # Variables de entorno validadas con Zod
+│       ├── scheduler.js          # Jobs periodicos (cron): sync, senales IA, PnL, alertas
+│       ├── auth/                 # Autenticacion JWT + bcrypt
+│       │   ├── auth.controller.js
+│       │   ├── auth.service.js
+│       │   ├── auth.routes.js
+│       │   ├── auth.validators.js
+│       │   └── jwt.js
+│       ├── markets/              # Mercados de Polymarket
+│       │   ├── markets.controller.js
+│       │   ├── markets.service.js
+│       │   ├── markets.routes.js
+│       │   ├── markets.validators.js
+│       │   ├── markets.repository.js
+│       │   └── polymarket.client.js
+│       ├── signals/              # Pipeline de IA (ModernFinBERT + Qwen3-8B)
+│       │   ├── signals.controller.js
+│       │   ├── signals.service.js
+│       │   ├── signals.routes.js
+│       │   ├── signals.repository.js
+│       │   ├── aiPipeline.js     # Pipeline IA con fallback chain
+│       │   └── finnhub.client.js # Noticias financieras
+│       ├── positions/            # Simulador de posiciones virtuales
+│       │   ├── positions.controller.js
+│       │   ├── positions.service.js
+│       │   ├── positions.routes.js
+│       │   ├── positions.validators.js
+│       │   ├── positions.repository.js
+│       │   └── kelly.js          # Criterio de Kelly (sizing)
+│       ├── watchlist/            # Lista de seguimiento
+│       │   ├── watchlist.controller.js
+│       │   ├── watchlist.service.js
+│       │   ├── watchlist.routes.js
+│       │   ├── watchlist.validators.js
+│       │   └── watchlist.repository.js
+│       ├── alerts/               # Alertas por Telegram
+│       │   ├── alerts.controller.js
+│       │   ├── alerts.service.js
+│       │   ├── alerts.routes.js
+│       │   ├── alerts.repository.js
+│       │   └── telegram.client.js
+│       ├── middlewares/          # Middlewares reutilizables
+│       │   ├── validate.js       # Validacion Zod generica
+│       │   ├── requireAuth.js    # Autenticacion JWT
+│       │   ├── rateLimitLogin.js # Rate limit login
+│       │   ├── errorHandler.js   # Manejo centralizado de errores
+│       │   └── notFound.js       # 404
+│       ├── utils/                # Utilidades compartidas
+│       │   ├── apiResponse.js    # Helpers de respuesta HTTP
+│       │   ├── httpClient.js     # Cliente HTTP con retry + timeout
+│       │   ├── logger.js         # Pino (logs estructurados)
+│       │   └── prisma.js         # Singleton PrismaClient
+│       └── socket/
+│           └── broadcaster.js    # Emisor de eventos Socket.io
 │
-├── frontend/                # SPA Vanilla JS con Vite
-│   ├── index.html             # Punto de entrada HTML
-│   ├── package.json           # Dependencias del frontend
-│   ├── vite.config.js         # Configuracion de Vite (proxy + build)
+├── frontend/                     # SPA Vanilla JS con Vite
+│   ├── index.html                # Punto de entrada HTML
+│   ├── package.json
+│   ├── vite.config.js            # Proxy a backend + build config
 │   └── src/
-│       ├── main.js            # Entry point de Vite
-│       ├── app.js             # Logica principal SPA + Socket.io
-│       ├── api.js             # Cliente REST
-│       ├── charts.js          # Chart.js (historial + sparklines)
-│       ├── map.js             # Leaflet (mapa mundial interactivo)
-│       ├── simulator.js       # Simulador de posiciones virtuales
-│       └── style.css          # Estilos dark terminal / fintech
+│       ├── main.js               # Entry point de Vite
+│       ├── app.js                # Logica principal SPA + Socket.io
+│       ├── api.js                # Cliente REST del backend
+│       ├── charts.js             # Chart.js (historial + sparklines)
+│       ├── map.js                # Leaflet (mapa mundial interactivo)
+│       ├── simulator.js          # Simulador de posiciones virtuales
+│       └── style.css             # Estilos dark terminal / fintech
+│
+├── spaces/                       # HuggingFace Spaces (ZeroGPU)
+│   ├── modernfinbert/            # Space de ModernFinBERT
+│   │   ├── app.py
+│   │   ├── requirements.txt
+│   │   └── README.md
+│   └── qwen3-8b/                 # Space de Qwen3-8B
+│       ├── app.py
+│       ├── Dockerfile
+│       ├── requirements.txt
+│       └── README.md
 │
-├── package.json             # Root con workspaces + scripts conjuntos
-├── docker-compose.yml       # Orquestacion local
-├── Dockerfile               # Build para HuggingFace Spaces
-├── .env.example             # Variables de entorno de ejemplo
+├── package.json                  # Root con workspaces + scripts conjuntos
+├── docker-compose.yml            # Orquestacion local
+├── Dockerfile                    # Build para HuggingFace Spaces
+├── .env.example                  # Variables de entorno de ejemplo
+├── SECURITY_HEALTHCHECK.md       # Auditoria de seguridad y arquitectura
 └── README.md
 ```
 
@@ -71,13 +143,11 @@ polysignal/
 # 1. Instalar dependencias (root + todos los workspaces)
 npm install
 
-# 2. (Opcional) Configurar variables de entorno para backend
-#    Si solo vas a probar el frontend, este paso NO es necesario.
+# 2. Configurar variables de entorno
 cp .env.example .env
-# Editar .env con tus claves
+# Editar .env con tus claves (HF_TOKEN, HF_SPACE_*, OPENROUTER_API_KEY, etc.)
 
-# 3. (Opcional) Generar base de datos y cliente Prisma
-#    Solo necesario si vas a desarrollar el backend.
+# 3. Generar base de datos y cliente Prisma
 npm run db:migrate
 npm run db:generate
 
@@ -98,9 +168,46 @@ npm run dev
 
 El frontend consume datos mock localmente cuando el backend no responde, por lo que el dashboard es totalmente funcional para la demo sin configuracion adicional.
 
+## Arquitectura del Backend
+
+El backend sigue una arquitectura **Layered (Controller → Service → Repository)**:
+
+| Capa | Responsabilidad | Ejemplo |
+|------|----------------|---------|
+| **Controller** | Recibir HTTP request, delegar a Service, responder | `markets.controller.js` |
+| **Service** | Logica de negocio, validaciones, coordinacion | `markets.service.js` |
+| **Repository** | Acceso a datos via Prisma ORM | `markets.repository.js` |
+| **Client** | Integracion con APIs externas | `polymarket.client.js`, `finnhub.client.js` |
+| **Middleware** | Cross-cutting concerns (auth, validacion, rate limiting) | `requireAuth.js`, `validate.js` |
+
+### Pipeline de IA
+
+```
+Noticias (Finnhub)
+    ↓
+Filtrado (ModernFinBERT Space / API directa)
+    ↓ (descarta neutrales, score < 0.65)
+Generacion de senal (Qwen3-8B Space / API directa)
+    ↓
+Fallback: OpenRouter (deepseek-chat)
+    ↓
+Fallback: Rule-based (precio del mercado)
+    ↓
+Persistencia (SQLite) + Emision Socket.io
+```
+
+### Scheduler (node-cron)
+
+| Job | Frecuencia | Descripcion |
+|-----|-----------|-------------|
+| syncMarkets | Cada 30s | Sincroniza precios desde Polymarket Gamma API |
+| generateSignals | Cada 5 min | Genera senales IA para top 20 mercados activos |
+| updatePositionsPnL | Cada 30s | Recalcula P&L de posiciones abiertas |
+| processAlerts | Cada 60s | Revisa watchlist y envia alertas Telegram |
+
 ## Arquitectura del Frontend
 
-El frontend es una SPA (Single Page Application) construida con **Vite 8** como bundler y dev server. Las librerias (Chart.js, Leaflet, Socket.io client) se gestionan como dependencias npm en lugar de CDN, lo que permite tree-shaking y un build optimizado para produccion.
+El frontend es una SPA construida con **Vite 7** como bundler y dev server.
 
 ### Caracteristicas visuales
 
@@ -130,7 +237,7 @@ npm run dev
 # Levantar solo el frontend (Vite con hot reload)
 npm run dev:frontend
 
-# Levantar backend y frontend simultaneamente en una sola terminal
+# Levantar backend y frontend simultaneamente
 npm run dev:all
 
 # Build de produccion del frontend (genera frontend/dist/)
@@ -138,16 +245,13 @@ npm run build:frontend
 
 # Preview del build de produccion
 npm run preview:frontend
-```
-
-### Build de produccion
 
-```bash
-npm run build:frontend
+# Base de datos
+npm run db:migrate      # Crear/actualizar migraciones
+npm run db:generate     # Generar cliente Prisma
+npm run db:studio       # Explorar BD con Prisma Studio
 ```
 
-Esto genera los assets optimizados en `frontend/dist/`. En produccion (HuggingFace Spaces), el backend Express sirve directamente esa carpeta como archivos estaticos.
-
 ## Deploy en HuggingFace Spaces
 
 1. Crear Space tipo "Docker"
@@ -166,6 +270,30 @@ docker build -t polysignal .
 docker run -p 7860:7860 --env-file .env polysignal
 ```
 
+## Variables de entorno
+
+```env
+# HuggingFace
+HF_TOKEN=                          # API key de HuggingFace (Inference API)
+HF_SPACE_MODERNFINBERT_URL=        # URL del Space (ej: usuario/modernfinbert)
+HF_SPACE_QWEN_URL=                 # URL del Space (ej: usuario/qwen3-8b)
+
+# Fallbacks y datos
+OPENROUTER_API_KEY=                # Fallback LLM si HF esta saturado
+FINNHUB_API_KEY=                   # Noticias financieras (finnhub.io)
+
+# Alertas
+TELEGRAM_BOT_TOKEN=                # Bot de alertas (@BotFather)
+
+# Base de datos y auth
+DATABASE_URL=file:./backend/prisma/polysignal.db
+JWT_SECRET=minimo-32-caracteres    # Secreto para firmar JWT
+
+# Servidor
+PORT=7860                          # Puerto requerido por HuggingFace Spaces
+NODE_ENV=production                # development | production
+```
+
 ## Equipo
 
 Hackathon CIFO Barcelona La Violeta — 13-18 mayo 2026

backend/package.json

@@ -17,6 +17,7 @@
     "db:studio": "prisma studio"
   },
   "dependencies": {
+    "@gradio/client": "^2.2.0",
     "@prisma/client": "^6.19.2",
     "bcryptjs": "^2.4.3",
     "cors": "^2.8.5",

backend/src/alerts/alerts.controller.js

@@ -1,3 +1,13 @@
+/**
+ * Controladores del modulo de alertas.
+ *
+ * Responsabilidades:
+ *   - list(req, res) → devuelve el historial de alertas del usuario autenticado.
+ *
+ * Endpoint (bajo /api/v1/alerts, protegido por requireAuth):
+ *   GET / → lista paginada de alertas.
+ */
+
 import { ok } from '../utils/apiResponse.js';
 import { alertsService } from './alerts.service.js';
 

backend/src/alerts/alerts.repository.js

@@ -1,3 +1,17 @@
+/**
+ * Repositorio de acceso a datos para el modelo Alert.
+ *
+ * Responsabilidades:
+ *   - create(data)       → inserta una nueva alerta.
+ *   - findByUser(...)    → alertas paginadas del usuario con datos del mercado.
+ *   - findRecent(...)    → busca alerta reciente en ventana de tiempo (deduplicacion).
+ *
+ * Campos:
+ *   type (price_threshold|signal_change), message, sentAt.
+ *
+ * Todas las operaciones usan Prisma ORM.
+ */
+
 import { prisma } from '../utils/prisma.js';
 
 export const alertsRepository = {

backend/src/alerts/alerts.routes.js

@@ -1,3 +1,12 @@
+/**
+ * Rutas REST del modulo de alertas.
+ *
+ * Endpoint (montado en /api/v1/alerts):
+ *   GET / → listar alertas del usuario autenticado.
+ *
+ * Requiere autenticacion JWT (router.use(requireAuth)).
+ */
+
 import { Router } from 'express';
 import { requireAuth } from '../middlewares/requireAuth.js';
 import { alertsController } from './alerts.controller.js';

backend/src/alerts/alerts.service.js

@@ -1,3 +1,24 @@
+/**
+ * Logica de negocio del modulo de alertas.
+ *
+ * Responsabilidades:
+ *   - list(userId, query) → devuelve alertas paginadas del usuario.
+ *   - processAll()        → revisa la watchlist cada 60s (scheduler):
+ *       1. Obtiene entradas de watchlist con alertThreshold.
+ *       2. Si yesPrice >= alertThreshold y no hay alerta reciente (5 min dedup):
+ *          - Crea alerta en base de datos.
+ *          - Envía mensaje por Telegram (si hay bot token y chatId).
+ *          - Emite evento 'price_alert' por Socket.io.
+ *
+ * Tipos de alerta:
+ *   - price_threshold : umbral de precio cruzado.
+ *   - signal_change   : cambio de senal IA (reservado para futuras versiones).
+ *
+ * Consumido por:
+ *   - alerts.controller.js (API REST).
+ *   - scheduler.js (processAlerts cada 60s).
+ */
+
 import { z } from 'zod';
 import { alertsRepository } from './alerts.repository.js';
 import { watchlistRepository } from '../watchlist/watchlist.repository.js';

backend/src/alerts/telegram.client.js

@@ -1,3 +1,20 @@
+/**
+ * Servicio de envio de alertas por Telegram Bot API.
+ *
+ * Responsabilidades:
+ *   - sendMessage(chatId, text) → POST a api.telegram.org/bot<TOKEN>/sendMessage.
+ *   - Parse_mode: HTML (permite formato basico: <b>, <i>).
+ *   - Si falta TELEGRAM_BOT_TOKEN o chatId, la funcion retorna silenciosamente.
+ *   - Errores de red se capturan y loguean como warn (no bloquean el flujo).
+ *
+ * Consumido por:
+ *   - alerts.service.js → processAll() cuando se dispara una alerta.
+ *
+ * Seguridad:
+ *   - El token se lee de variables de entorno (nunca hardcodeado).
+ *   - Se recomienda escapar entidades HTML si el texto incluye input de usuario.
+ */
+
 import { httpPost } from '../utils/httpClient.js';
 import { config } from '../config.js';
 import { logger } from '../utils/logger.js';

backend/src/app.js

@@ -1,3 +1,26 @@
+/**
+ * Aplicacion Express principal — configuracion de middlewares y montaje de rutas.
+ *
+ * Middlewares aplicados (en orden):
+ *   1. helmet()            — headers de seguridad (X-Frame-Options, HSTS, etc.).
+ *   2. cors()              — CORS con origen configurable (CORS_ORIGIN).
+ *   3. rateLimit()         — 200 peticiones / 15 min por IP.
+ *   4. express.json()      — parseo de JSON con limite de 1 MB.
+ *
+ * Rutas REST montadas bajo /api/v1:
+ *   - /auth       → login, perfil (auth.routes.js)
+ *   - /markets    → listado y detalle de mercados (markets.routes.js)
+ *   - /markets    → senales IA por mercado (signals.routes.js, subruta)
+ *   - /positions  → simulador de posiciones virtuales (positions.routes.js)
+ *   - /watchlist  → lista de seguimiento (watchlist.routes.js)
+ *   - /alerts     → historial de alertas (alerts.routes.js)
+ *   - /health     → healthcheck basico
+ *
+ * Manejo de errores:
+ *   - notFound      → 404 para rutas no definidas.
+ *   - errorHandler  → 500 generico en produccion, detalles en desarrollo.
+ */
+
 import express from 'express';
 import cors from 'cors';
 import helmet from 'helmet';

backend/src/auth/auth.controller.js

@@ -1,3 +1,16 @@
+/**
+ * Controladores del modulo de autenticacion.
+ *
+ * Responsabilidades:
+ *   - login  → recibir credenciales, delegar validacion a auth.service.js,
+ *              responder con { token, user }.
+ *   - me     → devolver el usuario autenticado extraido del JWT (req.user).
+ *
+ * Errores:
+ *   - 401 INVALID_CREDENTIALS → email o password incorrectos (mensaje generico).
+ *   - 401 UNAUTHORIZED        → token invalido o ausente (en requireAuth).
+ */
+
 import * as authService from './auth.service.js';
 import { ok } from '../utils/apiResponse.js';
 

backend/src/auth/auth.routes.js

@@ -1,3 +1,19 @@
+/**
+ * Rutas REST de autenticacion.
+ *
+ * Endpoints:
+ *   POST /api/v1/auth/login
+ *     → rateLimitLogin (5 intentos / 15 min)
+ *     → validate(loginSchema)
+ *     → authController.login
+ *     → Devuelve JWT + objeto usuario.
+ *
+ *   GET /api/v1/auth/me
+ *     → requireAuth
+ *     → authController.me
+ *     → Devuelve el usuario autenticado (req.user).
+ */
+
 import { Router } from 'express';
 import * as ctrl from './auth.controller.js';
 import { loginSchema } from './auth.validators.js';

backend/src/auth/auth.service.js

@@ -1,3 +1,20 @@
+/**
+ * Logica de negocio del modulo de autenticacion.
+ *
+ * Responsabilidades:
+ *   - login({ email, password }) → buscar usuario, comparar hash con bcrypt,
+ *     verificar que este activo (isActive) y firmar JWT.
+ *
+ * Seguridad:
+ *   - Mensaje generico en fallo ("Email or password is incorrect")
+ *     para no revelar si el email existe.
+ *   - Bcrypt con salt rounds configurable (BCRYPT_ROUNDS, default 10).
+ *   - JWT firmado con HS256 y expiracion (JWT_EXPIRES_IN).
+ *
+ * Devuelve:
+ *   { token: string, user: { id, email } }
+ */
+
 import bcrypt from 'bcryptjs';
 import { prisma } from '../utils/prisma.js';
 import { HttpError } from '../utils/apiResponse.js';

backend/src/auth/auth.validators.js

@@ -1,3 +1,14 @@
+/**
+ * Esquemas Zod para validar inputs del modulo de autenticacion.
+ *
+ * Responsabilidades:
+ *   - loginSchema: validar email (formato correcto, lowercase, trim)
+ *                  y password (minimo 8 caracteres).
+ *
+ * Consumido por:
+ *   - auth.routes.js → validate(loginSchema) en POST /login.
+ */
+
 import { z } from 'zod';
 
 export const loginSchema = z.object({

backend/src/auth/jwt.js

@@ -1,3 +1,19 @@
+/**
+ * Helpers para firmar y verificar tokens JWT.
+ *
+ * Responsabilidades:
+ *   - signToken(payload)  → firma un token HS256 con expiracion configurable.
+ *   - verifyToken(token)  → verifica firma, expiracion y algoritmo (solo HS256).
+ *
+ * Consumido por:
+ *   - auth.service.js   → al hacer login exitoso.
+ *   - requireAuth.js    → en cada peticion protegida.
+ *
+ * Configuracion:
+ *   - JWT_SECRET    : minimo 32 chars (validado en config.js).
+ *   - JWT_EXPIRES_IN: default '1h'.
+ */
+
 import jwt from 'jsonwebtoken';
 import { config } from '../config.js';
 

backend/src/config.js

@@ -1,3 +1,22 @@
+/**
+ * Configuracion centralizada de variables de entorno.
+ *
+ * Carga los valores de process.env mediante dotenv, los valida con Zod
+ * y expone constantes tipadas como: PORT, DATABASE_URL, JWT_SECRET,
+ * HF_TOKEN, HF_SPACE_MODERNFINBERT_URL, HF_SPACE_QWEN_URL, etc.
+ *
+ * Variables clave:
+ *   - PORT: 7860 (requerido por HuggingFace Spaces).
+ *   - DATABASE_URL: SQLite local para desarrollo, PostgreSQL para produccion.
+ *   - JWT_SECRET: minimo 32 caracteres, usado para firmar tokens de autenticacion.
+ *   - HF_TOKEN / HF_SPACE_*: credenciales para los Spaces de HuggingFace (IA).
+ *   - OPENROUTER_API_KEY: fallback LLM si los Spaces estan saturados.
+ *   - FINNHUB_API_KEY: noticias financieras para el pipeline de senales.
+ *   - TELEGRAM_BOT_TOKEN: bot de alertas (@BotFather).
+ *
+ * Si falla la validacion, el proceso termina con error antes de levantar el servidor.
+ */
+
 import 'dotenv/config';
 import { z } from 'zod';
 
@@ -11,6 +30,8 @@ const schema = z.object({
   CORS_ORIGIN: z.string().default('http://localhost:5173'),
   LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
   HF_TOKEN: z.string().optional(),
+  HF_SPACE_MODERNFINBERT_URL: z.string().optional(),
+  HF_SPACE_QWEN_URL: z.string().optional(),
   OPENROUTER_API_KEY: z.string().optional(),
   FINNHUB_API_KEY: z.string().optional(),
   TELEGRAM_BOT_TOKEN: z.string().optional(),

backend/src/index.js

@@ -1,3 +1,20 @@
+/**
+ * Entry point de la aplicacion PolySignal.
+ *
+ * Inicializa el servidor HTTP nativo de Node.js, monta Express sobre el,
+ * configura Socket.io para comunicacion en tiempo real, arranca el scheduler
+ * de tareas periodicas (node-cron) y gestiona el cierre limpio ante SIGTERM/SIGINT.
+ *
+ * Flujo de arranque:
+ *   1. Crear servidor HTTP y adjuntar Express (app.js).
+ *   2. Inicializar Socket.io con CORS permitido desde CORS_ORIGIN.
+ *   3. Conectar el broadcaster (socket/broadcaster.js) para emitir eventos.
+ *   4. Escuchar en el puerto configurado (default 7860 para HF Spaces).
+ *   5. En modo no-test, iniciar scheduler (sync mercados, senales IA, PnL, alertas).
+ *
+ * Puerto por defecto: 7860 (requerido por HuggingFace Spaces).
+ */
+
 import http from 'node:http';
 import { Server as IOServer } from 'socket.io';
 import app from './app.js';

backend/src/markets/markets.controller.js

@@ -1,3 +1,18 @@
+/**
+ * Controladores del modulo de mercados.
+ *
+ * Responsabilidades:
+ *   - list(req, res)   → listado paginado y filtrado de mercados activos.
+ *   - getById(req, res) → detalle de un mercado por su ID nativo de Polymarket.
+ *
+ * Datos expuestos:
+ *   - id, question, category, countryCode, yesPrice, noPrice,
+ *     volumeEur, liquidityEur, status, closesAt, lastSynced.
+ *
+ * Errores:
+ *   - 404 NOT_FOUND si el mercado no existe.
+ */
+
 import { ok } from '../utils/apiResponse.js';
 import { marketsService } from './markets.service.js';
 

backend/src/markets/markets.repository.js

@@ -1,3 +1,16 @@
+/**
+ * Repositorio de acceso a datos para el modelo Market.
+ *
+ * Responsabilidades:
+ *   - findMany({ limit, offset, category, status }) → listado paginado y filtrado.
+ *   - count({ category, status })                    → conteo para paginacion.
+ *   - findById(id)                                   → busqueda por ID nativo.
+ *   - upsert(market)                                 → crea o actualiza un mercado.
+ *
+ * Todas las operaciones usan Prisma ORM (queries parametrizadas, sin SQL injection).
+ * El orden por defecto es descendente por volumen (volumeEur).
+ */
+
 import { prisma } from '../utils/prisma.js';
 
 export const marketsRepository = {

backend/src/markets/markets.routes.js

@@ -1,3 +1,13 @@
+/**
+ * Rutas REST del modulo de mercados.
+ *
+ * Endpoints (montados en /api/v1/markets):
+ *   GET /           → listado paginado/filtrado (validate listQuery en query).
+ *   GET /:id        → detalle de mercado (validate idParam en params).
+ *
+ * No requieren autenticacion (datos publicos de Polymarket).
+ */
+
 import { Router } from 'express';
 import { validate } from '../middlewares/validate.js';
 import { marketsController } from './markets.controller.js';

backend/src/markets/markets.service.js

@@ -1,3 +1,18 @@
+/**
+ * Logica de negocio del modulo de mercados.
+ *
+ * Responsabilidades:
+ *   - list(query)   → delega a marketsRepository.findMany + count para paginacion.
+ *   - getById(id)   → busca un mercado; si no existe lanza 404.
+ *
+ * Consumido por:
+ *   - markets.controller.js (API REST).
+ *   - scheduler.js (syncMarkets cada 30s).
+ *
+ * No contiene logica de scraping directa; delega a polymarket.client.js
+ * y persiste via marketsRepository.
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 import { marketsRepository } from './markets.repository.js';
 

backend/src/markets/markets.validators.js

@@ -1,3 +1,14 @@
+/**
+ * Esquemas Zod para validar inputs del modulo de mercados.
+ *
+ * Responsabilidades:
+ *   - listQuery → limit (1-100, default 20), offset, category enum, status enum.
+ *   - idParam   → string no vacio para el parametro :id.
+ *
+ * Consumido por:
+ *   - markets.routes.js → validate(listQuery, 'query') y validate(idParam, 'params').
+ */
+
 import { z } from 'zod';
 
 export const listQuery = z.object({

backend/src/markets/polymarket.client.js

@@ -1,3 +1,19 @@
+/**
+ * Cliente de integracion con Polymarket Gamma API.
+ *
+ * Responsabilidades:
+ *   - fetchActiveMarkets(limit) → obtiene mercados activos desde gamma-api.polymarket.com.
+ *   - mapMarket(raw)            → normaliza campos crudos a la estructura del modelo Market:
+ *       * id, question, category, countryCode
+ *       * yesPrice / noPrice (parseados desde outcomePrices JSON)
+ *       * volumeEur / liquidityEur (convertidos de USD a EUR con tasa 0.93)
+ *       * status (active | closed | resolved) derivado de flags active/closed/archived
+ *       * closesAt, lastSynced
+ *
+ * No requiere autenticacion. No usa CLOB API (solo datos publicos de mercado).
+ * Consumido por scheduler.js cada 30 segundos.
+ */
+
 import { httpGet } from '../utils/httpClient.js';
 
 const GAMMA_URL = 'https://gamma-api.polymarket.com/markets';

backend/src/middlewares/errorHandler.js

@@ -1,3 +1,15 @@
+/**
+ * Middleware centralizado de manejo de errores.
+ *
+ * Responsabilidades:
+ *   - Capturar errores lanzados por controladores, servicios o middlewares.
+ *   - Si es HttpError conocido: responder con el status y codigo definido.
+ *   - Si es error inesperado: loguear el stack y responder 500 generico
+ *     ("Internal server error") para no filtrar detalles internos en produccion.
+ *
+ * Montado al final de app.js como ultimo middleware.
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 import { logger } from '../utils/logger.js';
 

backend/src/middlewares/notFound.js

@@ -1,3 +1,13 @@
+/**
+ * Middleware para rutas no definidas (404).
+ *
+ * Responsabilidades:
+ *   - Responder con 404 y un JSON estandarizado cuando ninguna ruta coincide.
+ *   - Incluye el metodo y path solicitado para facilitar debugging.
+ *
+ * Montado al final de app.js, justo antes del errorHandler.
+ */
+
 export const notFound = (req, res) =>
   res.status(404).json({
     ok: false,

backend/src/middlewares/rateLimitLogin.js

@@ -1,3 +1,15 @@
+/**
+ * Rate limiter especifico para el endpoint de login.
+ *
+ * Responsabilidades:
+ *   - Limitar a 5 intentos de login cada 15 minutos por IP.
+ *   - Mitigar ataques de fuerza bruta contra credenciales.
+ *   - Responder 429 con codigo TOO_MANY_REQUESTS cuando se excede.
+ *
+ * Aplicado unicamente en POST /api/v1/auth/login.
+ * El rate limiter global (200 req / 15 min) tambien protege el resto de la API.
+ */
+
 import rateLimit from 'express-rate-limit';
 
 export const rateLimitLogin = rateLimit({

backend/src/middlewares/requireAuth.js

@@ -1,3 +1,19 @@
+/**
+ * Middleware de autenticacion JWT.
+ *
+ * Responsabilidades:
+ *   - Extraer el header Authorization: Bearer <token>.
+ *   - Verificar la firma y expiracion del token con jwt.verify().
+ *   - Buscar el usuario en la base de datos y comprobar que esta activo (isActive).
+ *   - Adjuntar req.user para que controladores y servicios posteriores lo usen.
+ *
+ * Rutas protegidas:
+ *   - Todas bajo /positions, /watchlist, /alerts.
+ *   - GET /auth/me.
+ *
+ * Si falta token, es invalido o el usuario no existe/inactivo → 401 UNAUTHORIZED.
+ */
+
 import { verifyToken } from '../auth/jwt.js';
 import { prisma } from '../utils/prisma.js';
 import { HttpError } from '../utils/apiResponse.js';

backend/src/middlewares/validate.js

@@ -1,3 +1,19 @@
+/**
+ * Middleware generico de validacion de inputs con Zod.
+ *
+ * Responsabilidades:
+ *   - Ejecutar schema.safeParse() sobre el source indicado (body, query, params).
+ *   - Si falla: propagar HttpError 400 con los errores de validacion detallados.
+ *   - Si pasa: reemplazar req[source] por los datos parseados (coercion incluida).
+ *
+ * Uso tipico:
+ *   router.post('/', validate(createBody), controller.create);
+ *   router.get('/', validate(listQuery, 'query'), controller.list);
+ *   router.get('/:id', validate(idParam, 'params'), controller.getById);
+ *
+ * Fuente por defecto: 'body'. Para query y params debe especificarse explicitamente.
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 
 export const validate = (schema, source = 'body') => (req, _res, next) => {

backend/src/positions/kelly.js

@@ -1,7 +1,20 @@
 /**
- * Kelly criterion capped at 25%.
- * k = (odds * pWin - pLose) / odds
- * odds = (1 / price) - 1
+ * Criterio de Kelly para sizing de posiciones, limitado al 25%.
+ *
+ * Formula:
+ *   odds = (1 / price) - 1
+ *   k = (odds * pWin - pLose) / odds
+ *   return min(max(k, 0), 0.25)
+ *
+ * Parametros:
+ *   - price : precio actual del outcome (0 < price < 1).
+ *   - pWin  : probabilidad de ganar (usamos confidence de la senal IA).
+ *
+ * Devuelve:
+ *   Fraccion del capital virtual recomendada (0.0 a 0.25).
+ *
+ * Consumido por:
+ *   - positions.service.js → al abrir una posicion.
  */
 export function kellyFraction(price, pWin) {
   if (!price || price <= 0 || price >= 1 || !pWin) return 0;

backend/src/positions/positions.controller.js

@@ -1,3 +1,17 @@
+/**
+ * Controladores del modulo de posiciones (simulador virtual).
+ *
+ * Responsabilidades:
+ *   - open(req, res)   → abre una posicion virtual en un mercado.
+ *   - list(req, res)   → lista las posiciones del usuario autenticado.
+ *   - close(req, res)  → cierra una posicion y calcula P&L final.
+ *
+ * Endpoints (bajo /api/v1/positions, protegidos por requireAuth):
+ *   POST /       → abrir posicion.
+ *   GET /        → listar posiciones (opcional ?status=open|closed).
+ *   DELETE /:id  → cerrar posicion.
+ */
+
 import { ok, created, noContent } from '../utils/apiResponse.js';
 import { positionsService } from './positions.service.js';
 

backend/src/positions/positions.repository.js

@@ -1,3 +1,16 @@
+/**
+ * Repositorio de acceso a datos para el modelo Position.
+ *
+ * Responsabilidades:
+ *   - create(data)       → inserta una nueva posicion virtual.
+ *   - findByUser(userId, status) → lista posiciones del usuario con datos del mercado.
+ *   - findByIdAndUser(id, userId) → busca posicion propia del usuario.
+ *   - findAllOpen()      → todas las posiciones abiertas (para recalcular P&L).
+ *   - update(id, data)   → actualiza precio, P&L, estado, etc.
+ *
+ * Todas las operaciones usan Prisma ORM.
+ */
+
 import { prisma } from '../utils/prisma.js';
 
 export const positionsRepository = {

backend/src/positions/positions.routes.js

@@ -1,3 +1,14 @@
+/**
+ * Rutas REST del modulo de posiciones (simulador virtual).
+ *
+ * Endpoints (montados en /api/v1/positions):
+ *   POST /       → abrir posicion (validate openBody).
+ *   GET /        → listar posiciones (validate listQuery en query).
+ *   DELETE /:id  → cerrar posicion (validate idParam en params).
+ *
+ * Todas las rutas requieren autenticacion JWT (router.use(requireAuth)).
+ */
+
 import { Router } from 'express';
 import { validate } from '../middlewares/validate.js';
 import { requireAuth } from '../middlewares/requireAuth.js';

backend/src/positions/positions.service.js

@@ -1,3 +1,23 @@
+/**
+ * Logica de negocio del modulo de posiciones (simulador virtual).
+ *
+ * Responsabilidades:
+ *   - open(userId, { marketId, outcome, amountEur })
+ *     → valida que el mercado exista y este activo, obtiene precio de entrada,
+ *       calcula fraccion de Kelly y crea la posicion.
+ *   - list(userId, status) → devuelve posiciones del usuario.
+ *   - close(id, userId)    → calcula P&L final con el precio actual y marca como cerrada.
+ *   - updateAllPnL()       → recalcula P&L de todas las posiciones abiertas (scheduler).
+ *
+ * Calculos:
+ *   - P&L = amountEur * (currentPrice / entryPrice - 1).
+ *   - Kelly = (odds * pWin - pLose) / odds, capped al 25%.
+ *
+ * Consumido por:
+ *   - positions.controller.js (API REST).
+ *   - scheduler.js (updatePositionsPnL cada 30s).
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 import { positionsRepository } from './positions.repository.js';
 import { marketsRepository } from '../markets/markets.repository.js';

backend/src/positions/positions.validators.js

@@ -1,3 +1,15 @@
+/**
+ * Esquemas Zod para validar inputs del modulo de posiciones.
+ *
+ * Responsabilidades:
+ *   - openBody  → marketId (string), outcome ('YES'|'NO'), amountEur (positivo, max 100k).
+ *   - idParam   → coerce a numero entero positivo.
+ *   - listQuery → status opcional ('open'|'closed').
+ *
+ * Consumido por:
+ *   - positions.routes.js → validate() en POST, GET y DELETE.
+ */
+
 import { z } from 'zod';
 
 export const openBody = z.object({

backend/src/scheduler.js

@@ -1,3 +1,16 @@
+/**
+ * Scheduler de tareas periodicas usando node-cron.
+ *
+ * Define y ejecuta los 4 jobs principales del backend:
+ *   1. syncMarkets        — cada 30s, sincroniza precios desde Polymarket Gamma API.
+ *   2. generateSignals    — cada 5 min, genera senales IA para el top 20 mercados activos.
+ *   3. updatePositionsPnL — cada 30s, recalcula P&L de posiciones abiertas.
+ *   4. processAlerts      — cada 60s, revisa watchlist y envia alertas por Telegram.
+ *
+ * Cada job captura sus propios errores para evitar que un fallo afecte a los demas.
+ * Se ejecuta inmediatamente al arrancar (llamada manual) y luego segun cron.
+ */
+
 import { schedule } from 'node-cron';
 import { fetchActiveMarkets } from './markets/polymarket.client.js';
 import { marketsRepository } from './markets/markets.repository.js';

backend/src/signals/aiPipeline.js

@@ -1,3 +1,23 @@
+/**
+ * Pipeline de inteligencia artificial para generacion de senales de trading.
+ *
+ * Flujo de tres fases con fallback:
+ *   1. Filtrado de noticias (Finnhub + ModernFinBERT Space o API directa HF).
+ *      → descarta noticias neutrales o con score < 0.65.
+ *   2. Generacion de senal (Qwen3-8B Space o API directa HF).
+ *      → analiza mercado + noticias filtradas y genera:
+ *        { signal: 'bullish'|'bearish'|'neutral', confidence, summary, keyRisk }.
+ *   3. Fallbacks:
+ *      - Si falla el Space de Qwen → intenta API directa de HuggingFace.
+ *      - Si falla HF directa      → intenta OpenRouter (deepseek-chat).
+ *      - Si todo falla            → regla basada en precio (rule-based).
+ *
+ * Consumido por:
+ *   - signals.service.js → generateForMarket(market).
+ *   - scheduler.js       → cada 5 minutos para los 20 mercados activos.
+ */
+
+import { Client } from '@gradio/client';
 import { httpPost } from '../utils/httpClient.js';
 import { config } from '../config.js';
 import { logger } from '../utils/logger.js';
@@ -9,6 +29,10 @@ const QWEN_MODEL = 'Qwen/Qwen3-8B';
 const OPENROUTER_API = 'https://openrouter.ai/api/v1/chat/completions';
 const OPENROUTER_MODEL = 'deepseek/deepseek-chat-v3-0324:free';
 
+// Cached Gradio clients for Spaces
+let modernFinBERTClient = null;
+let qwenClient = null;
+
 // ── helpers ──────────────────────────────────────────────────────────────────
 
 function hfHeaders() {
@@ -43,9 +67,42 @@ function buildPrompt(market, headlines) {
   ].join('\n');
 }
 
-// ── FinBERT filtering ─────────────────────────────────────────────────────────
+// ── Gradio Spaces clients ────────────────────────────────────────────────────
 
-async function filterWithFinBERT(articles) {
+async function getModernFinBERTClient() {
+  if (!modernFinBERTClient && config.HF_SPACE_MODERNFINBERT_URL) {
+    modernFinBERTClient = await Client.connect(config.HF_SPACE_MODERNFINBERT_URL);
+  }
+  return modernFinBERTClient;
+}
+
+async function getQwenClient() {
+  if (!qwenClient && config.HF_SPACE_QWEN_URL) {
+    qwenClient = await Client.connect(config.HF_SPACE_QWEN_URL);
+  }
+  return qwenClient;
+}
+
+// ── FinBERT filtering via Space or direct API ─────────────────────────────────
+
+async function filterWithFinBERTSpace(articles) {
+  if (!articles.length) return articles;
+  const client = await getModernFinBERTClient();
+  if (!client) return articles;
+
+  const textBlock = articles.map((a) => a.headline).join('\n');
+  const result = await client.predict('/predict', { text_block: textBlock });
+  // Gradio returns: { data: [ [ {label, score}, ... ] ], ... }
+  const sentiments = result.data[0];
+  return articles.filter((_, i) => {
+    const r = sentiments[i];
+    if (!r) return false;
+    const label = String(r.label).toLowerCase();
+    return label !== 'neutral' && (typeof r.score === 'number' ? r.score : parseFloat(r.score)) >= 0.65;
+  });
+}
+
+async function filterWithFinBERTDirect(articles) {
   if (!articles.length) return articles;
   const inputs = articles.map((a) => a.headline);
   const results = await httpPost(
@@ -60,7 +117,44 @@ async function filterWithFinBERT(articles) {
   });
 }
 
-// ── LLM generation ────────────────────────────────────────────────────────────
+async function filterWithFinBERT(articles) {
+  // Prefer Space if configured, fallback to direct API
+  if (config.HF_SPACE_MODERNFINBERT_URL) {
+    try {
+      return await filterWithFinBERTSpace(articles);
+    } catch (err) {
+      logger.warn({ err: err.message }, 'ModernFinBERT Space failed, falling back to direct API');
+    }
+  }
+  if (config.HF_TOKEN) {
+    return await filterWithFinBERTDirect(articles);
+  }
+  return articles;
+}
+
+// ── LLM generation via Space or direct API ───────────────────────────────────
+
+async function generateWithQwenSpace(market, headlines) {
+  const client = await getQwenClient();
+  if (!client) return null;
+
+  const newsSummary = headlines.length
+    ? headlines.map((h) => `- ${h.headline}`).join('\n')
+    : 'No relevant news available.';
+
+  const marketContext = [
+    `Market: "${market.question}"`,
+    `YES price: ${market.yesPrice ?? 'N/A'} | NO price: ${market.noPrice ?? 'N/A'}`,
+  ].join('\n');
+
+  const result = await client.predict('/predict', {
+    market_context: marketContext,
+    news_summary: newsSummary,
+  });
+
+  // result.data[0] → { signal, confidence, summary, keyRisk }
+  return result.data[0];
+}
 
 async function callChatCompletion(url, model, messages, authHeader) {
   const data = await httpPost(
@@ -71,7 +165,7 @@ async function callChatCompletion(url, model, messages, authHeader) {
   return data?.choices?.[0]?.message?.content ?? null;
 }
 
-async function generateWithQwen3(market, headlines) {
+async function generateWithQwen3Direct(market, headlines) {
   const content = await callChatCompletion(
     `${HF_API}/${QWEN_MODEL}/v1/chat/completions`,
     QWEN_MODEL,
@@ -119,7 +213,7 @@ function ruleBasedSignal(market) {
 
 function validateSignal(result) {
   if (!result) return false;
-  const validSignals = ['bullish', 'bearish', 'neutral'];
+  const validSignals = ['bullish', 'bearish', 'neutral', 'buy', 'sell', 'hold'];
   return (
     validSignals.includes(result.signal) &&
     typeof result.confidence === 'number' &&
@@ -130,6 +224,16 @@ function validateSignal(result) {
   );
 }
 
+function normalizeSignal(result) {
+  if (!result) return result;
+  // Normalize buy/sell/hold to bullish/bearish/neutral for downstream compatibility
+  const signalMap = { buy: 'bullish', sell: 'bearish', hold: 'neutral' };
+  if (result.signal in signalMap) {
+    result.signal = signalMap[result.signal];
+  }
+  return result;
+}
+
 // ── public API ────────────────────────────────────────────────────────────────
 
 export async function run(market) {
@@ -138,10 +242,10 @@ export async function run(market) {
   try {
     const allNews = await fetchFinancialNews(30);
     const relevant = filterNewsByRelevance(allNews, market.question);
-    if (config.HF_TOKEN && relevant.length) {
+    if (relevant.length) {
       headlines = await filterWithFinBERT(relevant);
     } else {
-      headlines = relevant.slice(0, 10);
+      headlines = [];
     }
   } catch (err) {
     logger.warn({ err: err.message, marketId: market.id }, 'news fetch failed, continuing without news');
@@ -150,15 +254,28 @@ export async function run(market) {
   // Step 2: LLM signal generation with fallback chain
   let result = null;
 
-  if (config.HF_TOKEN) {
+  // Try Space first
+  if (config.HF_SPACE_QWEN_URL) {
+    try {
+      result = await generateWithQwenSpace(market, headlines);
+      result = normalizeSignal(result);
+      if (!validateSignal(result)) result = null;
+    } catch (err) {
+      logger.warn({ err: err.message, marketId: market.id }, 'Qwen Space failed, trying direct API');
+    }
+  }
+
+  // Fallback to direct HF API
+  if (!result && config.HF_TOKEN) {
     try {
-      result = await generateWithQwen3(market, headlines);
+      result = await generateWithQwen3Direct(market, headlines);
       if (!validateSignal(result)) result = null;
     } catch (err) {
-      logger.warn({ err: err.message, marketId: market.id }, 'Qwen3 failed, trying OpenRouter');
+      logger.warn({ err: err.message, marketId: market.id }, 'Qwen3 direct API failed, trying OpenRouter');
     }
   }
 
+  // Fallback to OpenRouter
   if (!result && config.OPENROUTER_API_KEY) {
     try {
       result = await generateWithOpenRouter(market, headlines);
@@ -168,6 +285,7 @@ export async function run(market) {
     }
   }
 
+  // Final fallback
   if (!result) {
     result = ruleBasedSignal(market);
   }

backend/src/signals/finnhub.client.js

@@ -1,3 +1,19 @@
+/**
+ * Servicio de integracion con Finnhub REST API.
+ *
+ * Responsabilidades:
+ *   - fetchFinancialNews(count) → obtiene titulares de noticias financieras.
+ *   - filterNewsByRelevance(articles, question) → filtra por keywords del mercado.
+ *
+ * Restricciones:
+ *   - Free tier: maximo 60 llamadas/minuto.
+ *   - Solo se invoca durante la generacion de senales (cada 5 min).
+ *   - Si FINNHUB_API_KEY no esta configurado, devuelve array vacio.
+ *
+ * Consumido por:
+ *   - aiPipeline.js → fase 1 de filtrado de noticias.
+ */
+
 import { httpGet } from '../utils/httpClient.js';
 import { config } from '../config.js';
 

backend/src/signals/signals.controller.js

@@ -1,3 +1,17 @@
+/**
+ * Controladores del modulo de senales IA.
+ *
+ * Responsabilidades:
+ *   - getLatest(req, res) → devuelve la senal mas reciente de un mercado.
+ *
+ * Endpoint:
+ *   GET /api/v1/markets/:marketId/signal
+ *
+ * Errores:
+ *   - 404 NOT_FOUND si el mercado no existe.
+ *   - 404 NOT_FOUND si aun no hay senal generada para ese mercado.
+ */
+
 import { ok } from '../utils/apiResponse.js';
 import { signalsService } from './signals.service.js';
 

backend/src/signals/signals.repository.js

@@ -1,3 +1,16 @@
+/**
+ * Repositorio de acceso a datos para el modelo AISignal.
+ *
+ * Responsabilidades:
+ *   - create(data)          → inserta una nueva senal generada por IA.
+ *   - findLatestByMarket(id) → devuelve la senal mas reciente de un mercado.
+ *
+ * Campos persistidos:
+ *   signal, confidence, summary, keyRisk, newsCount, modelVersion, generatedAt.
+ *
+ * Todas las operaciones usan Prisma ORM.
+ */
+
 import { prisma } from '../utils/prisma.js';
 
 export const signalsRepository = {

backend/src/signals/signals.routes.js

@@ -1,3 +1,12 @@
+/**
+ * Rutas REST del modulo de senales IA.
+ *
+ * Endpoint (montado en /api/v1/markets):
+ *   GET /:marketId/signal → senal mas reciente del mercado.
+ *
+ * No requiere autenticacion (datos publicos).
+ */
+
 import { Router } from 'express';
 import { signalsController } from './signals.controller.js';
 

backend/src/signals/signals.service.js

@@ -1,3 +1,21 @@
+/**
+ * Logica de negocio del modulo de senales IA.
+ *
+ * Responsabilidades:
+ *   - getLatest(marketId)      → devuelve la ultima senal persistida de un mercado.
+ *   - generateForMarket(market) → ejecuta el pipeline de IA (aiPipeline.js) y persiste
+ *     el resultado en AISignal. Emite evento 'ai_signal' por Socket.io.
+ *
+ * Flujo de generacion:
+ *   1. aiPipeline.run(market) → obtiene { signal, confidence, summary, keyRisk, newsCount }.
+ *   2. signalsRepository.create(...) → persiste en SQLite.
+ *   3. emitAiSignal(...) → notifica a clientes conectados en tiempo real.
+ *
+ * Consumido por:
+ *   - scheduler.js cada 5 minutos para los 20 mercados mas activos.
+ *   - signals.controller.js para el endpoint GET /markets/:id/signal.
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 import { signalsRepository } from './signals.repository.js';
 import { marketsRepository } from '../markets/markets.repository.js';

backend/src/socket/broadcaster.js

@@ -1,3 +1,18 @@
+/**
+ * Broadcaster de eventos en tiempo real via Socket.io.
+ *
+ * Actua como un wrapper singleton sobre la instancia de Socket.io.
+ * Responsabilidades:
+ *   - Recibir la instancia de io en el arranque (attachBroadcaster).
+ *   - Emitir eventos tipados a todos los clientes conectados:
+ *       * market_update  → cambio de precio/volumen de un mercado.
+ *       * ai_signal      → nueva senal generada por el pipeline de IA.
+ *       * price_alert    → alerta de umbral de precio o cambio de senal.
+ *
+ * Los controladores y servicios importan estas funciones para notificar
+ * sin acoplarse directamente a Socket.io.
+ */
+
 let _io = null;
 
 export function attachBroadcaster(io) {

backend/src/utils/apiResponse.js

@@ -1,3 +1,17 @@
+/**
+ * Helpers para respuestas HTTP estandarizadas y manejo de errores.
+ *
+ * Funciones de respuesta exitosa:
+ *   - ok(res, data, meta)      → 200 con { ok: true, data } y meta opcional.
+ *   - created(res, data)       → 201 con { ok: true, data }.
+ *   - noContent(res)           → 204 sin body.
+ *
+ * Clase HttpError:
+ *   - Extiende Error nativo.
+ *   - Campos: status (HTTP), code (string identificador), message, details (opcional).
+ *   - Usada por middlewares y servicios para propagar errores controlados.
+ */
+
 export const ok = (res, data, meta) =>
   res.status(200).json(meta ? { ok: true, data, meta } : { ok: true, data });
 

backend/src/utils/httpClient.js

@@ -1,3 +1,18 @@
+/**
+ * Cliente HTTP reutilizable con retry y timeout.
+ *
+ * Responsabilidades:
+ *   - Realizar peticiones GET y POST usando fetch nativo de Node.js.
+ *   - Aplicar timeout via AbortController.
+ *   - Reintentar automaticamente ante errores de red o HTTP 429/5xx.
+ *   - Backoff exponencial con tope de 30s.
+ *   - Inyectar User-Agent: PolySignal/1.0 en todas las peticiones.
+ *
+ * Uso:
+ *   const data = await httpGet(url, { headers, timeout, retries });
+ *   const data = await httpPost(url, body, { headers, timeout, retries });
+ */
+
 import { logger } from './logger.js';
 
 const DEFAULT_TIMEOUT_MS = 10_000;

backend/src/utils/logger.js

@@ -1,3 +1,14 @@
+/**
+ * Logger estructurado basado en Pino.
+ *
+ * Responsabilidades:
+ *   - Loguear eventos del servidor en formato JSON (facil de parsear).
+ *   - Nivel configurable via LOG_LEVEL (trace, debug, info, warn, error, fatal).
+ *   - Usado por todos los modulos para trazabilidad sin bloquear el event loop.
+ *
+ * En produccion se puede redirigir stdout a un agregador de logs (Datadog, etc.).
+ */
+
 import pino from 'pino';
 
 export const logger = pino({

backend/src/utils/prisma.js

@@ -1,3 +1,16 @@
+/**
+ * Instancia singleton de PrismaClient.
+ *
+ * Responsabilidades:
+ *   - Gestionar la conexion a SQLite (desarrollo) o PostgreSQL (produccion).
+ *   - Reutilizar la misma instancia en hot-reload (guardada en globalThis).
+ *   - Loguear solo warns y errores para no saturar la salida.
+ *
+ * Relaciones:
+ *   - Todos los repositories importan este prisma para ejecutar queries.
+ *   - schema.prisma define los modelos: User, Market, AISignal, Position, Watchlist, Alert.
+ */
+
 import { PrismaClient } from '@prisma/client';
 
 const globalForPrisma = globalThis;

backend/src/watchlist/watchlist.controller.js

@@ -1,3 +1,17 @@
+/**
+ * Controladores del modulo de lista de seguimiento (watchlist).
+ *
+ * Responsabilidades:
+ *   - add(req, res)    → anade un mercado a la watchlist con umbral de alerta opcional.
+ *   - remove(req, res) → elimina un mercado de la watchlist.
+ *   - list(req, res)   → devuelve la watchlist del usuario autenticado.
+ *
+ * Endpoints (bajo /api/v1/watchlist, protegidos por requireAuth):
+ *   POST /              → anadir mercado.
+ *   GET /               → listar watchlist.
+ *   DELETE /:marketId   → eliminar mercado.
+ */
+
 import { ok, created, noContent } from '../utils/apiResponse.js';
 import { watchlistService } from './watchlist.service.js';
 

backend/src/watchlist/watchlist.repository.js

@@ -1,3 +1,18 @@
+/**
+ * Repositorio de acceso a datos para el modelo Watchlist.
+ *
+ * Responsabilidades:
+ *   - create(data)              → inserta entrada en watchlist.
+ *   - findByUser(userId)        → lista con datos del mercado asociado.
+ *   - deleteByUserAndMarket(...) → elimina entrada especifica.
+ *   - findAllWithThreshold()    → entradas con alertThreshold definido (para alertas).
+ *
+ * Constraint:
+ *   - @@unique([userId, marketId]) → un usuario no puede duplicar un mercado.
+ *
+ * Todas las operaciones usan Prisma ORM.
+ */
+
 import { prisma } from '../utils/prisma.js';
 
 export const watchlistRepository = {

backend/src/watchlist/watchlist.routes.js

@@ -1,3 +1,14 @@
+/**
+ * Rutas REST del modulo de lista de seguimiento (watchlist).
+ *
+ * Endpoints (montados en /api/v1/watchlist):
+ *   POST /              → anadir mercado (validate addBody).
+ *   GET /               → listar watchlist.
+ *   DELETE /:marketId   → eliminar mercado (validate marketIdParam en params).
+ *
+ * Todas las rutas requieren autenticacion JWT (router.use(requireAuth)).
+ */
+
 import { Router } from 'express';
 import { validate } from '../middlewares/validate.js';
 import { requireAuth } from '../middlewares/requireAuth.js';

backend/src/watchlist/watchlist.service.js

@@ -1,3 +1,18 @@
+/**
+ * Logica de negocio del modulo de lista de seguimiento (watchlist).
+ *
+ * Responsabilidades:
+ *   - add(userId, { marketId, alertThreshold })
+ *     → valida que el mercado exista, crea entrada en watchlist.
+ *     → si ya existe (P2002), devuelve 409 ALREADY_IN_WATCHLIST.
+ *   - remove(userId, marketId) → elimina entrada; si no existe devuelve 404.
+ *   - list(userId)             → devuelve todas las entradas del usuario.
+ *
+ * Consumido por:
+ *   - watchlist.controller.js (API REST).
+ *   - alerts.service.js       → processAll() revisa watchlist con alertThreshold.
+ */
+
 import { HttpError } from '../utils/apiResponse.js';
 import { watchlistRepository } from './watchlist.repository.js';
 import { marketsRepository } from '../markets/markets.repository.js';

backend/src/watchlist/watchlist.validators.js

@@ -1,3 +1,14 @@
+/**
+ * Esquemas Zod para validar inputs del modulo de watchlist.
+ *
+ * Responsabilidades:
+ *   - addBody       → marketId (string), alertThreshold opcional (0.0 a 1.0).
+ *   - marketIdParam → string no vacio para el parametro :marketId.
+ *
+ * Consumido por:
+ *   - watchlist.routes.js → validate() en POST y DELETE.
+ */
+
 import { z } from 'zod';
 
 export const addBody = z.object({