Contexto del proyecto Cortex (HIVE)¶

Documento de referencia para desarrolladores y agentes: dónde estamos, cómo encaja todo y hacia dónde apunta el monorepo. Actualizar cuando cambie arquitectura o hitos relevantes.

Última revisión: 2026-07 (principio rector panels emergentes; products/ sandbox PMV; casos de uso; MCP/WS beta; auth JWT parcial).

Visión¶

Cortex/HIVE es una plataforma modular ensamblada por plugins Python. ¿No conoces una sigla? Consulta el Glosario.

La experiencia administrativa ofrece panels que emergen de plugins habilitados, UI declarativa y API REST bajo /api/v1:

• Los panels activos los definen los plugins (contributes_panels, entry point opcional cortex.panels), no un catálogo fijo del framework.
• Cada panel tiene path UI, namespace API y módulos CUS (manifests + dashboards JSON).
• Los plugins no aportan páginas React; declaran JSON y REST.
• El framework no conoce plugins de dominio; sí provee mecanismos (control, namespaces generativos, discovery por entry points).
• Capa products/ — extensibilidad esperada / sandbox PMV (caso Reservas); el loader no lee composition.py en runtime.
• Documentación de plataforma en docs/ (cortex-docs); documentación de dominio en docs/plugins/<id>/ (fuente única en el sitio).

Los prototipos históricos validaron la arquitectura multi-panel y UI declarativa; no definen el dominio genérico de los módulos de negocio (ver ADR 008 y catálogo de plugins).

Mapa general del sistema¶

Diagrama de un vistazo: actores, capas Dependiente, plugins Independiente, datos e integraciones. El detalle de cada bloque está en las secciones siguientes y en los ADRs.

Leyenda: Visión holística de Cortex/HIVE. Actores: administrador (panel), apps externas (REST), agentes (MCP/WS). Estado: UI, registries, apirest — implementados; MCP/WS — beta; auth JWT — parcial; oauth2-server completo — diseño; webhooks — diseño.

flowchart TB
  subgraph actores [Actores]
    Admin[Administrador panel]
    Apps[Apps y clientes REST]
    IA[Agentes IA MCP]
  end

  subgraph frontend [Frontend Dependiente]
    Shell["@cortex/web + skins"]
    CUS[Panel CUS widgets]
  end

  subgraph plataforma [Plataforma HIVE Dependiente]
    REST["FastAPI /api/v1"]
    Auth[JWT middleware parcial ADR 005]
    DB[database PG]
    IO[io apirest mcp ws beta]
    UIreg[forms panel registries]
  end

  subgraph nucleo [Nucleo ensamblador]
    SPI[cortex_core SPI hooks]
    FW[cortex_framework loader]
  end

  subgraph plugins [Plugins Independiente]
    Dom[cortex_plugin descubierto por entry points]
  end

  subgraph datos [Infraestructura]
    PG[(PostgreSQL de plataforma)]
    Redis[(Redis cache NFR)]
  end

  subgraph externos [Externos opcionales]
    IdP[IdP OAuth externo]
    WH[Suscriptores webhooks]
  end

  Admin --> Shell
  Shell --> CUS
  CUS -->|HTTP| REST
  Apps --> REST
  IA --> IO
  REST --> Auth
  REST --> DB
  REST --> IO
  REST --> UIreg
  Auth --> IdP
  FW --> SPI
  SPI -->|discovery bootstrap| Dom
  Dom -->|api_router runtime| IO
  DB --> PG
  Dom --> PG
  IO --> Redis
  IO --> WH

Flujo resumido:

1. Bootstrap (arranque): load_plugins descubre plugins → create_plugin + hooks register_* → registries → rutas /panels, /ui, /forms.
2. Runtime: el panel React consume esas rutas; los plugins sirven dominio en /api/v1/{namespace}; auth aplica en cada petición cuando esté activo.
3. Integración: plugins de negocio no se importan entre sí. Se integran por REST (ruta conocida) y/o events/listeners sin conocer al emisor (ADR 021). Bus de datos y puertos quedan para una fase posterior.

