ADR 001: Stack HIVE (core + framework + plugins)¶

Estado¶

Aceptado — 2026-06

Contexto¶

Cortex/HIVE es una plataforma modular ensamblada por plugins Python con frontend React declarativo. El monorepo organiza el código en cuatro capas: core/, framework/, plugins/ y products/ (composición de un vertical concreto; ver ADR 025).

Decisión¶

Componente	Tecnología
API	FastAPI (Python 3.12, Pydantic v2)
Datos	PostgreSQL 16 (una BD de plataforma)
Build Python	uv workspace
Frontend	React 18 + Vite (`@cortex/web` + `@cortex/panel-shadcn`, demo `framework/web-shadcn`)
Cache / rate limit	Redis 7

Leyenda: Componentes del stack HIVE (Dependiente). Actores: API, BD, cache, frontend. Estado: Implementado (infra); Redis NFR parcial (ADR 009).

flowchart TB
  subgraph hive [Stack HIVE]
    API[FastAPI /api/v1]
    PG[(PostgreSQL de plataforma)]
    UV[uv workspace]
    React["React 18 + Vite"]
    Redis[(Redis 7)]
  end
  API --> PG
  API --> Redis
  React -->|HTTP| API

Leyenda: Dependencias entre capas del monorepo. Actores: framework ensambla plugins vía SPI en core. Estado: Implementado.

flowchart TB
  core[cortex_core]
  fw[cortex_framework]
  plg[cortex_plugin_*]
  fw --> core
  plg --> core
  fw --> plg

Leyenda: Regla de dependencia: core no importa capas superiores. Estado: Implementado.

Estructura obligatoria:

Carpeta	Rol
`core/`	SPI, tipos, utilidades de grafo genéricas — sin importar framework ni plugins
`framework/`	FastAPI, loader, paneles generativos, registries
`plugins/`	Dominios instalables (`cortex_plugin_*`)
`products/`	Paquetes de composición por producto (`cortex-product-*`)

REST: /api/v1, auth en header Authorization, OpenAPI automático.
MCP: fachada por plugin; REST es fuente de verdad.
Redis 7: caché y rate limiting (valores de producción por configurar).

Consecuencias¶

Plugins activos vía state store PostgreSQL (/control/plugins); tests usan create_test_app(enabled_plugins=...).
core/ no depende de framework ni de plugins.
Frontend en npm workspaces: @cortex/panel-core, @cortex/panel-shadcn y demo framework/web-shadcn.