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