Arquitectura Dependiente vs Independiente¶

La pizarra de producto define dónde vive el código, no solo “core vs plugins”.

Guía de clonado y flujo git: Repositorios y submódulos.

Los plugins consumen módulos Dependiente (auth, IO, UI, database); no reimplementan OAuth, panel shell, widgets base ni capa REST/MCP.

Convención de leyendas en diagramas¶

Cada diagrama del repo incluye un bloque Leyenda con:

• Propósito — qué muestra el diagrama.
• Actores — quién inicia cada interacción.
• Estado — Implementado (código en repo) o Diseño (ADR / pendiente).

Módulos Dependiente¶

Paneles generativos: los namespaces (operations, admin) se materializan con ensure_panel() cuando plugins habilitados inyectan módulos. El sandbox helloworld (panel samples) es referencia interna — ver API interna del framework.

Guía operación y CI: Desarrollo y CI.

Namespaces operations y admin (ADR 019)¶

Convención de módulos por namespace (caso Reservas / UnoSportClub): casos-de-uso/reservas/bundles.md. El mecanismo generativo es de plataforma (ADR 019).

flowchart TB
  subgraph namespaces [Namespaces generativos]
    P[operations /operations]
    A[admin /admin]
  end

  subgraph opMods [Modulos operacion]
    BK[booking]
    CL[clients]
    RS[resources]
  end

  subgraph admMods [Modulos parametrizacion]
    SL[sales]
    BL[billing]
    PY[payments]
    PR[pricing]
  end

  subgraph cross [Contribucion transversal]
    W[register_widgets KPI]
    S[register_settings]
    F[reservation-flow widgets]
  end

  P --> opMods
  A --> admMods
  SL --> W
  PY --> W
  BK --> F
  F --> CL
  F --> PY
  F --> PR
  SL --> S
  BL --> S
  PY --> S
  PR --> S
  BK --> S

Leyenda: Convención de separación operación / parametrización. Un plugin puede registrar en varios namespaces (módulos, widgets o settings). Estado: Implementado (paneles generativos operations + admin).

Plugins Independiente (dominio)¶

Ventas ≠ Tienda: dos plugins separados; comparten integraciones (pagos, clientes, tarifas) vía REST, sin código compartido de dominio.

flowchart TB
  subgraph dependiente [Dependiente - modulos framework]
    Auth[oauth2-server ACL JWT]
    Tenant[modular logs config]
    UI[forms components dashboard skins panel]
    IO[io apirest webhooks mcp apirest2mcp]
  end
  subgraph independiente [Independiente - plugins]
    BK[cortex_plugin_booking]
    SL[cortex_plugin_sales POS]
    ST[cortex_plugin_store e-commerce]
    AC[cortex_plugin_accounting]
  end
  Auth --> IO
  UI -->|HTTP PanelApiClient| IO
  IO --> BK
  IO --> SL
  IO --> ST
  IO --> AC

Leyenda: Taxonomía Dependiente vs Independiente. Actores: módulos de plataforma habilitan plugins de negocio; la UI solo habla HTTP con REST. Estado: registries y apirest implementados; auth JWT parcial; oauth2-server y webhooks en diseño.

flowchart LR
  subgraph sales [cortex_plugin_sales]
    CR[cajeros]
    OP[apertura cierre]
    TK[ticket mostrador]
  end
  subgraph store [cortex_plugin_store]
    CAT[catalogo]
    CART[carrito]
    CHK[checkout]
  end
  subgraph shared [integracion REST]
    PAY[cortex_plugin_payments]
    CLI[cortex_plugin_clients]
    PRC[cortex_plugin_pricing]
  end
  sales --> PAY
  store --> PAY
  sales --> CLI
  store --> CLI
  store --> PRC

