Trasversale · Service · Active

platform-status-service

Operational control plane that probes service health, exposes an aggregate status API and renders the status/operator dashboard.

• NestJS
• React
• Vite
• @platform/observability
• react-router-dom

Spec sheet

Role

Runtime status aggregator and operator console

Backend

NestJS API on port 3400

Frontend

React + Vite on port 5176

Proxy host

http://status.cs.lvh.me:8080

Default targets

auth, ai, connectors, mcp, sfdc backend, funnel backend, cs-portal backend, cs-chat backend, transaction backend

Responsibilities

• Probe configured health endpoints and normalize aggregate status.
• Expose operations routes for runtime, auth, AI and connector administration views.
• Serve the operator dashboard through the local stack proxy.
• Require explicit upstream operation service URLs for Core-service administration calls.

Interfaces and contract surface

• GET /health
• GET /api/status/overview
• GET /api/operations/overview
• GET /api/operations/auth/providers
• GET /api/operations/ai/providers
• POST /api/operations/ai/generations
• GET /api/operations/connectors/sources
• POST /api/operations/connectors/sources/:sourceId/test
• POST /api/operations/connectors/sources/:sourceId/configure

Consumers

• platform-local-stack proxy
• platform-mcp-service status tools
• Operators and developers via browser

Dependencies and external touchpoints

• platform-auth-service
• platform-ai-service
• platform-connectors-service
• platform-mcp-service
• @platform/observability

Notes

• STATUS_TARGETS can override the default local probe list; missing STATUS_TARGETS falls back to local targets.
• OPERATIONS_AUTH_SERVICE_URL, OPERATIONS_AI_SERVICE_URL, OPERATIONS_CONNECTORS_SERVICE_URL and PLATFORM_INTERNAL_TOKEN are required for operations routes.

Source references

• platform-status-service/README.md
• platform-status-service/backend/src/status/default-status-targets.ts
• platform-status-service/backend/src/operations/operations-config.service.ts

Endpoint rapidi

curl -sS http://127.0.0.1:3400/health
curl -sS http://127.0.0.1:3400/api/status-auth/session
curl -sS http://127.0.0.1:3400/api/status/overview
curl -sS http://127.0.0.1:3400/api/status/application-links
curl -sS http://127.0.0.1:3400/api/operations/agent/profiles

Console operations

La pagina /links contiene i Collegamenti rapidi del workspace. I link arrivano solo dal backend status tramite GET /api/status/application-links; nel local stack sono seedati nelle tabelle status_* del registry e possono essere corretti dalla pagina /products.

status-api usa Prisma 7 con DATABASE_URL obbligatorio per leggere le tabelle status_products, status_product_targets e status_application_links. Le tabelle sono gestite da migrazioni forward-only e sono la fonte canonica per prodotti, health target, link applicativi e picklist productCode della sezione Auth. I prodotti noti sono seedati come catalogo iniziale; i target/link locali sono seedati solo quando STATUS_REGISTRY_SEED_RUNTIME_DEFAULTS=true.

La pagina /products e le API GET/PUT /api/status/products/:productCode leggono e registrano prodotti con health target e link applicativi senza modificare codice frontend o payload JSON in env var. STATUS_TARGETS, STATUS_APPLICATION_LINKS e STATUS_APPLICATION_LINK_URLS non sono piu letti dal runtime.

Su Railway produzione, i target e i link salvati nelle tabelle devono puntare ai custom domain core: https://auth.core.codestorm.tools, https://ai.core.codestorm.tools, https://connectors.core.codestorm.tools, https://agent.core.codestorm.tools, https://mcp.core.codestorm.tools, https://payments.core.codestorm.tools, https://scraper.core.codestorm.tools e https://status.core.codestorm.tools/#/runtime. Non usare i public domain generati *.up.railway.app per questi servizi dopo la dismissione dei domini Railway generati.

Su Railway, status-api puo restare privato: status-web serve la console pubblica e inoltra /api/* al backend tramite STATUS_API_PROXY_TARGET=http://${{status-api.RAILWAY_PRIVATE_DOMAIN}}:3400. In questo setup VITE_STATUS_API_BASE_URL deve restare vuoto, cosi il browser chiama solo /api same-origin.

Lo smoke test dello scraper crea crawl asincroni con callback verso POST /api/smoke/scraper/callback. Configura SMOKE_STATUS_CALLBACK_BASE_URL con la base API raggiungibile da platform-scraper-service; nel local stack vale http://127.0.0.1:3400/api, su Railway vale https://status.core.codestorm.tools/api. Il risultato dello smoke espone anche blockType quando il crawl fallisce per una protezione anti-bot nota, per esempio datadome.

Nel deploy GitHub, il workflow imposta DATABASE_URL su status-api usando la reference Railway ${{Postgres.DATABASE_URL}}. Se il servizio database ha un nome diverso, usa il secret RAILWAY_STATUS_API_DATABASE_REFERENCE con la reference corretta.

La sezione Auth della console espone due superfici:

• provider OIDC/locali: /auth
• gestione accessi locali per productCode: /auth/sessions
• capability runtime e grant per ruolo/membership: /auth/capabilities
• catalogo prodotti status: /products

Le sezioni provider operative sono:

• AI provider registry: /ai
• Agent profile registry: /agent-profiles
• Payments provider registry: /payments
• Scraper provider registry: /scraper
• Datasource connector sources: /connectors

Le pagine sessioni, capability e provider passano sempre dal backend platform-status-service, che inoltra verso la surface admin protetta di ciascun servizio CORE. La pagina capability puo sincronizzare il catalogo MCP da platform-mcp-service verso Auth e poi modificare i grant runtime. Il frontend status non chiama direttamente i servizi CORE.

La pagina /agent-profiles gestisce le versioni AgentProfile tramite il backend status. Le API pubblicate dalla BFF sono proxy verso platform-agent-service: GET /api/operations/agent/profiles, GET /api/operations/agent/profiles/:profileKey/latest, GET /api/operations/agent/profiles/:profileKey/versions/:version, PUT /api/operations/agent/profiles/:profileKey e PATCH /api/operations/agent/profiles/:profileKey/versions/:version. Il frontend mostra lista, dettaglio, creazione nuova versione, modifica contenuto e attivazione/disattivazione versione senza chiamare direttamente il servizio agent.

Accesso CS Status

La console status usa una membership dedicata cs-status. Se non esiste ancora una credenziale locale abilitata con role=SUPER_ADMIN, il frontend mostra il wizard /setup. Il wizard crea la credenziale tramite platform-auth-service e apre una sessione condivisa HttpOnly.

Dopo il setup, tutte le API /api/status/*, /api/operations/* e /api/smoke/* richiedono una sessione valida con membership cs-status e ruolo SUPER_ADMIN. Restano pubblici solo /health e le route /api/status-auth/* necessarie a sessione, login, logout e primo setup.