DashDescomplicar/okf/entidades/Express-API.md

type, layer, tags, title

type	layer	tags	title
Entity	wiki	stack dashdescomplicar backend express api core	Express-API

Express-API

Servidor backend Express 4 que expõe a REST API do DashDescomplicar. Orquestra 15 rotas, middleware de segurança e serve o frontend estático em produção.

Responsabilidades

• Roteamento: 15 rotas REST (/api/dashboard, /api/monitor, /api/hetzner, /api/wp-monitor, /api/server-metrics, /api/financial, /api/mcps, /api/n8n, /api/paperclip, /api/operations, /api/ai, /api/beszel, /api/sessions, /api/diagnostic, /api/health)
• Segurança: Rate limiting (100 req/15min produção, 1000/15min dev), CORS restrito, validação Zod em todas as rotas, OIDC opcional
• Error Handling: UUIDs para tracking de erros, sem stack traces em produção, logs estruturados
• Static Serving: Serve o bundle Vite (React SPA) em produção na porta 3001
• Health Check: Endpoint /health (público) e /api/health (autenticado)

Stack

• Runtime: Node.js 22+ (Alpine no Docker)
• Framework: Express 4.19+ com TypeScript 5.9
• Validação: Zod 4.3 (z.object(), .passthrough(), z.coerce)
• Rate Limit: express-rate-limit 8.2
• CORS: cors 2.8
• Auth: express-openid-connect (opcional, via OIDC_ENABLED)
• DB Drivers: mysql2 3.11 (promise), ssh2 1.17, better-sqlite3 12.9
• Observabilidade: SQLite local (~/.claude-work/sessions.db) para sessões Claude Code

Localizações

• Código: Dev/DashDescomplicar/api/server.ts (238 linhas)
• Rotas: api/routes/ (14 ficheiros)
• Serviços: api/services/ (16 ficheiros)
• Middleware: api/middleware/validation.ts
• DB Pool: api/db.ts
• Deploy: dash.descomplicar.pt:3001 (EasyPanel Swarm)
• Dev: http://localhost:3001 (tsx watch)

Rotas Expostas

Rota	Ficheiro	Fonte Dados
GET /api/dashboard	routes/dashboard.ts	Desk CRM MySQL (16 queries paralelas)
GET /api/monitor	routes/monitor.ts	tbl_eal_monitoring (MySQL)
GET /api/diagnostic	routes/diagnostic.ts	Testes de conectividade (17 checks)
GET/POST /api/hetzner	routes/hetzner.ts	Hetzner Cloud API + MySQL
GET/POST /api/wp-monitor	routes/wp-monitor.ts	Plugin WP → MySQL (API key auth)
POST /api/server-metrics	routes/server-metrics.ts	SSH2 (EasyPanel) + MySQL
GET /api/financial	routes/financial.ts	Desk CRM MySQL (7 queries)
GET /api/mcps	routes/mcps.ts	MCP Gateway (HTTP ping, cache 60s)
GET /api/n8n	routes/n8n.ts	n8n REST API (cache 300s)
GET /api/paperclip	routes/paperclip.ts	PostgreSQL Paperclip (com fallback)
GET /api/operations	routes/operations.ts	Desk CRM MySQL (4 queries)
GET /api/ai	routes/ai.ts	Dados estáticos (snapshot STK)
GET /api/beszel	routes/beszel.ts	Beszel PocketBase API + MySQL
GET /api/sessions	routes/sessions.ts	SQLite local (better-sqlite3)

Dependências

• MySQL-Pool: Conexão ao Desk CRM (176.9.3.158)
• Variáveis de Ambiente: DB_*, HETZNER_TOKEN, WP_MONITOR_API_KEY, N8N_API_KEY, BESZEL_*, EASY_*, MCP_GATEWAY_*, OIDC_*, OBSERVABILIDADE_DB
• Docker-Deploy: Empacotado via Dockerfile → EasyPanel Swarm
• Observabilidade-Sessions: Abre ligação SQLite para sessões Claude Code

Consome de

• Desk CRM (MySQL — 176.9.3.158:3306)
• Hetzner Cloud API (api.hetzner.cloud/v1)
• MCP Gateway (gateway.descomplicar.pt)
• n8n API (automator.descomplicar.pt/api/v1)
• Paperclip PostgreSQL (container Docker)
• Beszel PocketBase API
• EasyPanel Server (SSH2 porta 22)
• Sistema de ficheiros local (SQLite sessions.db)

Fornece a

• Todos os 8 painéis frontend (via fetch à API)
• Dashboard-Engine (dados agregados para App.tsx)
• Sistema de diagnóstico (/api/diagnostic)