Arquitectura del HUD

Esta página explica cómo está estructurado el HUD internamente. Léela antes de depurar un panel o agregar uno nuevo.

Flujo de Datos

graph TD
    DB[(raise.db)] --> DM["HUDDataManager\n(data.py)"]
    DM -->|"missions, active_mission,\nmissions_detail"| MP[MissionsPanel]
    DM -->|"active_session, session_state,\nmission, signals, pipeline_runs"| SP[SessionPanel]
    DM -->|pipeline_runs| PP[PipelinePanel]
    DM -->|signals| EP[EventsPanel]
    DM -->|"session_index, skill_events, kpis"| IP[InsightsPanel]
    TIMER["Poll Timers\n(app.py)"] -->|"3s / 5s / 30s"| DM

raise.db es la única fuente de datos. Ningún panel lee la base de datos directamente.

Responsabilidades de Módulos

Módulo	Responsabilidad	NO hace
app.py	Compone el TUI, gestiona los keybindings, programa los timers de polling	Leer la BD directamente
data.py	Única puerta a raise.db — todas las consultas pasan por HUDDataManager	Importar Textual
panels/missions.py	Lista de misiones navegable (izquierda) + panel de detalle (derecha)	Consultar BD
panels/session.py	Estado de sesión activa, barra de progreso de misión, gates HITL	Consultar BD
panels/pipeline.py	DataTable ordenable de pipeline runs con cadena de fases	Consultar BD
panels/events.py	Consola de señales con barra de filtros y línea de estado	Consultar BD
panels/insights.py	KPIs de entrega (velocidad, cycle time, flow efficiency) y salud de tokens	Consultar BD

Ciclo de Polling

Tres intervalos independientes se configuran en app.py:79-81:

Intervalo	Método	Qué refresca	Por qué
3 s	_poll_signals	Nuevas señales de ciclo de vida	Las señales son ráfagas; la pestaña Events necesita actualizaciones casi en tiempo real
5 s	_poll_fast	Sesión activa, misiones, pipeline runs	Frecuente suficiente para sentirse en vivo sin saturar SQLite
30 s	_poll_slow	Índice de sesiones, KPIs, salud de tokens	Agregaciones costosas; los datos de tendencia toleran mayor latencia

action_refresh (tecla r) dispara los tres inmediatamente a demanda.

Contrato de Panel

Cada panel expone un único método update_data(**kwargs). HUDDataManager empuja los datos hacia cada panel; el panel es dueño de toda la lógica de renderizado. Los paneles nunca obtienen datos por sí mismos.

Panel	Args de update_data
MissionsPanel	missions: list[Mission], active_mission: Mission \| None, missions_detail: dict \| None
SessionPanel	active_session: dict \| None, session_state: SessionState \| None, mission: Mission \| None, signals: list[dict], pipeline_runs: list[dict], last_closed_session: dict \| None
PipelinePanel	pipeline_runs: list[dict]
EventsPanel	signals: list[dict]
InsightsPanel	session_index: list[dict], skill_events: list[dict], kpis: dict \| None

Al agregar un nuevo panel, implementa update_data(**kwargs) y registra la llamada en el método _poll_fast o _poll_slow de app.py según los requisitos de refresco de los datos.

¿Qué Sigue?

• Guía de Extensión — paso a paso: panel Hello World → panel data-driven → panel poll-driven (disponible en una versión futura)