Add files using upload-large-folder tool

.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s \"https://gamma-api.polymarket.com/tags?limit=500&offset=0\")",
+      "Bash(python3 -c ' *)",
+      "Bash(curl -s \"https://gamma-api.polymarket.com/tags?limit=20&is_carousel=true\")",
+      "Bash(curl -s \"https://gamma-api.polymarket.com/tags?limit=100&is_carousel=true\")",
+      "Bash(curl -s \"https://gamma-api.polymarket.com/events?active=true&closed=false&limit=5&order=volume24hr&ascending=false\")",
+      "Bash(curl -s 'https://gamma-api.polymarket.com/tags?slug=__TRACKED_VAR__&limit=1')"
+    ]
+  }
+}

.env.example

@@ -0,0 +1,25 @@
+# Variables de entorno — PolySignal
+#
+# Copiar este archivo a .env y rellenar con tus claves.
+# Nunca commitear el archivo .env real (debe estar en .gitignore).
+# Ubicacion recomendada: en la raiz del proyecto (al lado de docker-compose.yml).
+
+# 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

CLAUDE.md

@@ -0,0 +1,133 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**PolySignal** — a real-time prediction market intelligence dashboard. It fetches market data from Polymarket, enriches it with financial news via Finnhub, runs AI sentiment analysis (ModernFinBERT + Qwen3-8B), and displays signals on an interactive world map. No real trading — pure analysis and virtual simulation. Built for CIFO Barcelona La Violeta Hackathon (May 2026). UI and docs are in **Spanish**, base currency is **Euro (€)**.
+
+## Common Commands
+
+```bash
+# Development (backend + frontend simultaneously)
+npm run dev:all
+
+# Backend only (with --watch)
+npm run dev
+
+# Frontend only (Vite @ :5173)
+npm run dev:frontend
+
+# Production build (frontend)
+npm run build:frontend
+
+# Database
+npm run db:migrate    # Apply Prisma migrations
+npm run db:generate   # Regenerate Prisma client
+npm run db:studio     # Open Prisma Studio GUI
+
+# Docker
+docker-compose up --build   # Full stack on port 7860
+```
+
+Node.js **≥24.0.0** is required (enforced in package.json engines).
+
+First-time setup:
+```bash
+npm install
+cp .env.example .env   # then fill in API keys
+npm run db:migrate && npm run db:generate
+```
+
+## Architecture
+
+Monorepo with two workspaces: `backend/` (Express 5 + Socket.io) and `frontend/` (Vanilla JS + Vite).
+
+### Backend (`backend/src/`)
+
+Follows a strict **Controller → Service → Repository → Client** layered pattern. Each domain lives in its own directory:
+
+| Directory | Responsibility |
+|-----------|---------------|
+| `markets/` | Polymarket Gamma API client + sync job |
+| `signals/` | AI pipeline (aiPipeline.js) + signals service |
+| `finnhub/` | Finnhub news client + service |
+| `positions/` | Virtual position simulator + Kelly Criterion sizing |
+| `watchlist/` | User-saved markets |
+| `alerts/` | Telegram Bot notification delivery |
+| `auth/` | JWT + bcryptjs login |
+| `socket/` | Socket.io broadcaster |
+| `middlewares/` | Auth, validation, error handling, rate limiting |
+| `utils/` | Pino logger, HTTP client, Prisma singleton |
+
+Entry points: `src/index.js` (HTTP server + Socket.io setup) → `src/app.js` (Express middleware + route mounting) → `src/scheduler.js` (cron jobs).
+
+Environment/config validated at startup via **Zod** in `src/config.js` — the app crashes fast if required env vars are missing.
+
+### Scheduler Jobs
+
+| Job | Frequency | What it does |
+|-----|-----------|-------------|
+| `syncMarkets` | 30s | Fetches top 100 active Polymarket markets, broadcasts price changes via Socket.io |
+| `generateSignals` | 5m | Runs full AI pipeline on top 20 active markets |
+| `updatePositionsPnL` | 30s | Recalculates P&L for open virtual positions |
+| `processAlerts` | 1m | Checks watchlist thresholds, fires Telegram alerts |
+
+### AI Signal Pipeline (`signals/aiPipeline.js`)
+
+Three-phase flow with automatic fallbacks:
+
+1. **News filtering** — Finnhub headlines → ModernFinBERT (HF Space) → keep only scores ≥ 0.65, drop neutral
+2. **Signal generation** — market data + filtered news → Qwen3-8B (HF Space) → `{ signal, confidence, summary, keyRisk }`
+3. **Fallback chain**: HF Space → HF direct inference API → OpenRouter (deepseek-chat) → rule-based (price-trend logic)
+
+### Frontend (`frontend/src/`)
+
+Single-page app with no framework. Key modules:
+
+| File | Role |
+|------|------|
+| `app.js` | SPA routing, DOM rendering, Socket.io listeners |
+| `api.js` | REST client wrapper with JWT token management |
+| `map.js` | Leaflet world map (bubble size = volume, color = signal) |
+| `charts.js` | Chart.js sparklines + 7-day price history |
+| `simulator.js` | Virtual buy/sell logic |
+| `filters.js` | Market filtering by category, country, continent, trend |
+
+Vite proxies `/api` and `/socket.io` to backend (`localhost:7860`) during development.
+
+### Database (SQLite via Prisma)
+
+Schema at `backend/prisma/schema.prisma`. Key models:
+- `Market` — Polymarket data (prices, volume, category, country code)
+- `AISignal` — sentiment signals with confidence and risk summary
+- `Position` — virtual trades with entry/exit prices and P&L
+- `Watchlist` / `Alert` — user market tracking and Telegram history
+- `User` — auth + optional Telegram chat ID
+
+### Real-time Communication
+
+REST API at `/api/v1/*` + WebSocket events via Socket.io:
+- `market_update` — price/volume changes
+- `ai_signal` — new sentiment signals
+- `price_alert` — watchlist threshold triggers
+
+## Deployment Target
+
+The app is designed to run on **HuggingFace Spaces** (port 7860). The Dockerfile uses `node:22-slim`, installs backend deps, copies the frontend `dist/`, runs Prisma generate, and starts the server. The frontend is served as static files by Express in production.
+
+## Key Environment Variables
+
+See `.env.example` for the full list. Critical ones:
+
+```
+HF_SPACE_MODERNFINBERT_URL   # HuggingFace Space for FinBERT
+HF_SPACE_QWEN_URL            # HuggingFace Space for Qwen3-8B
+HF_TOKEN                     # HF inference API key (fallback)
+OPENROUTER_API_KEY           # LLM fallback if HF is down
+FINNHUB_API_KEY              # News source
+TELEGRAM_BOT_TOKEN           # Alert delivery
+JWT_SECRET                   # Must be ≥32 characters
+PORT=7860                    # Required by HF Spaces
+DATABASE_URL=file:./backend/prisma/polysignal.db
+```

backend/.env.example

@@ -0,0 +1,20 @@
+# Variables de entorno del backend PolySignal.
+# Copiar este archivo a backend/.env y rellenar los valores.
+# El archivo .env real NO debe commitearse (asegurar entrada en .gitignore).
+
+NODE_ENV=development
+PORT=7860
+
+# SQLite path relativo al archivo schema.prisma (backend/prisma/).
+DATABASE_URL=file:./polysignal.db
+
+# Auth — generar con: openssl rand -hex 48
+JWT_SECRET=replace-with-64-plus-random-chars
+JWT_EXPIRES_IN=1h
+BCRYPT_ROUNDS=10
+
+# CORS del frontend Vite en desarrollo.
+CORS_ORIGIN=http://localhost:5173
+
+# Logger pino (trace | debug | info | warn | error | fatal).
+LOG_LEVEL=info

backend/docs/ALERTS.md