Leyenda: Ventas (POS) y Tienda (e-commerce) como plugins distintos. Actores: cada dominio llama a otros plugins solo por API. Estado: sales scaffold; store scaffold; integraciones reales pendientes.

Ciclo de vida del plugin¶

Principio: HIVE no conoce las reglas de negocio ni el código React de un plugin. Solo conoce contratos SPI, hooks de registro y rutas HTTP genéricas de plataforma. Al descubrir un plugin, este se coloca en la aplicación: panels, módulos CUS, formularios y API REST — usando herramientas Dependientes (forms, UI/panel, widgets, io.apirest).

El arranque en framework/cortex_framework/plugins/loader.py tiene dos fases:

1. Instancia: create_plugin() → PluginProtocol (api_router, resource_paths) — lógica REST de dominio.
2. Bootstrap: hooks opcionales → el framework inyecta implementaciones concretas de los registradores definidos en core/cortex_core/registrar.py (DIP).

Bootstrap vs runtime¶

Hooks disponibles¶

Catálogo de campos v1 (FormBuilder, emisión en forms/emit.py, renderers shadcn): ver ADR 020.

El plugin compone pantallas con widgets del UI Kit (data-table, form, section, …); no aporta componentes React propios.

Límite del desacoplamiento: HIVE sí conoce los tipos de widget y las rutas HTTP de plataforma; lo desconocido es el dominio de negocio y el JSON concreto de cada módulo.

Leyenda: Ciclo completo discovery → bootstrap → ensamblado HTTP → shell React. Actores: discovery, control embebido, plugins, registries, API, shell. Estado: Implementado.

flowchart TB
  subgraph discovery [Discovery]
    EP[entry_points cortex.plugins]
    Load[load_plugins]
  end
  subgraph control [Control embebido]
    BC[bootstrap_control_panel]
  end
  subgraph plugin [Plugin Independiente]
    CP[create_plugin api_router]
    HR[register_resources]
    HD[register_dashboards legacy]
    JSON[ui manifest dashboards]
  end
  subgraph framework [Framework Dependiente]
    PREG[PanelRegistry ensure_panel]
    RREG[ResourceRegistry DashboardRegistry FormRegistry]
    HTTP["GET /api/v1/panels /ui /forms"]
    IO[io.apirest guards de auth]
    Store[PluginStateStore PG]
  end
  subgraph frontend [Shell React]
    Shell["@cortex/web + panel-shadcn"]
    Widgets[widgets CUS]
  end
  Store --> Load
  EP --> Load
  Load --> BC --> PREG
  Load --> CP
  Load --> HR
  Load --> HD
  JSON --> HD
  HR --> PREG
  HR --> RREG
  HD --> RREG
  CP --> IO
  PREG --> HTTP
  RREG --> HTTP
  HTTP --> Shell --> Widgets
  Widgets -->|fetchPath| IO

Leyenda: Secuencia de invocación de hooks en bootstrap. Actores: loader, módulo del plugin, registries etiquetados, rutas FastAPI. Estado: Implementado.

sequenceDiagram
  participant Loader as loader.py
  participant Host as cortex.panels
  participant Mod as cortex_plugin_*
  participant Reg as TaggedRegistries
  participant API as FastAPI routes

  Loader->>Host: load_panel_hosts configure_panel
  Host->>Reg: PanelRegistry
  Loader->>Mod: import_plugin_module
  Loader->>Mod: create_plugin
  Loader->>Mod: register_resources registry
  Mod->>Reg: manifest dashboards forms
  Reg->>API: assemble GET /panels /ui /forms
  Loader->>Loader: validate_panels

Diseño de ingeniería (ADRs 005–010, 021)¶

Documentación de decisiones acordadas; implementación parcial según ADR (MCP/WS y dominio IO en beta; auth OIDC y webhooks pendientes).

