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

Estado¶

Aceptado — 2026-06

Contexto¶

Cortex/HIVE es una plataforma multi-tenant ensamblada por plugins Python con frontend React declarativo. El monorepo organiza el producto en tres capas obligatorias: core/, framework/ y plugins/.

Decisión¶

Componente	Tecnología
API	FastAPI (Python 3.12, Pydantic v2)
Datos	PostgreSQL 16 (una BD por tenant)
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 por tenant)]
    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: core/, framework/, plugins/.

REST: /api/v1, tenant en header X-Tenant-Id, 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 CORTEX_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.