Saltar a contenido

ADR 011: Panel namespaces y composición

Estado

Aceptado — 2026-07 (reescrito)

Contexto

Cortex expone varias experiencias UI (/operations/, /admin/, /accounting/, /control/) sobre un mismo backend pluginizado. Los plugins de dominio deben poder contribuir módulos, widgets y settings sin acoplarse a un paquete host monolítico ni a variables de entorno de activación.

Decisión

  1. panel_id es un namespace de composición — identifica dónde se ensamblan módulos, dashboards, layouts y settings.
  2. Panel de plataforma control — embebido en cortex_framework.control, siempre activo, scope sudo, no toggleable en /control/plugins.
  3. Paneles de dominio generativos — operations, admin, samples y similares se materializan con ensure_panel() cuando plugins habilitados inyectan contenido; desaparecen del catálogo visible cuando no hay contribuciones. El sandbox helloworld (panel samples) es referencia interna del framework, no dominio de producto.
  4. Orden de bootstrap en load_plugins():
  5. bootstrap_control_panel()
  6. plugins de dominio habilitados (hooks register_*; ensure_panel() al registrar módulos)
  7. load_panel_hosts() para paneles dedicados con configure_panel (accounting, trainer, …) y metadata opcional vía cortex.panels
  8. register_resources / register_forms del entry point cortex.panels cuando aplica
  9. merge_panel_infrastructure() por panel activo
  10. Activación en caliente — activate_pending_plugins() repite register_resources / register_forms para paneles pendientes (mismo contrato que boot).
  11. Entry point cortex.panels — opcional para metadata y shell adicional; no define qué paneles existen en runtime. El panel_id lo declara el plugin (contributes_panels o configure_panel), no el framework.
  12. Frontera dominio vs mecanismo — el framework no conoce plugins de negocio ni lista fija de panels de producto. Conoce control, contratos de namespaces generativos y discovery por entry points. La asignación módulo → panel_id es responsabilidad de cada plugin (contributes_panels) y del caso de uso ensamblado (ADR 025).
  13. Activación — state store /control/plugins + builtins (template); sin CORTEX_ENABLED_PLUGINS ni CORTEX_ENABLED_PANELS.
  14. GET /api/v1/panels/{id} incluye configuration (brand, theme, defaultRoute) para el shell React.
flowchart TB
  Boot[bootstrap_control]
  Domain[plugins dominio habilitados]
  Ensure[ensure_panel por namespace]
  Merge[merge_panel_infrastructure]
  Assemble[assemble_all_panels]
  Boot --> Domain --> Ensure --> Merge --> Assemble

Glosario

Término Significado
panel_id Namespace de composición UI+API
Panel de plataforma Solo control (framework)
Panel de dominio Namespace que emerge por inyección de plugins
cortex.panels Metadata/shell opcional

Consecuencias

  • plugins/shells eliminado; composición por namespace.
  • cortex-plugin-panel / cortex-plugin-admin son paquetes de metadata y extensiones, no requisito pip para activar operations/admin.
  • Frontend (PanelShell) lee configuration de la API.
  • Activar un panel en caliente sin reinicio debe registrar todos los módulos UI del plugin (home + register_resources); ver ADR 023.

Referencias