@@ -0,0 +1,129 @@
+# ALERTS.md — Módulo de alertas
+
+Historial de alertas de precio disparadas por el job `processAlerts`. Las alertas se crean automáticamente cuando `yesPrice >= alertThreshold` en la watchlist del usuario.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `GET /api/v1/alerts`
+
+Lista el historial de alertas del usuario, paginado y ordenado por `sentAt` DESC.
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 4,
+      "userId": 1,
+      "marketId": "559677",
+      "type": "price_threshold",
+      "message": "<b>Price Alert</b>\nWill Hillary Clinton win the 2028 Democratic presidential nomination?\nYES: 0.8% ≥ threshold 0.1%",
+      "sentAt": "2026-05-16T09:38:00.033Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?"
+      }
+    }
+  ]
+}
+```
+
+**Campos**
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la alerta |
+| `userId` | int | Usuario que la recibió |
+| `marketId` | string | Mercado que la disparó |
+| `type` | string | Tipo de alerta (`price_threshold`) |
+| `message` | string | Mensaje enviado (formato HTML para Telegram) |
+| `sentAt` | ISO 8601 | Timestamp de envío |
+| `market.question` | string | Pregunta del mercado (para mostrar en UI) |
+
+---
+
+## Flujo de creación
+
+Las alertas **no se crean desde el frontend** — solo se leen. El flujo de creación es:
+
+1. `POST /api/v1/watchlist` con `alertThreshold` → guarda umbral en DB.
+2. Job `processAlerts` (cada minuto): evalúa `yesPrice >= alertThreshold` para cada watchlist entry con threshold definido.
+3. Si se cumple y no hay alerta reciente (< 5 min): crea `Alert` + envía Telegram + emite `price_alert` por socket.
+
+---
+
+## Socket — evento `price_alert`
+
+**Nombre del evento:** `price_alert`
+
+**Payload**
+
+```json
+{
+  "marketId": "559677",
+  "type": "price_threshold",
+  "message": "<b>Price Alert</b>\n..."
+}
+```
+
+**Uso en el frontend**
+
+```js
+socket.on('price_alert', ({ marketId, message }) => {
+  // mostrar notificación toast
+});
+```
+
+---
+
+## Integración Telegram
+
+Para recibir alertas vía Telegram:
+
+1. Crear un bot en [@BotFather](https://t.me/BotFather) y obtener el `TELEGRAM_BOT_TOKEN`.
+2. El usuario debe iniciar conversación con el bot y obtener su `chatId`.
+3. Configurar `telegramChatId` en el registro `User` (actualmente solo vía `prisma studio` o seed).
+4. Añadir `TELEGRAM_BOT_TOKEN` al `.env`.
+
+Si `TELEGRAM_BOT_TOKEN` no está configurado o el usuario no tiene `telegramChatId`, el envío se omite silenciosamente (la `Alert` se crea igualmente en DB).
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Listar alertas (últimas 10)
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/alerts?limit=10" | jq
+
+# Segunda página
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/alerts?limit=10&offset=10" | jq
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Params inválidos (limit > 100) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/API.md

@@ -0,0 +1,137 @@
+# API.md — Referencia general PolySignal Backend
+
+Base URL (dev): `http://localhost:7860`  
+Base URL (prod, HF Spaces): misma URL que el frontend (mismo origen).
+
+---
+
+## Arranque rápido
+
+```bash
+cd backend/
+npm install
+npm run db:migrate        # solo primera vez
+npm run db:seed           # crea usuarios de prueba
+npm run dev               # http://localhost:7860
+```
+
+Usuarios de prueba: `admin@polysignal.test / Admin123!` y `user@polysignal.test / User123!`
+
+---
+
+## Autenticación
+
+El API usa JWT Bearer. Para obtener un token:
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+```
+
+Enviarlo en cada request protegido:
+
+```
+Authorization: Bearer <token>
+```
+
+---
+
+## Endpoints
+
+### Públicos (sin auth)
+
+| Método | Ruta | Descripción | Doc |
+|---|---|---|---|
+| `GET` | `/api/v1/health` | Sanity check | [AUTH.md](AUTH.md) |
+| `POST` | `/api/v1/auth/login` | Login → JWT | [AUTH.md](AUTH.md) |
+| `GET` | `/api/v1/markets` | Lista mercados paginada | [MARKETS.md](MARKETS.md) |
+| `GET` | `/api/v1/markets/:id` | Detalle de mercado | [MARKETS.md](MARKETS.md) |
+| `GET` | `/api/v1/markets/:id/signal` | Señal AI del mercado | [SIGNALS.md](SIGNALS.md) |
+
+### Protegidos (requieren `Authorization: Bearer <token>`)
+
+| Método | Ruta | Descripción | Doc |
+|---|---|---|---|
+| `GET` | `/api/v1/auth/me` | Perfil del usuario | [AUTH.md](AUTH.md) |
+| `POST` | `/api/v1/positions` | Abrir posición | [POSITIONS.md](POSITIONS.md) |
+| `GET` | `/api/v1/positions` | Listar posiciones | [POSITIONS.md](POSITIONS.md) |
+| `DELETE` | `/api/v1/positions/:id` | Cerrar posición | [POSITIONS.md](POSITIONS.md) |
+| `POST` | `/api/v1/watchlist` | Añadir a watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `GET` | `/api/v1/watchlist` | Listar watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `DELETE` | `/api/v1/watchlist/:marketId` | Eliminar de watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `GET` | `/api/v1/alerts` | Historial de alertas | [ALERTS.md](ALERTS.md) |
+
+---
+
+## Contrato de respuesta
+
+Todas las respuestas siguen el mismo envelope:
+
+```json
+// éxito
+{ "ok": true, "data": <payload>, "meta": { ...opcional } }
+
+// error
+{ "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "details": [...] } }
+```
+
+Códigos HTTP: `200` lectura · `201` creación · `204` borrado · `400` validación · `401` no autenticado · `404` no encontrado · `409` conflicto · `429` rate limit · `500` server error.
+
+---
+
+## Rate limiting
+
+- **Global:** 200 req / 15 min / IP
+- **`POST /auth/login`:** 5 intentos / 15 min / IP
+
+Headers de respuesta: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.
+
+---
+
+## WebSocket (Socket.io)
+
+Conectar al mismo host que el backend:
+
+```js
+import { io } from 'socket.io-client';
+const socket = io('http://localhost:7860');
+```
+
+| Evento | Frecuencia | Descripción | Doc |
+|---|---|---|---|
+| `market_update` | cada 30s | Precio actualizado de un mercado | [MARKETS.md](MARKETS.md) |
+| `ai_signal` | cada 5 min | Nueva señal AI generada | [SIGNALS.md](SIGNALS.md) |
+| `price_alert` | cuando se dispara | Alerta de precio threshold | [ALERTS.md](ALERTS.md) |
+
+---
+
+## Importar en Insomnia / Postman
+
+Ver [`insomnia-collection.json`](insomnia-collection.json) — export v4 listo para importar en Insomnia.
+
+Pasos:
+1. Abrir Insomnia → Import → File
+2. Seleccionar `backend/docs/insomnia-collection.json`
+3. Configurar variable de entorno `base_url = http://localhost:7860`
+4. Ejecutar `POST /auth/login` y copiar el token a la variable `token`
+
+---
+
+## Variables de entorno completas
+
+Ver [`backend/.env.example`](../.env.example) para la plantilla completa.
+
+| Variable | Obligatoria | Descripción |
+|---|---|---|
+| `PORT` | Sí | Puerto del servidor (7860 para HF Spaces) |
+| `DATABASE_URL` | Sí | Path SQLite: `file:./polysignal.db` |
+| `JWT_SECRET` | Sí | Mínimo 32 chars |
+| `JWT_EXPIRES_IN` | No | Default `1h` |
+| `BCRYPT_ROUNDS` | No | Default `10` |
+| `CORS_ORIGIN` | No | Default `http://localhost:5173` |
+| `LOG_LEVEL` | No | Default `info` |
+| `HF_TOKEN` | No | HuggingFace (señales AI reales) |
+| `OPENROUTER_API_KEY` | No | Fallback LLM |
+| `FINNHUB_API_KEY` | No | Noticias para señales |
+| `TELEGRAM_BOT_TOKEN` | No | Alertas Telegram |

backend/docs/AUTH.md

@@ -0,0 +1,172 @@
+# Auth — Guía de uso
+
+Login con email + password. El backend emite un JWT (HS256, default 1h) que viaja en `Authorization: Bearer <token>`. No hay registro público en esta fase: los usuarios se crean vía el seeder. **No hay roles** — `requireAuth` solo valida que el usuario esté logueado y activo, para que pueda mantener sus preferencias.
+
+## 1. Variables de entorno
+
+Copiar `backend/.env.example` a `backend/.env` y rellenar:
+
+| Variable | Default | Notas |
+|---|---|---|
+| `NODE_ENV` | `development` | `development` \| `test` \| `production` |
+| `PORT` | `7860` | Puerto del backend (HF Spaces requiere 7860) |
+| `DATABASE_URL` | `file:./polysignal.db` | Path SQLite **relativo a `prisma/schema.prisma`** |
+| `JWT_SECRET` | — (obligatorio) | Mínimo 32 chars. Generar con `openssl rand -hex 48` |
+| `JWT_EXPIRES_IN` | `1h` | Formato `jsonwebtoken` (`1h`, `15m`, `7d`, ...) |
+| `BCRYPT_ROUNDS` | `10` | Entre 4 y 15 |
+| `CORS_ORIGIN` | `http://localhost:5173` | Origen del frontend en dev |
+| `LOG_LEVEL` | `info` | `trace`/`debug`/`info`/`warn`/`error`/`fatal` |
+
+> Si el `.env` falta una variable obligatoria o un valor es inválido, el backend imprime el error y aborta el arranque (validación con Zod en `src/config.js`).
+
+## 2. Primer arranque
+
+Desde `backend/`:
+
+```bash
+npm install                                  # instala deps
+npm run db:migrate -- --name init_auth       # solo la primera vez (ya hecho)
+npm run db:seed                              # crea los 2 usuarios de prueba
+npm run dev                                  # arranca en http://localhost:7860
+```
+
+Para inspeccionar la DB en una UI:
+
+```bash
+npm run db:studio
+```
+
+## 3. Usuarios de prueba
+
+Sembrados por `prisma/seed.js` (idempotente, se puede re-ejecutar):
+
+| Email | Password |
+|---|---|
+| `admin@polysignal.test` | `Admin123!` |
+| `user@polysignal.test`  | `User123!`  |
+
+## 4. Endpoints
+
+### `GET /api/v1/health`
+
+Sanity check. Respuesta:
+
+```json
+{ "ok": true, "data": { "status": "up" } }
+```
+
+### `POST /api/v1/auth/login`
+
+Body:
+
+```json
+{ "email": "admin@polysignal.test", "password": "Admin123!" }
+```
+
+Respuesta `200`:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiJ9...",
+    "user": { "id": 1, "email": "admin@polysignal.test" }
+  }
+}
+```
+
+Errores:
+
+| HTTP | code | cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Email inválido o password < 8 chars |
+| `401` | `INVALID_CREDENTIALS` | Email no existe, usuario desactivado, o password incorrecta |
+| `429` | `TOO_MANY_REQUESTS` | Más de 5 intentos en 15 min desde la misma IP |
+
+### `GET /api/v1/auth/me`
+
+Requiere header `Authorization: Bearer <token>`. Respuesta `200`:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "user": {
+      "id": 1,
+      "email": "admin@polysignal.test",
+      "isActive": true,
+      "createdAt": "2026-05-16T07:11:43.000Z"
+    }
+  }
+}
+```
+
+Errores:
+
+| HTTP | code | cuándo |
+|---|---|---|
+| `401` | `UNAUTHORIZED` | Sin header, token mal formado, expirado, manipulado, o usuario desactivado |
+
+## 5. Ejemplos con `curl`
+
+```bash
+# 1) Login y guardar token en variable
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' \
+  | jq -r '.data.token')
+
+# 2) Llamar a /me con el token
+curl -s http://localhost:7860/api/v1/auth/me \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+## 6. Login desde el frontend (referencia)
+
+El JWT es opaco para el front: basta con guardarlo (sessionStorage o estado en memoria) y enviarlo en cada request protegido.
+
+```js
+const res = await fetch('/api/v1/auth/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ email, password }),
+});
+const json = await res.json();
+if (!json.ok) throw new Error(json.error.code);
+const { token, user } = json.data;
+// guardar token y user
+
+// requests autenticados
+fetch('/api/v1/auth/me', { headers: { Authorization: `Bearer ${token}` } });
+```
+
+> En dev, Vite proxea `/api/*` al backend (`localhost:7860`); no hace falta CORS si va por el proxy, pero ya está configurado por si el front llama directo.
+
+## 7. Cómo proteger nuevos endpoints
+
+```js
+import { requireAuth } from '../middlewares/requireAuth.js';
+
+router.get('/positions', requireAuth, controller.list);
+```
+
+Dentro del controller, `req.user` ya está disponible con `{ id, email, isActive, createdAt }` — suficiente para filtrar datos del usuario logueado (ej. sus preferencias, posiciones, watchlist).
+
+## 8. Rotar `JWT_SECRET`
+
+Genera uno nuevo y reemplaza el valor de `JWT_SECRET` en `backend/.env`:
+
+```bash
+openssl rand -hex 48
+```
+
+Al cambiar el secreto, todos los tokens emitidos previamente quedan invalidados (los clientes deben volver a hacer login).
+
+## 9. Notas técnicas
+
+- **Hashing:** `bcryptjs` (puro JS, sin compilación nativa — más portable a HF Spaces) con coste `BCRYPT_ROUNDS` (default 10).
+- **JWT:** algoritmo `HS256`, claim `sub = user.id`, `email`, `iat`, `exp`.
+- **Rate limit en `/auth/login`:** `express-rate-limit`, 5 intentos / 15 min / IP.
+- **Validación de body:** zod schema en `src/auth/auth.validators.js`.
+- **Errores formateados:** todas las respuestas siguen `{ ok, data }` o `{ ok:false, error:{ code, message, details? } }` vía `src/utils/apiResponse.js` y el middleware `errorHandler`.
+- **Prisma:** singleton en `src/utils/prisma.js` para no abrir conexiones de más con `node --watch`.

backend/docs/FINNHUB.md

@@ -0,0 +1,199 @@
+# FINNHUB.md — Modulo de noticias financieras
+
+Fuente de titulares financieros para el pipeline de IA. Consulta la API REST de Finnhub (free tier) y proporciona noticias filtradas por relevancia al mercado analizado.
+
+**No expone endpoints REST publicos.** Es un modulo interno consumido unicamente por `signals/aiPipeline.js` durante la generacion de senales (cada 5 min).
+
+---
+
+## Variables de entorno
+
+| Variable | Obligatoria | Descripcion |
+|---|---|---|
+| `FINNHUB_API_KEY` | No | API key de Finnhub (finnhub.io). Sin ella el modulo devuelve array vacio y el pipeline usa rule-based. |
+
+---
+
+## API interna
+
+### `getMarketNews(category, limit)`
+
+**Archivo:** `src/finnhub/finnhub.client.js`
+
+Obtiene noticias generales del mercado por categoria.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `category` | string | `"general"` | Categoria: `general`, `forex`, `crypto`, `merger` |
+| `limit` | int | `50` | Maximo de noticias a devolver |
+
+**Retorno:** `Promise<Object[]>` — array de noticias normalizadas.
+
+**Noticia normalizada:**
+
+```json
+{
+  "id": 12345,
+  "headline": "Fed signals potential rate cut...",
+  "summary": "The Federal Reserve hinted at...",
+  "url": "https://example.com/news/12345",
+  "source": "Reuters",
+  "related": "AAPL",
+  "datetime": "2026-05-15T14:30:00.000Z"
+}
+```
+
+---
+
+### `getCompanyNews(symbol, daysBack)`
+
+**Archivo:** `src/finnhub/finnhub.client.js`
+
+Obtiene noticias de una empresa especifica en un rango de fechas.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `symbol` | string | — | Simbolo bursatil (ej. `AAPL`, `TSLA`, `BTC`) |
+| `daysBack` | int | `7` | Dias hacia atras desde hoy |
+
+**Retorno:** `Promise<Object[]>` — noticias normalizadas de la empresa.
+
+---
+
+### `fetchFinancialNews(daysBack)`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Agrega noticias de multiples categorias (`general`, `forex`, `crypto`) para el pipeline de IA.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `daysBack` | int | `7` | No aplica directamente; se usa el rango por defecto de Finnhub |
+
+**Retorno:** `Promise<Object[]>` — hasta 90 noticias agregadas (50 general + 20 forex + 20 crypto).
+
+---
+
+### `filterNewsByRelevance(news, question)`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Filtra noticias por keywords extraidas de la pregunta del mercado. Elimina stop words en ingles y espanol; matching case-insensitive.
+
+**Parametros**
+
+| Param | Tipo | Descripcion |
+|---|---|---|
+| `news` | Object[] | Array de noticias normalizadas |
+| `question` | string | Pregta del mercado (ej. "Will Bitcoin reach $100k?") |
+
+**Retorno:** `Object[]` — noticias que contienen al menos una keyword en `headline` o `summary`.
+
+---
+
+### `fetchHeadlinesForPipeline({ symbols, daysBack, limitPerSymbol })`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Obtiene noticias de multiples simbolos en paralelo, truncando a maximo 5 simbolos para respetar el rate limit.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `symbols` | string[] | `[]` | Lista de simbolos bursatiles |
+| `daysBack` | int | `7` | Dias hacia atras |
+| `limitPerSymbol` | int | `20` | Maximo de noticias por simbolo |
+
+**Retorno:** `Promise<Object[]>` — noticias agregadas con campo `symbol` anadido.
+
+**Limitacion:** si `symbols.length > 5`, se trunca a 5 y se emite warning en logs.
+
+---
+
+## Pipeline de noticias dentro de la generacion de senales
+
+```
+scheduler.js (cada 5 min)
+    ↓
+aiPipeline.run(market)
+    ↓ Paso 1: Obtener noticias
+    fetchFinancialNews()           → general + forex + crypto
+    ↓ Paso 2: Filtrar por relevancia
+    filterNewsByRelevance(news, market.question)
+    ↓ Paso 3: Filtrar por sentimiento (FinBERT)
+    filterWithFinBERT(headlines)
+    ↓ Paso 4: Generar senal (Qwen3-8B / OpenRouter / rule-based)
+```
+
+**Nota:** si Finnhub no esta configurado o falla, los pasos 1-2 devuelven array vacio y el pipeline continua con rule-based usando el precio del mercado.
+
+---
+
+## Rate limiter y restricciones
+
+| Restriccion | Implementacion |
+|---|---|
+| **Free tier: 60 llamadas/min** | Rate limiter en memoria en `finnhub.client.js`. Si se excede, devuelve `[]`. |
+| **Sin API key** | `ensureApiKey()` devuelve `false`; todas las funciones retornan `[]` sin lanzar error. |
+| **Sin endpoints REST** | El modulo es puramente interno; no se expone via HTTP. |
+| **Limite de 5 simbolos** | `fetchHeadlinesForPipeline` trunca `symbols` a 5 para no saturar el rate limit. |
+| **Errores de red** | Capturados internamente; se loguean como `warn` y se retorna `[]`. |
+
+**Calculo de uso tipico:**
+- `fetchFinancialNews()` = 3 llamadas (general + forex + crypto)
+- Top 20 mercados cada 5 min = 20 x 3 = 60 llamadas/5min (en el limite exacto del free tier)
+
+---
+
+## Ejemplo de uso interno
+
+```js
+// Desde aiPipeline.js
+import { fetchFinancialNews, filterNewsByRelevance } from '../finnhub/finnhub.service.js';
+
+async function run(market) {
+  // 1. Obtener noticias
+  const allNews = await fetchFinancialNews(30);
+
+  // 2. Filtrar por relevancia respecto al mercado
+  const relevant = filterNewsByRelevance(allNews, market.question);
+
+  // 3. Continuar con FinBERT + Qwen3-8B...
+}
+```
+
+---
+
+## Logs esperados
+
+```
+# Sin API key configurada
+[DEBUG] Finnhub API key not configured, returning empty array
+
+# Rate limit excedido
+[WARN] Finnhub rate limit exceeded (60 calls/min), returning empty array
+
+# Pipeline continua sin noticias
+[WARN] news fetch failed, continuing without news
+```
+
+---
+
+## Archivos del modulo
+
+```
+backend/src/finnhub/
+├── finnhub.client.js   # Cliente HTTP + rate limiter
+└── finnhub.service.js  # Logica de negocio y filtrado
+```
+
+---
+
+*Ultima actualizacion: mayo 2026*

backend/docs/MARKETS.md

@@ -0,0 +1,193 @@
+# MARKETS.md — Módulo de mercados
+
+Referencia para el frontend: contrato HTTP, mapping de datos de Polymarket, evento socket y errores.
+
+---
+
+## Variables de entorno requeridas
+
+```
+DATABASE_URL=file:./backend/prisma/polysignal.db
+PORT=7860
+```
+
+No se necesita clave de API para Polymarket Gamma (pública).
+
+---
+
+## Endpoints
+
+### `GET /api/v1/markets`
+
+Lista paginada de mercados activos sincronizados desde Polymarket. **No requiere autenticación.**
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+| `category` | string | — | Filtro: `politics` \| `crypto` \| `economics` \| `sports` |
+| `status` | string | `active` | Filtro: `active` \| `closed` \| `resolved` |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "category": null,
+      "countryCode": null,
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "volumeEur": 38608906.44,
+      "liquidityEur": 2301398.64,
+      "status": "active",
+      "closesAt": "2028-11-07T00:00:00.000Z",
+      "lastSynced": "2026-05-16T09:38:30.204Z"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "limit": 1,
+    "offset": 0
+  }
+}
+```
+
+> `category` y `countryCode` pueden ser `null` si Polymarket no los proporciona.
+
+---
+
+### `GET /api/v1/markets/:id`
+
+Detalle de un mercado por su ID de Polymarket. **No requiere autenticación.**
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | string | ID numérico de Polymarket (ej. `559677`) |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "559677",
+    "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+    "category": null,
+    "countryCode": null,
+    "yesPrice": 0.0075,
+    "noPrice": 0.9925,
+    "volumeEur": 38608906.44,
+    "liquidityEur": 2301398.64,
+    "status": "active",
+    "closesAt": "2028-11-07T00:00:00.000Z",
+    "lastSynced": "2026-05-16T09:38:30.204Z"
+  }
+}
+```
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "Market not found" }
+}
+```
+
+---
+
+### `GET /api/v1/markets/:id/signal`
+
+Señal AI más reciente para un mercado. Ver [SIGNALS.md](SIGNALS.md) para el contrato completo.
+
+---
+
+## Mapping Polymarket Gamma API → `Market`
+
+URL de origen: `https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=100`
+
+| Campo Gamma API | Campo `Market` | Transformación |
+|---|---|---|
+| `id` | `id` | String (ID numérico de Polymarket) |
+| `question` | `question` | Directo |
+| `category` | `category` | Minúsculas; `null` si Gamma no lo envía |
+| — | `countryCode` | `null` por defecto (no proporcionado por Gamma) |
+| `outcomePrices[0]` | `yesPrice` | `parseFloat`; rango 0.0–1.0 |
+| `outcomePrices[1]` | `noPrice` | `parseFloat`; rango 0.0–1.0 |
+| `volume` | `volumeEur` | `parseFloat(volume) * 0.93` (USD→EUR tasa fija) |
+| `liquidity` | `liquidityEur` | Igual que `volumeEur` |
+| `active` + `closed` + `archived` | `status` | `active=true → "active"`, `closed=true → "closed"`, `archived=true → "resolved"` |
+| `endDateIso` | `closesAt` | `new Date(endDateIso)` |
+| — | `lastSynced` | `new Date()` en el momento del upsert |
+
+La sincronización usa `prisma.market.upsert({ where: { id }, ... })` para evitar duplicados.
+
+---
+
+## Socket — evento `market_update`
+
+Emitido por `src/socket/broadcaster.js` cada 30 s (tras `syncMarkets`).
+
+**Nombre del evento:** `market_update`
+
+**Payload**
+
+```json
+{
+  "marketId": "0x1a2b...",
+  "yesPrice": 0.63,
+  "noPrice": 0.37,
+  "volumeEur": 125000.00
+}
+```
+
+**Uso en el frontend (Socket.io client)**
+
+```js
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:7860');
+socket.on('market_update', ({ marketId, yesPrice, noPrice }) => {
+  // actualizar estado local del mercado
+});
+```
+
+En producción (HF Spaces) el frontend y backend comparten origen → usar `io()` sin URL.
+
+---
+
+## Ejemplos `curl`
+
+```bash
+# Listar mercados (primeros 5)
+curl "http://localhost:7860/api/v1/markets?limit=5"
+
+# Filtrar por estado
+curl "http://localhost:7860/api/v1/markets?status=active&limit=10"
+
+# Detalle de un mercado
+curl "http://localhost:7860/api/v1/markets/559677"
+
+# Señal AI del mercado
+curl "http://localhost:7860/api/v1/markets/559677/signal"
+```
+
+---
+
+## Códigos de error relevantes
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Parámetro inválido (ej. `limit` > 100) |
+| `404` | `NOT_FOUND` | ID de mercado no existe en DB |
+| `500` | `INTERNAL` | Error inesperado del servidor |
+
+Los endpoints de markets **no requieren autenticación** — son datos públicos.

backend/docs/POSITIONS.md

@@ -0,0 +1,196 @@
+# POSITIONS.md — Módulo de posiciones
+
+Simulador de capital virtual. Las posiciones no generan órdenes reales en Polymarket — son un tracking local de apuestas simuladas en euros.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `POST /api/v1/positions`
+
+Abre una posición nueva en un mercado activo.
+
+**Body**
+
+```json
+{
+  "marketId": "559677",
+  "outcome": "YES",
+  "amountEur": 100
+}
+```
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado (debe existir y estar `active`) |
+| `outcome` | `"YES"` \| `"NO"` | Lado de la apuesta |
+| `amountEur` | float > 0 | Importe a invertir en euros |
+
+**Respuesta `201`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 1,
+    "userId": 1,
+    "marketId": "559677",
+    "outcome": "YES",
+    "amountEur": 100,
+    "entryPrice": 0.0075,
+    "currentPrice": 0.0075,
+    "pnl": 0,
+    "kellyFraction": 0.25,
+    "status": "open",
+    "openedAt": "2026-05-16T09:14:55.750Z",
+    "closedAt": null,
+    "market": {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "status": "active"
+    }
+  }
+}
+```
+
+**Campos de respuesta relevantes**
+
+| Campo | Descripción |
+|---|---|
+| `entryPrice` | Precio en el momento de abrir (`yesPrice` o `noPrice` según `outcome`) |
+| `currentPrice` | Precio actual (actualizado por `updatePositionsPnL` cada 30s) |
+| `pnl` | Profit & Loss en EUR (negativo = pérdida) |
+| `kellyFraction` | Fracción de Kelly calculada (capada al 0.25) |
+| `status` | `"open"` \| `"closed"` |
+
+---
+
+### `GET /api/v1/positions`
+
+Lista todas las posiciones del usuario autenticado (abiertas y cerradas).
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 1,
+      "userId": 1,
+      "marketId": "559677",
+      "outcome": "YES",
+      "amountEur": 100,
+      "entryPrice": 0.0075,
+      "currentPrice": 0.0075,
+      "pnl": 0,
+      "kellyFraction": 0.25,
+      "status": "closed",
+      "openedAt": "2026-05-16T09:14:55.750Z",
+      "closedAt": "2026-05-16T09:15:04.155Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+        "yesPrice": 0.0075,
+        "noPrice": 0.9925,
+        "status": "active"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### `DELETE /api/v1/positions/:id`
+
+Cierra una posición abierta. Calcula el P&L final con el precio actual.
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la posición |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 1,
+    "status": "closed",
+    "closedAt": "2026-05-16T09:15:04.155Z",
+    "pnl": -99.25
+  }
+}
+```
+
+**Errores**
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `404` | `NOT_FOUND` | Posición no existe o no pertenece al usuario |
+| `409` | `CONFLICT` | La posición ya está cerrada |
+
+---
+
+## Criterio de Kelly
+
+`kellyFraction = (pWin - pLoss) / pWin` capado al 25% y nunca negativo.
+
+- `pWin` = precio del outcome elegido (`yesPrice` o `noPrice`)
+- `pLoss` = `1 - pWin`
+
+El resultado es informativo — el usuario decide cuánto invertir.
+
+---
+
+## Socket — actualización de P&L
+
+El job `updatePositionsPnL` recalcula `currentPrice` y `pnl` de todas las posiciones abiertas cada 30s. No emite evento de socket propio; el frontend puede re-fetch `GET /positions` tras recibir `market_update`.
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Abrir posición
+curl -s -X POST http://localhost:7860/api/v1/positions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"marketId":"559677","outcome":"YES","amountEur":50}' | jq
+
+# Listar posiciones
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/positions | jq
+
+# Cerrar posición (id=1)
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/positions/1 | jq
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Body inválido (outcome no es YES/NO, amountEur <= 0) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `404` | `NOT_FOUND` | Mercado o posición no existe |
+| `409` | `CONFLICT` | Mercado no activo o posición ya cerrada |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/SIGNALS.md

@@ -0,0 +1,128 @@
+# SIGNALS.md — Módulo de señales AI
+
+Referencia para el frontend: señales generadas por la pipeline FinBERT + Qwen3-8B sobre mercados de Polymarket.
+
+---
+
+## Variables de entorno (opcionales)
+
+| Variable | Descripción |
+|---|---|
+| `HF_TOKEN` | HuggingFace Pro token — FinBERT + Qwen3-8B |
+| `OPENROUTER_API_KEY` | Fallback LLM si HuggingFace está saturado |
+| `FINNHUB_API_KEY` | Noticias financieras para contexto |
+
+Sin ninguna clave, el backend usa una señal **rule-based** derivada de los precios del mercado.
+
+---
+
+## Endpoints
+
+### `GET /api/v1/markets/:id/signal`
+
+Señal AI más reciente para el mercado. **No requiere autenticación.**
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | string | ID numérico de Polymarket (ej. `559677`) |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 81,
+    "marketId": "559677",
+    "signal": "bearish",
+    "confidence": 0.9,
+    "summary": "Market strongly favors NO at 99% probability. Downside momentum dominates.",
+    "keyRisk": "Unexpected positive developments could reverse this rapidly.",
+    "newsCount": 0,
+    "modelVersion": "Qwen3-8B",
+    "generatedAt": "2026-05-16T09:35:00.110Z"
+  }
+}
+```
+
+**Campos**
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la señal en DB |
+| `marketId` | string | ID del mercado |
+| `signal` | `"bullish"` \| `"bearish"` \| `"neutral"` | Dirección recomendada |
+| `confidence` | float (0–1) | Nivel de confianza del modelo |
+| `summary` | string | Resumen del análisis |
+| `keyRisk` | string \| null | Principal riesgo identificado |
+| `newsCount` | int | Noticias procesadas por Finnhub |
+| `modelVersion` | string | Modelo que generó la señal (`Qwen3-8B`, `OpenRouter`, `rule-based`) |
+| `generatedAt` | ISO 8601 | Timestamp de generación |
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "No signal found for this market" }
+}
+```
+
+---
+
+## Pipeline de generación
+
+1. **Finnhub** → noticias relacionadas por keywords del `question`
+2. **FinBERT** (HuggingFace) → filtro de sentimiento; descarta noticias irrelevantes
+3. **Qwen3-8B** (HuggingFace) → genera señal JSON `{ signal, confidence, summary, keyRisk }`
+4. **OpenRouter** → fallback si HF está saturado (HTTP 503)
+5. **Rule-based** → fallback final: `yesPrice > 0.6 → bullish`, `yesPrice < 0.4 → bearish`, else `neutral`
+
+La señal se persiste en `AISignal` y se emite por socket (`ai_signal`).
+
+---
+
+## Socket — evento `ai_signal`
+
+Emitido por `src/socket/broadcaster.js` cada 5 min (tras `generateSignals`).
+
+**Nombre del evento:** `ai_signal`
+
+**Payload**
+
+```json
+{
+  "marketId": "559677",
+  "signal": "bearish",
+  "confidence": 0.9,
+  "summary": "Market strongly favors NO at 99% probability."
+}
+```
+
+**Uso en el frontend**
+
+```js
+socket.on('ai_signal', ({ marketId, signal, confidence }) => {
+  // actualizar badge de señal en la tarjeta del mercado
+});
+```
+
+---
+
+## Ejemplos `curl`
+
+```bash
+# Señal más reciente de un mercado
+curl "http://localhost:7860/api/v1/markets/559677/signal"
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `404` | `NOT_FOUND` | No hay señal generada aún para ese mercado |
+| `500` | `INTERNAL` | Error inesperado del servidor |

backend/docs/WATCHLIST.md

@@ -0,0 +1,157 @@
+# WATCHLIST.md — Módulo de watchlist
+
+Mercados favoritos del usuario con umbral de alerta opcional. Cuando `yesPrice >= alertThreshold`, el job `processAlerts` crea una `Alert` y envía notificación por Telegram.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `POST /api/v1/watchlist`
+
+Añade un mercado a la watchlist del usuario.
+
+**Body**
+
+```json
+{
+  "marketId": "559677",
+  "alertThreshold": 0.75
+}
+```
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado (debe existir en DB) |
+| `alertThreshold` | float (0–1) \| null | Precio YES que dispara la alerta; `null` para no alertar |
+
+**Respuesta `201`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 2,
+    "userId": 1,
+    "marketId": "559677",
+    "alertThreshold": 0.75,
+    "createdAt": "2026-05-16T09:21:41.606Z",
+    "market": {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "status": "active"
+    }
+  }
+}
+```
+
+**Respuesta `409`** — mercado ya está en la watchlist del usuario:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "CONFLICT", "message": "Market already in watchlist" }
+}
+```
+
+---
+
+### `GET /api/v1/watchlist`
+
+Lista todos los mercados en la watchlist del usuario con datos de mercado embebidos.
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 2,
+      "userId": 1,
+      "marketId": "559677",
+      "alertThreshold": 0.001,
+      "createdAt": "2026-05-16T09:21:41.606Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+        "yesPrice": 0.0075,
+        "noPrice": 0.9925,
+        "status": "active"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### `DELETE /api/v1/watchlist/:marketId`
+
+Elimina un mercado de la watchlist del usuario.
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado |
+
+**Respuesta `204`** — sin body.
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "Watchlist entry not found" }
+}
+```
+
+---
+
+## Lógica de alertas
+
+El job `processAlerts` (cron `* * * * *`) evalúa cada entrada de watchlist con `alertThreshold` definido:
+
+- Si `market.yesPrice >= alertThreshold` → crea `Alert` + envía Telegram + emite `price_alert` por socket.
+- Deduplicación: no se crea una segunda alerta si ya existe una para el mismo mercado en los últimos 5 min.
+
+Para recibir alertas por Telegram, el usuario debe tener `telegramChatId` configurado en su perfil (campo opcional en `User`).
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Añadir a watchlist con umbral 75%
+curl -s -X POST http://localhost:7860/api/v1/watchlist \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"marketId":"559677","alertThreshold":0.75}' | jq
+
+# Listar watchlist
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/watchlist | jq
+
+# Eliminar de watchlist
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/watchlist/559677"
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Body inválido (marketId vacío, threshold fuera de 0–1) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `404` | `NOT_FOUND` | Mercado no existe en DB o entrada no encontrada al borrar |
+| `409` | `CONFLICT` | Mercado ya en watchlist |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/insomnia-collection.json

@@ -0,0 +1,206 @@
+{
+  "_type": "export",
+  "__export_format": 4,
+  "__export_date": "2026-05-16",
+  "__export_source": "polysignal-backend",
+  "resources": [
+    {
+      "_id": "env_polysignal",
+      "_type": "environment",
+      "name": "PolySignal Dev",
+      "data": {
+        "base_url": "http://localhost:7860",
+        "token": ""
+      }
+    },
+    {
+      "_id": "wrk_polysignal",
+      "_type": "workspace",
+      "name": "PolySignal Backend",
+      "description": "API REST PolySignal — mercados Polymarket + señales AI"
+    },
+    {
+      "_id": "grp_auth",
+      "_type": "request_group",
+      "name": "Auth",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_health",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "GET /health",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/health",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_login",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "POST /auth/login",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/auth/login",
+      "headers": [{ "name": "Content-Type", "value": "application/json" }],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"email\": \"admin@polysignal.test\",\n  \"password\": \"Admin123!\"\n}"
+      }
+    },
+    {
+      "_id": "req_me",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "GET /auth/me",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/auth/me",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_markets",
+      "_type": "request_group",
+      "name": "Markets",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_markets_list",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets",
+      "parameters": [
+        { "name": "limit", "value": "10" },
+        { "name": "offset", "value": "0" }
+      ],
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_markets_by_id",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets/:id",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets/559677",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_market_signal",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets/:id/signal",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets/559677/signal",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "grp_positions",
+      "_type": "request_group",
+      "name": "Positions",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_positions_open",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "POST /positions (open)",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/positions",
+      "headers": [
+        { "name": "Authorization", "value": "Bearer {{ _.token }}" },
+        { "name": "Content-Type", "value": "application/json" }
+      ],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"marketId\": \"559677\",\n  \"outcome\": \"YES\",\n  \"amountEur\": 100\n}"
+      }
+    },
+    {
+      "_id": "req_positions_list",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "GET /positions",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/positions",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "req_positions_close",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "DELETE /positions/:id (close)",
+      "method": "DELETE",
+      "url": "{{ _.base_url }}/api/v1/positions/1",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_watchlist",
+      "_type": "request_group",
+      "name": "Watchlist",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_watchlist_add",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "POST /watchlist",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/watchlist",
+      "headers": [
+        { "name": "Authorization", "value": "Bearer {{ _.token }}" },
+        { "name": "Content-Type", "value": "application/json" }
+      ],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"marketId\": \"559677\",\n  \"alertThreshold\": 0.75\n}"
+      }
+    },
+    {
+      "_id": "req_watchlist_list",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "GET /watchlist",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/watchlist",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "req_watchlist_delete",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "DELETE /watchlist/:marketId",
+      "method": "DELETE",
+      "url": "{{ _.base_url }}/api/v1/watchlist/559677",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_alerts",
+      "_type": "request_group",
+      "name": "Alerts",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_alerts_list",
+      "_type": "request",
+      "parentId": "grp_alerts",
+      "name": "GET /alerts",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/alerts",
+      "parameters": [
+        { "name": "limit", "value": "20" },
+        { "name": "offset", "value": "0" }
+      ],
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    }
+  ]
+}

backend/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "polysignal-backend",
+  "version": "1.0.0",
+  "description": "Backend API de PolySignal — Hackathon CIFO Barcelona La Violeta",
+  "type": "module",
+  "main": "src/index.js",
+  "prisma": {
+    "schema": "prisma/schema.prisma",
+    "seed": "node prisma/seed.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "db:migrate": "prisma migrate dev",
+    "db:generate": "prisma generate",
+    "db:seed": "node prisma/seed.js",
+    "db:studio": "prisma studio"
+  },
+  "dependencies": {
+    "@gradio/client": "^2.2.0",
+    "@prisma/client": "^6.19.2",
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^5.2.1",
+    "express-rate-limit": "^7.4.0",
+    "helmet": "^8.0.0",
+    "jsonwebtoken": "^9.0.2",
+    "node-cron": "^4.2.1",
+    "pino": "^9.5.0",
+    "prisma": "^6.19.2",
+    "socket.io": "^4.8.3",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

backend/prisma/schema.prisma

@@ -0,0 +1,124 @@
+/**
+ * Schema de Prisma ORM para base de datos SQLite.
+ *
+ * Define 6 modelos: User, Market, AISignal, Position, Watchlist, Alert.
+ * Relaciones:
+ *   - Market 1:N AISignal, Position, Watchlist, Alert
+ *   - User   1:N Position, Watchlist, Alert
+ *
+ * No modificar sin consenso del equipo. Generar migraciones con:
+ *   npx prisma migrate dev
+ *   npx prisma generate
+ */
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id             Int        @id @default(autoincrement())
+  email          String     @unique
+  passwordHash   String
+  isActive       Boolean    @default(true)
+  telegramChatId String?                         // Configurado manualmente para demo
+  createdAt      DateTime   @default(now())
+  updatedAt      DateTime   @updatedAt
+
+  positions Position[]
+  watchlist Watchlist[]
+  alerts    Alert[]
+}
+
+model Market {
+  id           String     @id                // ID nativo de Polymarket
+  question     String                         // Texto de la pregunta del mercado
+  category     String?                        // politics | crypto | economics | sports
+  countryCode  String?                        // ISO2 — usado por Leaflet para burbujas
+  yesPrice     Float?                         // Precio YES: 0.0 a 1.0
+  noPrice      Float?                         // Precio NO: 0.0 a 1.0
+  volumeEur    Float?                         // Volumen en Eur
+  liquidityEur Float?                         // Liquidez en Eur
+  spread       Float?                         // Bid/ask spread (0-1, ej 0.02 = 2c)
+  bestBid      Float?                         // Mejor oferta de compra
+  bestAsk      Float?                         // Mejor oferta de venta
+  clobTokenId  String?                        // YES outcome CLOB token ID (para prices-history)
+  analyzable   Boolean    @default(true)      // Si la IA tiene edge plausible aqui
+  status       String     @default("active")  // active | closed | resolved
+  closesAt     DateTime?                      // Fecha de cierre del mercado
+  lastSynced   DateTime   @default(now())     // Ultima sincronizacion de precios
+
+  signals   AISignal[]
+  positions Position[]
+  watchlist Watchlist[]
+  alerts    Alert[]
+}
+
+model AISignal {
+  id           Int      @id @default(autoincrement())
+  marketId     String
+  market       Market   @relation(fields: [marketId], references: [id], onDelete: Cascade)
+  signal       String                          // bullish | bearish | neutral
+  confidence   Float                           // 0.0 a 1.0
+  summary      String?                         // 2 frases generadas por Qwen3
+  keyRisk      String?                         // 1 frase de riesgo principal
+  newsCount    Int      @default(0)            // Titulares relevantes usados
+  modelVersion String   @default("Qwen3-8B")   // Modelo LLM que genero la senal
+  impliedProb  Float?                          // Probabilidad implicita YES al generar (0-1)
+  fairProb     Float?                          // Probabilidad "justa" segun IA (0-1)
+  edgePoints   Float?                          // (fairProb - impliedProb) * 100, signo conserva direccion
+  generatedAt  DateTime @default(now())
+
+  @@index([marketId, generatedAt])
+}
+
+model Position {
+  id            Int      @id @default(autoincrement())
+  userId        Int
+  user          User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  marketId      String
+  market        Market   @relation(fields: [marketId], references: [id], onDelete: Cascade)
+  outcome       String                          // YES | NO
+  amountEur     Float                           // Capital virtual apostado
+  entryPrice    Float                           // Precio al abrir la posicion
+  currentPrice  Float?                          // Precio actual (actualizado por scheduler)
+  pnl           Float    @default(0)            // Profit and Loss calculado
+  kellyFraction Float?                          // Fraccion de Kelly al abrir
+  status        String   @default("open")       // open | closed
+  openedAt      DateTime @default(now())
+  closedAt      DateTime?
+
+  @@index([userId, status])
+  @@index([marketId])
+}
+
+model Watchlist {
+  id              Int      @id @default(autoincrement())
+  userId          Int
+  user            User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  marketId        String
+  market          Market   @relation(fields: [marketId], references: [id], onDelete: Cascade)
+  alertThreshold  Float?                       // Umbral de precio para alerta Telegram
+  createdAt       DateTime @default(now())
+
+  @@unique([userId, marketId])
+  @@index([userId])
+}
+
+model Alert {
+  id       Int      @id @default(autoincrement())
+  userId   Int
+  user     User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  marketId String
+  market   Market   @relation(fields: [marketId], references: [id], onDelete: Cascade)
+  type     String                          // price_threshold | signal_change
+  message  String                          // Texto enviado por Telegram
+  sentAt   DateTime @default(now())
+
+  @@index([userId, sentAt])
+  @@index([marketId])
+}