PDF consolidado: ingenieria-hive.pdf — regenerar con docs/build-ingenieria-pdf.sh (autor: Neftali Yagua; incluye arquitectura Dependiente/Independiente y ADRs seleccionados 001–011, 018–019). Diagramas fuente: docs/diagrams/.

Leyenda: ADRs transversales (Dependiente) y de dominio (Independiente) que afectan al ecosistema. Estado: Parcial — ver columna Estado en cada ADR.

flowchart TB
  subgraph transversal [Capas transversales]
    OIDC[ADR 005 OIDC]
    Redis[ADR 009 Redis NFR]
    PG[ADR 007 Persistencia]
    IOM[ADR 010 Modulo IO]
  end
  subgraph dominio [Dominio]
    Booking[plugin booking]
    MCP[ADR 006 MCP tools]
  end
  OIDC --> Booking
  PG --> Booking
  Redis --> Booking
  IOM --> MCP
  MCP --> Booking

Leyenda: Dependencias entre ADRs transversales y dominio booking/MCP. Actores: capas de plataforma habilitan el módulo booking. Estado: Diseño.

Estado actual (hitos completados)¶

Backend¶

• [x] Stack HIVE: FastAPI, PostgreSQL de plataforma, Redis, uv workspace (ADR 001).
• [x] SPI en core/cortex_core + abstracciones registrar (PanelRegistrar, DashboardRegistrar, FormRegistrar) — plugins no importan cortex_framework.
• [x] Multi-panel registry + GET /api/v1/panels, /panels/routes, /panels/{id} (ADR 004).
• [x] CUS: manifests/dashboards JSON, validación ligera en cortex_framework/panel/.
• [x] Panel Control embebido (/control/, toggles de plugins en caliente).
• [x] Plugin accounting como PoC de dominio completo (API + UI).
• [x] Sandbox helloworld (panel samples, To-Do) — API interna del framework.
• [x] Paneles generativos: namespaces operations, admin vía ensure_panel; dedicados (accounting, trainer) con cortex.panels opcional; control embebido en framework.
• [x] Scaffolds de dominio: booking, billing, clients, discounts, events, payments, pricing, sales, store, subscriptions (fixtures + UI; persistencia real — ADR 007/017).
• [x] Capa IO MCP (POST /mcp, hook register_mcp_tools) y WebSocket (WS /api/v1/ws, hook register_ws_namespaces) — ADR 006/010.
• [x] IO de dominio (beta): events, listeners, observers, notifications, broadcasting, middleware — ADR 021.
• [x] Plugin ai-agents: chat WS, widget ask-ai, tools MCP in-process (LangGraph).

Frontend¶

• [x] @cortex/panel-core: headless (types, PanelProvider, nav agrupada, routing, PanelApiClient).
• [x] @cortex/panel-shadcn: skin shadcn/ui + Tailwind v4 (shell, widgets, DashboardRenderer).
• [x] Routing por especificidad: matchModuleScreen / scoreScreenPath — rutas literales (create) antes que :id (ADR 018).
• [x] Jerarquía de títulos: shell → dashboard (hideTitle) → widgets; flags shellOwnsPageTitle y showPanelSubtitle.
• [x] @cortex/web: shell común createPanelShellApp() — rutas, provider, API client.
• [x] Demo: framework/web-shadcn (:5175).
• [x] Fix resolveApiUrl: paths CUS con /api/v1/... no duplican prefijo en fetchPath.

Tooling / CI¶

