Dashboard Design System + Real-Time SSE Pipeline

2026-03-20

What We Built

Design system foundation and real-time SSE event pipeline for the BrainstormRouter dashboard. The design system introduces semantic typography tokens (--font-data for machine values with tabular numerals), a strict 4-state status color palette (--status-healthy/degraded/critical/inactive), and a modular CSS architecture split from a monolithic 1,688-line stylesheet into tokens, base, layout, and component modules.

The SSE pipeline delivers real-time governance events from the API to the dashboard via Server-Sent Events. A new GET /auth/events endpoint with dual authentication (Bearer token for SDKs, JWT query param for browsers) streams tenant-scoped events with heartbeat, reconnection support via Last-Event-ID, and a 100-event ring buffer per tenant. The dashboard SSE client handles exponential backoff reconnection with polling fallback.

A governance status bar now sits below the header showing kill switch state, budget utilization, alert count, and circuit breaker summary — all updating in real-time via SSE.

Why It Matters

Portkey.ai sets the bar for AI gateway dashboards with real-time log feeds and governance-as-first-class-UI. BrainstormRouter's dashboard was static with polling. This phase establishes the infrastructure for real-time observability across all dashboard surfaces, and the design system ensures every subsequent phase (logs uplift, routing brain, agent live view, cost centers) launches with consistent, precision typography and status semantics.

How It Works

The SSE endpoint hooks into the existing broadcast pipeline via a lightweight tap function. Every broadcast event (usage, budget alerts, errors, quality signals) is mapped to an SSE event type and fan-out to all subscribed clients for that tenant. The SSEBroadcaster singleton manages per-tenant subscriber sets with monotonic event IDs.

The dashboard EventStream class uses fetch() + ReadableStream for SSE parsing (not native EventSource, which can't set auth headers). It reconnects with exponential backoff (1s→30s) and falls back to 10s polling after 3 consecutive failures.

Both TypeScript and Python SDKs expose subscribeEvents() / subscribe_events() as async generators using Bearer token auth.

Competitive Edge

No competitor ships a real-time governance bar with kill switch state, budget utilization, and circuit breaker summary updating via SSE in their dashboard. Portkey has real-time logs but not governance state. This is the foundation for BrainstormRouter's operator-grade dashboard.

Lockstep Checklist

• [x] API: GET /auth/events SSE endpoint with dual auth
• [x] SDK-TS: client.events.subscribe() async generator
• [x] SDK-PY: client.events.subscribe() / client.events.asubscribe() sync+async
• [x] Docs: docs/reference/sse-events.md
• [x] Dashboard: Design tokens, governance bar, SSE client, connection indicator
• [x] Tests: SSE endpoint, event stream client, governance bar
• [ ] MCP: N/A — SSE is observation channel, not agent tool
• [ ] CLI: N/A
• [ ] GTM: N/A