ADR 003: Cortex Panel (CUS + widgets)¶

Estado¶

Aceptado — 2026-06

Contexto¶

HIVE necesita construir apps y paneles admin de forma declarativa, sin una página React por plugin. JSON Forms cubre formularios; tablas, layout, cards y acciones requieren otro contrato.

Formily se descartó: añade complejidad y no sustituye vistas REST ni el shell del panel.

Decisión¶

Introducir Cortex Panel como parte de cortex_framework:

Capa	Responsabilidad
JSON Forms	Create/edit: `GET /api/v1/forms/{id}` → widget `form`
CUS (Cortex UI Schema)	Manifests + dashboards JSON servidos por `/api/v1/ui/...`
Widget registry (React)	`@cortex/panel-core` (headless) + skin `@cortex/panel-shadcn`

Leyenda: Módulo UI Dependiente: plugins Independiente declaran JSON; skins React renderizan. Estado: Implementado.

flowchart TB
  Plugin[cortex_plugin_* resources.py forms.py]
  subgraph contratos [Contratos HTTP]
    Forms["GET /api/v1/forms/{formId}"]
    Manifest["GET /api/v1/panels/{panelId}/modules/{moduleId}/manifest"]
    Dash["GET /api/v1/ui/dashboards/{dashboardId}"]
  end
  subgraph react [Skin shadcn]
    JF[widget form]
    CUS["DashboardRenderer + widgets"]
  end
  Plugin --> Forms --> JF
  Plugin --> Manifest --> CUS
  Plugin --> Dash --> CUS

Leyenda: Flujo manifest/dashboard desde plugin a widgets. Actores: plugin, API UI, skin React. Estado: Implementado.

flowchart LR
  Core["@cortex/panel-core"]
  Skin["@cortex/panel-shadcn"]
  Demo[framework/web-shadcn]
  Core --> Skin --> Demo

Leyenda: Capas npm del frontend Dependiente. Estado: Implementado.

Contratos HTTP (sin cambios de prefijo)¶

GET /api/v1/panels/{panelId}/modules/{moduleId}/manifest — navegación y pantallas
GET /api/v1/ui/dashboards/{dashboardId} — layout + widgets
GET /api/v1/forms/{formId} — JSON Forms (sin duplicar schema en dashboard)

Widgets MVP¶

`type`	Uso
`form`	Formulario JSON Forms + submit REST
`data-table`	Tabla sobre `GET config.path`
`api-card`	Card con resumen de `GET config.path`
`section`	Contenedor con título e hijos

Plugins registran UI vía register_resources() (recomendado) o register_dashboards() legacy (manifest + JSON en ui/). El shell React interpreta CUS; no importan código de plugins.

Consecuencias¶

Rutas dinámicas desde GET /api/v1/panels (shell @cortex/web + demo framework/web-shadcn).
Meta-schemas en cortex_framework/panel/schemas/ para documentación y validación ligera.
Nuevos widgets MVP en @cortex/panel-shadcn; lógica compartida en @cortex/panel-core; extensiones vía registry.register() en el shell.
Documentación de desarrollo: docs/guias/cortex-panel.md.

Referencias¶

ADR 001 (stack HIVE), ADR 002 (pip)
plugins/reference/cortex_plugin_reference/ui/ (panel samples, To-Do)