| title | Registro de Decisiones Arquitectónicas Locales |
|---|---|
| type | hub |
| classification | Product ADR |
| owner | Evolith Tracker Team |
Bilingual Navigation: English (this document) · Versión en Español
Este documento sirve como el Hub de Decisiones Arquitectónicas Locales para Evolith Tracker. Documenta las decisiones y desviaciones específicas de este producto satélite frente al Core.
Nota: Las decisiones universales se heredan del Upstream Base (evolith_arch32).
- Upstream base:
https://github.com/beyondnetcode/evolith_arch32 - Última clasificación:
2026-06-28 - Convención de IDs de ADR upstream: calificados por categoría —
core/,nodejs/,dotnet/,android/(p. ej.core/0074,nodejs/0075). - ADRs locales (satélite): este repositorio es un satélite gobernado — ver
evolith.yaml. Los ADRs locales conservan su namespaceT-{NNN}(distinto delADR-{NNNN}del Core, per T-011), siguen la plantilla canónica de 6 secciones del Core, llevan el tagEvolithSatelliteen su frontmatter y están registrados enevolith.yaml → spec.compliance.adrRegistry(regla federada CoreINH-04).
| ID | Título | Operación | Ref Upstream | ADR Local | Notas |
|---|---|---|---|---|---|
| T-001 | Orquestación de Monorepo con Nx | Adoptar | ADR-0001 | — | Inicializado en src/ utilizando npm workspaces con Nx. |
| T-002 | Adopción de Microfrontends en Fase 1 | Sobrescribir | N/A | T-002 | Desviación de topología para escalabilidad de UI. |
| T-003 | Arquitectura Hexagonal (Ports & Adapters) | Adoptar | ADR-0002 | — | Capa de dominio pura sin dependencias externas. |
| T-004 | TypeScript estricto como lenguaje primario | Adoptar | ADR-0003 | — | strict: true habilitado. |
| T-005 | TypeORM como ORM (Data Mapper pattern) | Adoptar | ADR-0043 | — | Data Mapper elegido sobre Active Record. |
| T-006 | React con Vite como base del frontend | Adoptar | ADR-0044 | — | Topología microfrontends. |
| T-007 | Zustand + TanStack Query (State Management) | Adoptar | ADR-0045 | — | Zustand (cliente) + TanStack Query (servidor). |
| T-008 | Convención de nombres de schema PostgreSQL | Definir | N/A | T-008 | Canónico: tracker_discovery, tracker_design... |
| T-009 | REST + OpenAPI 3.0 como única API en Fase 1 | Definir | N/A | T-009 | GraphQL fuera de alcance en Fase 1. |
| T-010 | Framework de agentes configurable por tenant | Extender | N/A | T-010 | Core usa BMAD internamente; el Tracker es framework-agnóstico. El tenant configura su harness agéntico por fase (bmad, spec-kit, custom). |
| T-011 | Estándar de numeración para Iniciativas, ADRs y Specs | Definir | N/A | T-011 | IDs de gobernanza/diseño: Iniciativas INIT-{NNN}, ADRs locales T-{NNN}, ADRs upstream ADR-{NNNN}. La descomposición de ejecución queda fuera de alcance. |
| T-012 | Contratos de eventos de dominio en libs/shared/ | Definir | N/A | — | Eventos compartidos (DriftDetectedEvent, ExternalCheckpointRegisteredEvent) se definen como contratos TypeScript en libs/shared/src/domain/events/. Pact tests pendientes (Phase 0). |
| T-013 | Value Object canónico ExternalReference en Shared Kernel | Definir | N/A | — | Unifica shapes dispares en 6 contextos. ExternalReference con system, externalId, url, type, linkedAt, label, metadata. Ubicado en libs/shared/src/domain/external-reference.vo.ts. |
| T-014 | UC-005 dividido en UC-005a y UC-005b | Definir | N/A | — | Plan Release y Authorize Deployment son operaciones distintas con distintos actores y precondiciones. UC-005a (Planning), UC-005b (Execution). |
| T-015 | Core BFF Gateway como único canal de comunicación | Adoptar | core/0074, nodejs/0075, core/0080 | — | El Tracker se comunica exclusivamente con Evolith Core a través del BFF Gateway (NestJS). Se prohíben llamadas directas a servicios internos de Core. Actualizado 2026-06-28 (CR-26): la nota previa "B2B API Gateway (API key)" queda obsoleta — core/0075 (api-key) fue superado por core/0080: Core no autentica; el BFF es el único perímetro (UMS Bearer + grafo de autorización) y las llamadas a Core usan repositoryRef+workspaceRef, sin API key. |
| T-016 | Capa Anti-Corrupción para Integración PPM (Funnel 0) | Definir | N/A | — | Se implementa una ACL (PpmIntakeACL) en el módulo tracker_intake para mapear y normalizar los esquemas de herramientas PPM externas (ej. Meisterplan) antes de que toquen el dominio del Tracker. Esto evita la contaminación de modelos financieros externos en el core del Tracker. |
| T-017 | Core API Exposure Layer (REST-only) | Adoptar | core/0074 | — | (CR-01/CR-02) Core-API es REST-only bajo /api/v1 (sin GraphQL/SSE) + gateway MCP. Salidas con envelope ADR-0073; errores RFC 9457. Reemplaza supuestos de transporte previos. |
| T-018 | Contrato de Referencia de Repositorio Remoto | Adoptar | core/0080 | — | (CR-26) Supera core/0075 (api-key). Core no autentica; el BFF es el único perímetro (UMS Bearer). Llamadas con contenido: repositoryRef {url, revision} + workspaceRef opaco + operationId. |
| T-019 | Separación Dominio/Financiero | Adoptar | core/0078 | — | (CR-17) ROI/finanzas fuera del dominio de gobernanza. Revisar Discovery Canvas / Business Case (hoy embeben ROI). |
| T-020 | Corpus Multi-Topología Componible | Adoptar | core/0079 | — | (CR-08/CR-09) Topología = 5 dimensiones componibles (progressive-axis/execution/integration/data/ai), no un ladder mono→micro. F1/F2/F3 = madurez de progressive-axis (modular-monolith/distributed-modules/microservices), no fases SDLC. |
| T-021 | PhaseId Canónico Semántico | Adoptar | core (GT-343) | — | (CR-28) Ids canónicos discovery|design|construction|qa|release; f1..f5 son alias deprecados solo de entrada; el namespace F# es madurez de topología. |
| T-022 | Contrato de Evaluación de Satélite | Adoptar | core/0073, core/0074 | — | (CR-03) POST /api/v1/evaluate → EvaluationVerdict (OPA real vía SatelliteEvaluationPipeline). El verdict es evidencia técnica, no un GateDecision canónico: el Tracker decide el gate. |
| T-023 | Distribución OPA-wasm Agnóstica | Adoptar | core/0085 | — | (CR-03) Evaluación de reglas vía rulesets/opa/policy.wasm; resultado por regla passed|failed|skipped (skipped si falta el wasm — manejar con gracia). |
| T-024 | Colisión de Nombre GateDecision |
Definir | N/A | T-024 | (CR-12/CR-13) Core ya define un VO GateDecision (estrecho). El GateDecision canónico del Tracker (rico: status/snapshots/approvals/exceptions) se renombra/namespacea (p. ej. TrackerGateDecision) y mapea el VO de Core como entrada de TechnicalEvaluation. |
| T-025 | Gobernanza de IA Agéntica (cluster) | Referenciar | core/0081–0083, 0086–0089 | — | (CR-21/CR-27) Sandbox isolation, trust boundary, action-authorization audit, telemetry/cost, ABAC tool execution, sovereign identity, event-driven workflows. Base para la superficie "AI Governance" del Tracker. |
| T-026 | Redis solo para soporte operacional | Definir | N/A | — | Redis es cache/locks/jobs/idempotency. Todo estado crítico va a PostgreSQL. Redis degrada gracefully cuando no está disponible. No es system of record. |
| T-027 | Circuit breaker en cliente Core API | Definir | N/A | — | Estado machine CLOSED→OPEN→HALF_OPEN. Umbral: 5 fallos. Recuperación: 30s. Previene cascade failures cuando Core no está disponible. |
| T-028 | Estrategia PostgreSQL schema-per-context | Adoptar | T-008 | — | 10 schemas (tracker_discovery, tracker_design, etc.). Sin foreign keys entre schemas. Referencias cross-context solo via UUIDs. |
| T-029 | OpenTelemetry Collector como sink único | Definir | N/A | — | Desacopla la app del backend de observability (Prometheus, Grafana, Loki). Un solo endpoint OTLP. |
| T-030 | K8s overlays via Kustomize (no Helm inicialmente) | Definir | N/A | — | Más simple para Fase 1. Helm chart se considera para Fase 2 si se necesita templating complejo. |
| T-031 | Criterios de evaluación de compuertas configurables por tenant sobre campos de artefactos | Definir | Accepted | T-031 | Base de artefactos autoritativa del Core (requeridos inmutables + opcionales) + overlay del tenant por compuerta: criterios por campo/valor, campos custom, config obligatoria (fail-closed con UNCONFIGURED), 5 estados de resultado (MET/NOT_MET/PENDING/OBSERVED/NOT_APPLICABLE) y traza total por criterio. |
| T-032 | Contexto acotado Geo / Datos Maestros (regionalización, localización, ubigeo) | Definir | Accepted | T-032 | Reemplaza los campos regionales libres (TenantLocalization) por catálogos maestros validados. Contexto geo dentro del Tracker con esquema propio + puerto IMasterDataDirectory + referencia blanda (geoId+snapshot); jerarquía por adyacencia+ltree, maestros globales tenant-agnósticos + overlays por tenant, datos por catalog_release. Extraíble a un servicio compartido evolith_mms (estrangulador) cuando exista un 2º consumidor. |
| T-033 | Adopción de la Plataforma Shell del Core (Ddd/Aop/Factory/Bootstrapper) | Adoptar | Accepted | T-033 | El dominio consume BeyondNetCode.Shell.Ddd (kernel compartido) en vez de un kernel propio; stack Shell completo (aspectos, factory, bootstrapper) espejando UMS. Cierra R-10 / Core ADR-0071. |
| T-034 | Hub de Configuración vs Monitor | Definir | Active | T-034 | La configuración/mantenimiento (CRUD) vive en Tenant configuration; los monitores son solo-lectura + comandos declarados por historias. §2.1 los registros están exentos; §2.2 toda sección de config es colapsable. |
| T-035 | Estándar de info-hints de campo (ayuda en contexto) | Definir | Active | T-035 | Todo término técnico/campo avanzado lleva un ⓘ InfoHint junto al label (significado·impacto·cuándo); info prop en TextField/Select, accesible, copy bilingüe. |
| T-036 | Parametrización de gates dirigida por artefactos del Core | Definir | Active | T-036 | (Extiende T-031) Evidencia y criterios anclados a artefactos definidos por el Core por fase (no texto libre); requerido efectivo = coreRequired OR tenantOverride; sin artefactos Core ⇒ sin criterios; GateMode (SIMPLE/COMPLEX) derivado de la config, no editable. |
Plantilla para nuevos ADRs: Al crear un nuevo documento para "ADR Local", utilice el esquema de Frontmatter definido en los estándares de Evolith Core y ubíquelo en la carpeta de gobernanza correspondiente.