backend/prisma/seed.js

@@ -0,0 +1,32 @@
+import bcrypt from 'bcryptjs';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const ROUNDS = Number(process.env.BCRYPT_ROUNDS ?? 10);
+
+const users = [
+  { email: 'admin@polysignal.test', password: 'Admin123!' },
+  { email: 'user@polysignal.test', password: 'User123!' },
+];
+
+const run = async () => {
+  for (const u of users) {
+    const passwordHash = await bcrypt.hash(u.password, ROUNDS);
+    const record = await prisma.user.upsert({
+      where: { email: u.email },
+      update: { passwordHash, isActive: true },
+      create: { email: u.email, passwordHash, isActive: true },
+    });
+    console.log(`seeded user ${record.email} (id=${record.id})`);
+  }
+};
+
+run()
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });

backend/src/config.js

@@ -0,0 +1,48 @@
+/**
+ * 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';
+
+const schema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  PORT: z.coerce.number().int().positive().default(7860),
+  DATABASE_URL: z.string().min(1, 'DATABASE_URL is required'),
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
+  JWT_EXPIRES_IN: z.string().default('1h'),
+  BCRYPT_ROUNDS: z.coerce.number().int().min(4).max(15).default(10),
+  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(),
+});
+
+const parsed = schema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('Invalid environment variables:');
+  console.error(parsed.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const config = Object.freeze(parsed.data);

frontend/index.html

@@ -0,0 +1,384 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>PolySignal — Dashboard de Inteligencia de Mercados</title>
+  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+</head>
+<body>
+  <div id="app" class="layout">
+
+    <!-- Sidebar -->
+    <aside class="sidebar" id="sidebar">
+      <div class="sidebar-toggle" id="sidebar-toggle" title="Colapsar sidebar">◀</div>
+      <nav class="sidebar-nav">
+        <div class="nav-item active" data-view="dashboard">
+          <span class="nav-icon">◈</span>
+          <span class="nav-label">Panel</span>
+        </div>
+        <div class="nav-item" data-view="positions">
+          <span class="nav-icon">◫</span>
+          <span class="nav-label">Posiciones</span>
+        </div>
+        <div class="nav-item" data-view="watchlist">
+          <span class="nav-icon">☆</span>
+          <span class="nav-label">Seguimiento</span>
+        </div>
+        <div class="nav-item" data-view="alerts">
+          <span class="nav-icon">⚡</span>
+          <span class="nav-label">Alertas</span>
+        </div>
+      </nav>
+      <div class="sidebar-footer">
+        v0.1.0 · HF Spaces
+      </div>
+    </aside>
+
+    <!-- Topbar -->
+    <header class="topbar" id="topbar">
+      <div class="topbar-logo">
+        <div class="logo-dot"></div>
+        <span class="logo-text">PolySignal</span>
+      </div>
+      <div class="topbar-stats">
+        <div class="live-badge">
+          <div class="live-dot"></div>
+          EN VIVO
+        </div>
+        <div class="stats-track">
+          <div class="stat">
+            <span class="stat-label">Mercados</span>
+            <span class="stat-val" id="stat-markets">2.847</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Volumen 24h</span>
+            <span class="stat-val" id="stat-volume">€4,2M</span>
+            <span class="stat-delta up" id="stat-volume-delta">+12,4%</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Señales IA</span>
+            <span class="stat-val" id="stat-signals">183</span>
+            <span class="stat-delta up" id="stat-signals-delta">alcista</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Alertas enviadas</span>
+            <span class="stat-val" id="stat-alerts">47</span>
+            <span class="stat-delta neutral">hoy</span>
+          </div>
+          <div class="legend end">
+            <div class="legend-item"><div class="legend-dot green"></div>alcista</div>
+            <div class="legend-item"><div class="legend-dot red"></div>bajista</div>
+            <div class="legend-item"><div class="legend-dot gray"></div>neutral</div>
+          </div>
+          <!-- Duplicate for infinite scroll -->
+          <div class="stat">
+            <span class="stat-label">Mercados</span>
+            <span class="stat-val" id="stat-markets-dup">2.847</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Volumen 24h</span>
+            <span class="stat-val" id="stat-volume-dup">€4,2M</span>
+            <span class="stat-delta up">+12,4%</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Señales IA</span>
+            <span class="stat-val" id="stat-signals-dup">183</span>
+            <span class="stat-delta up">alcista</span>
+          </div>
+          <div class="stat">
+            <span class="stat-label">Alertas enviadas</span>
+            <span class="stat-val" id="stat-alerts-dup">47</span>
+            <span class="stat-delta neutral">hoy</span>
+          </div>
+          <div class="legend">
+            <div class="legend-item"><div class="legend-dot green"></div>alcista</div>
+            <div class="legend-item"><div class="legend-dot red"></div>bajista</div>
+            <div class="legend-item"><div class="legend-dot gray"></div>neutral</div>
+          </div>
+        </div>
+      </div>
+      <div class="topbar-filters desktop-only">
+        <select class="filter-select" id="filter-trend" title="Tendencias">
+          <option value="">🔥 Todos los mercados</option>
+          <option value="hot">🔥 Más activos</option>
+          <option value="bullish-trend">📈 Tendencia alcista</option>
+          <option value="bearish-trend">📉 Tendencia bajista</option>
+          <option value="volatile">⚡ Más volátiles</option>
+          <option value="high-volume">📊 Alto volumen</option>
+        </select>
+        <select class="filter-select" id="filter-category" title="Categoría">
+          <option value="">Todas las categorías</option>
+        </select>
+
+      </div>
+      <div class="topbar-actions">
+        <button class="btn-ghost desktop-only" id="btn-telegram">Alertas Telegram</button>
+        <button class="icon-btn mobile-only" id="btn-telegram-mobile" title="Alertas Telegram">✈</button>
+        <button class="icon-btn" id="btn-notif" title="Notificaciones">◉</button>
+        <button class="btn-ghost desktop-only" id="btn-auth">Entrar</button>
+        <button class="icon-btn auth-indicator mobile-only" id="btn-auth-mobile" title="Entrar"></button>
+      </div>
+    </header>
+
+    <!-- Main content area -->
+    <main class="main" id="main">
+
+      <!-- DASHBOARD VIEW -->
+      <section class="view active" id="view-dashboard">
+        <div class="dashboard-grid">
+
+          <!-- Map Panel -->
+          <div class="panel map-panel" id="panel-map">
+            <div class="panel-header" data-panel="map">
+              <div class="panel-title">
+                <span>◈</span>
+                Mapa global
+              </div>
+              <div class="map-legend">
+                <div class="legend-item"><div class="legend-dot green"></div>alcista</div>
+                <div class="legend-item"><div class="legend-dot red"></div>bajista</div>
+                <div class="legend-item"><div class="legend-dot gray"></div>neutral</div>
+              </div>
+              <span class="panel-toggle">▼</span>
+            </div>
+            <div class="panel-body">
+              <div id="map-container"></div>
+            </div>
+          </div>
+
+          <!-- Signals Panel -->
+          <div class="panel signals-panel" id="panel-signals">
+            <div class="panel-header" data-panel="signals">
+              <div class="panel-title">
+                <span>◈</span>
+                Señales IA — mercados top
+              </div>
+              <span class="panel-toggle">▼</span>
+            </div>
+            <div class="panel-body">
+              <div class="signals-list" id="signals-list"></div>
+              <div class="positions-separator">
+                <div class="panel-title mb-sm">Mis posiciones</div>
+                <div id="mini-positions"></div>
+              </div>
+            </div>
+          </div>
+
+          <!-- Detail Panel -->
+          <div class="panel detail-panel" id="panel-detail">
+            <div class="panel-header" data-panel="detail">
+              <div class="panel-title">
+                <span>◈</span>
+                Detalle del mercado
+              </div>
+              <span class="panel-toggle">▼</span>
+            </div>
+            <div class="panel-body" id="detail-body">
+              <!-- Dynamic content -->
+            </div>
+          </div>
+
+        </div>
+      </section>
+
+      <!-- POSITIONS VIEW -->
+      <section class="view" id="view-positions">
+        <div class="panel full-height">
+          <div class="panel-header">
+            <div class="panel-title"><span>◫</span> Simulador — Posiciones abiertas</div>
+          </div>
+          <div class="panel-body">
+            <div class="table-wrap">
+              <table id="positions-table">
+                <thead>
+                  <tr>
+                    <th>Mercado</th>
+                    <th>Resultado</th>
+                    <th>Cantidad</th>
+                    <th>Entrada</th>
+                    <th>Actual</th>
+                    <th>G&amp;P</th>
+                    <th>Kelly</th>
+                    <th>Abierta</th>
+                    <th></th>
+                  </tr>
+                </thead>
+                <tbody></tbody>
+              </table>
+            </div>
+            <div class="empty-state hidden" id="positions-empty">No hay posiciones abiertas. Ve al Panel para simular una operación.</div>
+          </div>
+        </div>
+      </section>
+
+      <!-- WATCHLIST VIEW -->
+      <section class="view" id="view-watchlist">
+        <div class="panel full-height">
+          <div class="panel-header">
+            <div class="panel-title"><span>☆</span> Lista de seguimiento</div>
+          </div>
+          <div class="panel-body">
+            <div class="table-wrap">
+              <table id="watchlist-table">
+                <thead>
+                  <tr>
+                    <th>Mercado</th>
+                    <th>Categoría</th>
+                    <th>Sí</th>
+                    <th>No</th>
+                    <th>Señal</th>
+                    <th>Volumen</th>
+                    <th>Umbral de alerta</th>
+                    <th></th>
+                  </tr>
+                </thead>
+                <tbody></tbody>
+              </table>
+            </div>
+            <div class="empty-state hidden" id="watchlist-empty">Tu lista de seguimiento está vacía. Añade mercados desde el Panel.</div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ALERTS VIEW -->
+      <section class="view" id="view-alerts">
+        <div class="panel full-height">
+          <div class="panel-header">
+            <div class="panel-title"><span>⚡</span> Historial de alertas</div>
+          </div>
+          <div class="panel-body">
+            <div class="table-wrap">
+              <table id="alerts-table">
+                <thead>
+                  <tr>
+                    <th>Hora</th>
+                    <th>Mercado</th>
+                    <th>Tipo</th>
+                    <th>Mensaje</th>
+                  </tr>
+                </thead>
+                <tbody></tbody>
+              </table>
+            </div>
+            <div class="empty-state hidden" id="alerts-empty">Aún no se han enviado alertas.</div>
+          </div>
+        </div>
+      </section>
+
+    </main>
+  </div>
+
+  <!-- Telegram Alerts Modal -->
+  <div class="modal-overlay hidden" id="telegram-modal">
+    <div class="modal">
+      <div class="modal-header">
+        <div class="modal-title">
+          <span class="modal-title-icon">✈</span>
+          <span>Alertas Telegram</span>
+        </div>
+        <button class="modal-close" id="telegram-modal-close" title="Cerrar">✕</button>
+      </div>
+      <div class="modal-body">
+        <!-- Instructions -->
+        <div class="telegram-instructions">
+          <div class="instruction-step">
+            <span class="step-num">1</span>
+            <div class="step-body">
+              <strong>Crea tu bot</strong>
+              <p>Abre <a href="https://t.me/BotFather" target="_blank" rel="noopener">@BotFather</a> en Telegram, pulsa <em>/newbot</em> y sigue los pasos. Copia el token que te devuelve (parece <code>123456789:ABC...</code>).</p>
+            </div>
+          </div>
+          <div class="instruction-step">
+            <span class="step-num">2</span>
+            <div class="step-body">
+              <strong>Obtén tu Chat ID</strong>
+              <p>Escríbele a <a href="https://t.me/userinfobot" target="_blank" rel="noopener">@userinfobot</a> y te responderá con tu ID. Si quieres enviarlo a un grupo, añade el bot al grupo y usa <a href="https://t.me/getidsbot" target="_blank" rel="noopener">@getidsbot</a>.</p>
+            </div>
+          </div>
+          <div class="instruction-step">
+            <span class="step-num">3</span>
+            <div class="step-body">
+              <strong>Inicia el bot</strong>
+              <p>En Telegram, abre una conversación con tu bot y pulsa <em>/start</em>. Si usas un grupo, envía <em>/start</em> en el grupo también.</p>
+            </div>
+          </div>
+        </div>
+
+        <form class="modal-form active" id="form-telegram">
+          <div class="form-group">
+            <label for="telegram-bot-token">Token del bot</label>
+            <input type="password" id="telegram-bot-token" placeholder="123456789:ABCdefGHIjklMNOpqrsTUVwxyz" />
+          </div>
+          <div class="form-group">
+            <label for="telegram-chat-id">Chat ID</label>
+            <input type="text" id="telegram-chat-id" placeholder="-1001234567890" />
+          </div>
+          <div class="form-group">
+            <div class="toggle-row">
+              <label for="telegram-enabled">Activar alertas</label>
+              <label class="toggle-switch">
+                <input type="checkbox" id="telegram-enabled" />
+                <span class="toggle-slider"></span>
+              </label>
+            </div>
+          </div>
+          <div class="form-status" id="telegram-status"></div>
+          <div class="form-actions">
+            <button type="button" class="modal-submit modal-submit--secondary" id="btn-test-telegram">Probar conexión</button>
+            <button type="submit" class="modal-submit">Guardar configuración</button>
+          </div>
+        </form>
+      </div>
+    </div>
+  </div>
+
+  <!-- Auth Modal -->
+  <div class="modal-overlay hidden" id="auth-modal">
+    <div class="modal">
+      <div class="modal-header">
+        <div class="modal-tabs">
+          <button class="modal-tab active" data-tab="login">Iniciar sesión</button>
+          <button class="modal-tab" data-tab="register">Registrarse</button>
+        </div>
+        <button class="modal-close" id="modal-close" title="Cerrar">✕</button>
+      </div>
+      <div class="modal-body">
+        <!-- Login Form -->
+        <form class="modal-form active" id="form-login">
+          <div class="form-group">
+            <label for="login-email">Correo electrónico</label>
+            <input type="email" id="login-email" placeholder="usuario@ejemplo.com" required />
+          </div>
+          <div class="form-group">
+            <label for="login-password">Contraseña</label>
+            <input type="password" id="login-password" placeholder="••••••••" required />
+          </div>
+          <div class="form-error" id="login-error"></div>
+          <button type="submit" class="modal-submit">Entrar</button>
+        </form>
+
+        <!-- Register Form -->
+        <form class="modal-form" id="form-register">
+          <div class="form-group">
+            <label for="register-email">Correo electrónico</label>
+            <input type="email" id="register-email" placeholder="usuario@ejemplo.com" required />
+          </div>
+          <div class="form-group">
+            <label for="register-password">Contraseña</label>
+            <input type="password" id="register-password" placeholder="Mínimo 8 caracteres" required minlength="8" />
+          </div>
+          <div class="form-group">
+            <label for="register-password-confirm">Confirmar contraseña</label>
+            <input type="password" id="register-password-confirm" placeholder="Repite la contraseña" required />
+          </div>
+          <div class="form-error" id="register-error"></div>
+          <button type="submit" class="modal-submit">Crear cuenta</button>
+        </form>
+      </div>
+    </div>
+  </div>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

frontend/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "vite": "^7.3.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "chart.js": "^4.5.1",
+    "leaflet": "^1.9.4",
+    "socket.io-client": "^4.8.3"
+  }
+}

frontend/vite.config.js

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:7860',
+        changeOrigin: true,
+      },
+      '/socket.io': {
+        target: 'http://localhost:7860',
+        changeOrigin: true,
+        ws: true,
+      },
+    },
+  },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+  },
+})