Navegación Bilingüe: English · Español (este documento)
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).
| 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 para projects discretos |
| T-002 | Adopción de Microfrontends en Fase 1 | Sobrescribir | N/A | T-002 | Desviación de la topología base de Fase 1 para permitir escalabilidad concurrente de UI |
| T-003 | Arquitectura Hexagonal (Ports & Adapters) | Adoptar | ADR-0002 (Core Node.js) | — | Capa de dominio sin imports de NestJS, ORM ni SDKs externos |
| T-004 | TypeScript estricto como lenguaje primario | Adoptar | ADR-0003 | — | strict: true habilitado; imports sin usar prohibidos |
| T-005 | TypeORM como ORM (Data Mapper pattern) | Adoptar | ADR-0043 | — | Data Mapper elegido sobre Active Record; no se usa Prisma |
| T-006 | React con Vite como base del frontend | Adoptar | ADR-0044 | — | React + Vite como tecnología base; topología de microfrontends por T-002/T-002 |
| T-007 | Zustand + TanStack Query para state management | Adoptar | ADR-0045 | — | Zustand para estado de cliente; TanStack Query para estado de servidor |
| T-008 | Convención de nombres de schema PostgreSQL tracker_<context> |
Definir | N/A | — | Canónico: tracker_discovery, tracker_design, tracker_construction, tracker_qa, tracker_release, tracker_governance, tracker_artifacts, tracker_metrics, tracker_integration, tracker_audit. Resuelve conflicto C4/TAD (FINDING-002). |
| T-009 | REST + OpenAPI 3.0 como única superficie API en Fase 1 | Definir | N/A | — | GraphQL queda fuera de alcance en Fase 1 (FINDING-003). Su adopción en Fase 2 requerirá ADR formal y gobernanza híbrida (R-18). |
| T-010 | Framework de agentes configurable por tenant | Extender | N/A | T-010 | BMAD es orquestación; el tenant elige el framework de agentes (bmad, spec-kit, custom) por fase. |
| T-011 | Estándar de numeración para épicas e historias | Extender | N/A | T-011 | Extiende upstream US-\d{3} a US-{MOD}-{NNN} con códigos de módulo de 3 letras. Épicas: EPIC-{NNN}. |
| 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 Core BFF Gateway (Tier 1 Kong Edge → Tier 2 NestJS BFF). Se prohíben llamadas directas a servicios internos de Core. El BFF valida UMS/RBAC en el perímetro de usuario y usa autenticación B2B API key para el canal máquina-a-máquina hacia Core; core/0080 complementa el payload con repositoryRef + workspaceRef + operationId, pero no reemplaza el canal B2B. |
| 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) Las llamadas BFF → Core incluyen repositoryRef {url, revision} + workspaceRef opaco + operationId para evaluación stateless y correlación. Este contrato no autoriza usuarios finales ni persiste ownership; la autorización tenant/usuario queda en el Tracker BFF. |
| 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, 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). |
| 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) 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 | Navegación Multi-Perspectiva SDLC (8 perspectivas) | Definir | N/A | propuesta | Reemplaza navegación lineal por modelo de 8 perspectivas canónicas (Tenant, Producto, Iniciativa, Grupo, Fase, Cumplimiento, Impactos, Arquitectura). Incluye perspectivas de drift y monitoreo arquitectónico. |
| T-027 | Architecture Drift Monitor como capacidad de producto | Extender | core/0073, core/0080 | — | Tracker adopta el contrato de evaluación de Core (POST /api/v1/evaluate) para evaluaciones de tipo architecture_drift. Tracker opera el lifecycle del drift (detección → registro → visualización → remediación → excepción → auditoría). Core se mantiene stateless. Agent Runtime orquesta adaptadores de detección. Se crean entidades: ArchitectureDriftFinding, ArchitectureBaseline, DriftRemediationTask, DriftException, DriftApproval. Ver PRODUCT_VISION.es.md §10.3. |
| T-028 | CoreEvaluationTransaction como entidad de primera clase | Definir | N/A | — | Todo intercambio Tracker ↔ Core se modela como CoreEvaluationTransaction (request + response + contexto + metadata). Core no persiste nada — Tracker es el único responsable de la persistencia operacional. La transacción se implementa como agregado en tracker_integration con 30+ campos. Ver tracker-core-integration-design.es.md §N. |
| T-029 | ADR contextual en Tracker vs ADR general de Core | Definir | N/A | — | Dos niveles de ADR: (1) ADR contextual en Tracker — decisión operacional por tenant/producto/iniciativa, persiste en Tracker como evidencia. (2) ADR general de Core — modifica el estándar de Evolith Core, debe proponerse mediante flujo formal (issue → ADR → branch → PR → review → merge). Tracker no modifica el Core directamente; solo propone, registra y da seguimiento. |
| T-030 | Core Standard Change Request — flujo de evolución del Core | Definir | N/A | — | Las propuestas de cambio al estándar general del Core siguen un lifecycle formal: TechnicalDecision → CoreImprovementProposal → RepositoryIssue → DraftADR → Branch → PR → Review → Approval → Merge → CoreVersionUpdate → TrackerTrace. |