Skip to content

Real-Time Auto-Update Architecture (SSE)

Generated artifact. Do not edit manually.

Generated by: scripts/build_compendia.py Regenerate with: python3 scripts/build_compendia.py --compendium dev-handbook --web-and-tex Source of truth: docs/dev/source/

Language / Sprache: English (EN) · Deutsch (DE) | PDF: English PDF · Deutsches PDF

Compendium: §1 Documentation Guidelines · §2 Landscape JSON Reference · §3 Minimal Schema & Fallback · §4 Authoring Editors · §5 Graph Editor · §6 Flashcard Editor · §7 Node Ordering · §8 Liquibase · §9 Auto-Update (SSE)

9. Real-Time Auto-Update Architecture (SSE)

When an external AI coach (via MCP or REST) persists mastery or switches the active goal, the Cockpit WebGUI updates immediately without manual page reloads through Server-Sent Events (SSE) (Client-State Sync).

9.1. Backend Event Bus, SSE Endpoint, and React Reconnection Hook

LearnerService write -> LearnerStateChangedEvent
  -> SseService (SseEmitter map + ~25s heartbeat)
  -> GET /api/ui/updates/{skillpilotId} (text/event-stream)
  -> useLearnerUpdates(skillpilotId) -> refreshMastery() / state reload
  • Spring event publication: State mutations in LearnerService.java publish LearnerStateChangedEvent (MASTERY_UPDATE, GOAL_UPDATE / ACTIVE_GOAL_UPDATE).
  • SSE controller & emitter management: UpdateController exposes GET /api/ui/updates/{skillpilotId} (text/event-stream), backed by SseService maintaining per-learner SseEmitter registrations, automatic cleanup on completion/timeout/IO error, and periodic ~25s heartbeat comments so reverse proxies (Nginx/Cloudflare) keep idle streams open.
  • Frontend hook (useLearnerUpdates): Opens a native browser EventSource, triggers refreshMastery() and active-goal state reloads on incoming events, and reconnects with bounded exponential backoff on network drops.
  • Scaling boundary: In-memory NIO SseEmitter fan-out handles single-node deployments with minimal overhead; horizontal multi-instance deployments require an external pub/sub relay (such as Redis Pub/Sub or PostgreSQL LISTEN/NOTIFY) so events broadcast across all backend replicas.