• [x] npm workspaces en raíz (packages/*, framework/web, framework/web-shadcn).
• [x] Tests Vitest en @cortex/panel-core (nav, routing, API URL).

Arquitectura en capas¶

Leyenda: Stack frontend (demos → shell → skin → core) y backend (API ensambla framework y plugins). Actores: navegador, paquetes npm, FastAPI. Estado: Implementado.

flowchart TB
  subgraph demos [Demo Vite]
    SH[web-shadcn :5175]
  end
  subgraph shell ["@cortex/web"]
    CPS[createPanelShellApp]
  end
  subgraph skin ["@cortex/panel-shadcn"]
    Skin[PanelShell widgets]
  end
  subgraph headless ["@cortex/panel-core"]
    Core["PanelProvider navUtils PanelApiClient"]
  end
  subgraph backend [Backend Python]
    API[FastAPI /api/v1]
    FW[cortex_framework]
    PLG[cortex_plugin_*]
    SPI[cortex_core SPI]
  end
  demos --> CPS --> Skin --> Core
  Core -->|HTTP| API
  FW --> PLG --> SPI
  API --> FW

Acoplamiento entre capas¶

Fuente del diagrama: docs/diagrams/arquitectura-contexto-proyecto-09.mermaid.

Leyenda: Dependencias permitidas vs fugas conocidas del framework. Actores: core, framework, plugins, panel. Estado: Implementado con deuda documentada.

flowchart TB
  subgraph core [core SPI]
    SPI[hooks tipos registries]
  end
  subgraph framework [framework Dependiente]
    FW[cortex_framework loader API]
    IO[io mcp ws events]
    DB[database session]
  end
  subgraph plugins [plugins Independiente]
    PLG[cortex_plugin_*]
    Hooks[register_mcp_tools register_resources]
  end
  subgraph panel [Frontend]
    PC[panel-core]
    PS[panel-shadcn]
  end
  SPI -->|contrato estable| FW
  FW -->|discovery bootstrap| PLG
  PLG -->|api_router hooks| FW
  PLG --> Isolation[sin import entre plugins]
  PC -->|HTTP /api/v1| FW
  PS --> PC
  FW --> Leak[fuga conocida import directo]
  Hooks --> Note1[Correcto extension via hooks SPI]

Flujos clave¶

Arranque de una pantalla del panel¶

1. Usuario navega a p. ej. /operations/booking/home.
2. AppPanelRoutes resolvió rutas desde GET /api/v1/panels/routes.
3. PanelShell carga GET /api/v1/panels/operations → módulos, navGroups, navigation.
4. ModuleScreen carga manifest del módulo → dashboardId de la pantalla.
5. GET /api/v1/ui/dashboards/{dashboardId} → layout + widgets.
6. Widgets llaman API vía api.fetchPath(config.path) — paths CUS son absolutos /api/v1/....

Leyenda: Secuencia de carga de una pantalla del panel. Actores: usuario, rutas React, shell, ModuleScreen, widgets, FastAPI. Estado: Implementado.

sequenceDiagram
  participant U as Usuario
  participant R as AppPanelRoutes
  participant S as PanelShell
  participant M as ModuleScreen
  participant W as Widgets
  participant API as FastAPI

  U->>R: GET /operations/booking/home
  R->>API: GET /api/v1/panels/routes
  S->>API: GET /api/v1/panels/operations
  M->>API: GET /api/v1/panels/operations/modules/booking/manifest
  M->>API: GET /api/v1/ui/dashboards/{dashboardId}
  W->>API: PanelApiClient.fetchPath

Registro de UI en un plugin¶

Leyenda: Cómo un plugin Independiente publica UI declarativa sin React propio. Actores: ResourceBuilder, hook register_resources, registry del framework. Estado: Implementado.

flowchart LR
  RB[ResourceBuilder register_resources]
  JSON["ui/ legacy JSON"]
  Reg[ResourceRegistry PanelRegistry]
  API["GET /api/v1/panels /ui /forms"]
  RB --> Reg --> API
  JSON -->|register_dashboards legacy| Reg

# plugins/foo/cortex_plugin_foo/resources.py
from cortex_framework.ui import ResourceBuilder, register_resource
from cortex_framework.ui.registry import ResourceRegistry

def register_resources(registry: ResourceRegistry) -> None:
    def configure(builder: ResourceBuilder) -> None:
        builder.id("foo").title("Foo").api_base("/api/v1/foo")
    register_resource(registry, "operations", "foo", configure)

Bootstrap de una demo frontend¶

// framework/web-shadcn/src/panel/bootstrap.tsx (patrón)
import { createPanelShellApp } from '@cortex/web';
import { PanelShell, createDefaultRegistry } from '@cortex/panel-shadcn';

export const { AppPanelProvider, AppPanelRoutes, panelApiClient } =
  createPanelShellApp({ PanelShell, createDefaultRegistry, renderLoading, renderError });

Vista C4 — contenedores runtime¶

Complementa el mapa general (diagrama 01: capas lógicas). Aquí se muestran contenedores ejecutables y canales de red.

Fuente del diagrama: docs/diagrams/arquitectura-contexto-proyecto-12.mermaid.

Leyenda: Diagrama C4 nivel contenedores — browser, shell React, API, plugins, datos. Actores: administrador, agentes MCP/WS. Estado: Implementado.

flowchart TB
  subgraph browser [Browser]
    User[Administrador]
  end
  subgraph frontend [Contenedor web]
    WebShell["@cortex/web + panel-shadcn"]
  end
  subgraph apiContainer [Contenedor api]
    FastAPI[cortex_framework FastAPI]
    Plugins[cortex_plugin_* routers]
    IO[io mcp ws events]
  end
  subgraph data [Datos]
    PG[(PostgreSQL)]
    Redis[(Redis)]
  end
  subgraph agents [Agentes externos]
    MCPclient[MCP HTTP client]
  end
  User --> WebShell
  WebShell -->|HTTP /api/v1| FastAPI
  WebShell -->|WS /api/v1/ws| IO
  FastAPI --> Plugins
  FastAPI --> IO
  Plugins --> PG
  FastAPI --> PG
  FastAPI --> Redis
  MCPclient -->|POST /mcp| IO

Mapa de archivos importantes¶

Configuración habitual¶

Ver Configuración. Los nombres CORTEX_* están deprecados (dual-read temporal).

Activación de plugins: /control/plugins (state store PG). No usar CORTEX_ENABLED_PLUGINS ni CORTEX_ENABLED_PANELS.

Widgets CUS¶

Implementados en @cortex/panel-shadcn (tipos preferidos data-table, form; alias api-table, json-form):

Extensión: createDefaultRegistry() + registry.register('tipo', Component).

Pitfalls conocidos¶

1. Doble /api/v1: los dashboards declaran paths completos; el cliente usa resolveApiUrl — no volver a prefijar en widgets.
2. Vite + monorepo: en vite.config.ts de cada demo, optimizeDeps.exclude para @cortex/web, @cortex/panel-core y la skin; dedupe: ['@cortex/panel-core'] — evita dos copias de React context (usePanel must be used within PanelProvider).
3. Plugins scaffold: existen en repo pero no cargan hasta activarlos en /control/plugins.
4. Sin MongoDB: documentación y código activo solo PostgreSQL.
5. Legacy: no editar legacy/ salvo migración puntual.

Verificación antes de merge¶

git submodule update --init --recursive
uv run pytest
uv run ruff check core framework plugins/<tocados>
npm run test:panel-core
npm run build:web-shadcn   # si hay cambios UI

Dirección probable (no comprometida)¶

Orden sugerido para iteraciones futuras:

1. Implementar ADRs 005–009 — OIDC, MCP, PG por plugin, booking genérico, Redis NFR.
2. Pip packaging (ADR 002) — publicar cortex-plugin-* y validar sideload.
3. Endurecer plugins de dominio restantes (clients, payments, …).
4. Widgets CUS v2 — sparklines en stats, polling; contrato JSON estable para chart y stats-overview.

Referencias cruzadas¶

Changelog de este documento¶