Índice de ADRs — IngelCoding

Registro de decisiones arquitectónicas del proyecto IngelCoding. Para el contexto del framework de ADRs ver ADR-Pipeline-V2-Framework#Fundamento teórico.

¿Qué es un ADR?

Un Architectural Decision Record es un documento corto que captura una decisión arquitectónica con su contexto, alternativas evaluadas, opción elegida y consecuencias. Es la trazabilidad del “por qué” del sistema: cuando alguien (tú dentro de 6 meses o un colaborador nuevo) se pregunte “¿por qué este proyecto hace X así?”, la respuesta vive aquí.

Convenciones

• Nombre: descriptivo, sin numeración. ADR-<Tema>.md. Ejemplo: ADR-Source-Connectors.md.
• Ubicación: 01-Arquitectura/ADR/.
• Frontmatter obligatorio: tags, created, type: decision, status, produced_by, engram_id.
• Estados: proposed → accepted → (eventualmente) superseded o deprecated.
• Cada ADR aceptado/propuesto se guarda en Engram con topic_key: ingelcoding/adr/<slug> y el engram_id va en el frontmatter.

Estructura recomendada del cuerpo

1. Estado (Propuesta / Aceptada / Reemplazada por X / Obsoleta)
2. Contexto — problema y situación que motiva la decisión
3. Opciones evaluadas — alternativas reales con pros/contras
4. Decisión — qué se elige
5. Fundamento (opcional) — teoría o referencias que respaldan
6. Consecuencias — positivas / negativas / neutras
7. Ver también — links a docs relacionados

ADRs vigentes

ADR	Tema	Estado	Engram	Creado	Resumen
ADR-Zonal-Gestora-Derivada	Zonal Gestora derivada vs física	Aceptada	#1220	2026-05-14	Computar Zonal_Gestora en pipeline desde Control de OTs en vez de mantenerla manual en GSheets. Single source of truth
ADR-Pipeline-V2-Framework	Framework BasePipeline + DAG 6-stage	Aceptada (retroactiva)	#1227	2026-05-18	Adopción formal del framework V2: 6 etapas opcionales, PipelineConfig inmutable, YAML spec externo, short-circuits estándar
ADR-Integracion-Alertas-Waypoint-DW	Integrar alertas_waypoint al Data Warehouse	Aceptada	#1318 + #1326 (SDD archive)	2026-06-01	Pipeline (antes solo Excel) llevado al DW: constelación fact_alertas_waypoint + dim_vehiculo en data_warehouse.db (grano evento-vehículo, sin OT, reusa dim_calendario, geo lat/long 100%) → Supabase → Power BI. Implementado vía SDD alertas-waypoint-al-dw (36 tests, 12/12 COMPLIANT, 9/9 modularización). Documenta el flujo real pipeline→DW
ADR-Data-Warehouse-Epilogue	DW build + migración Supabase como epílogo del orquestador	Aceptada	#1354 + #1352 (SDD archive)	2026-06-03	run_pipeline.py --migrate (solo —all, gate todos-OK, exit≠0 si falla) construye el DW y migra seguro (drop opt-in); dim_ot rescatado. Implementado vía SDD migracion-segura-orquestador (PR #59)
ADR-Source-Connectors	Hexagonal architecture para fuentes de datos	Aceptada	#1228 + #1238 (F1) + #1248 (F2) + #1256 (F2.1) + #1265 (F2.2) + #1273 (F2.3) + #1281 (F2.4+F2.5) + #1289 (F2.6) + #1297 (F2.7)	2026-05-18 (decisión) / 2026-05-27 (aceptada)	ARCO COMPLETO: 6/6 pipelines IMAP en patrón Hexagonal directo + shim/core.ingest_imap eliminados (F2.7). R1-R7 todos ejercitados por consumidores reales (R4 multi-zonal validado por gantt). Capabilities: source-connectors + imap-connector (7 Reqs — R7 backward-compat REMOVED en F2.7). Ver Plan-Migracion-F2.2-F2.6
ADR-Costos-Metas-a-DW	Migración de METAS MES (costos) a Data Warehouse	Propuesta	—	2026-06-07	Eliminar artefactos manuales METAS MES/MES0 de la planilla. Crear fact_costos_hh = volcado directo de costo_por_hh; METAS MES → SELECT sobre DW. Rename hb_dia_esperado→hb_dia_total, hb_dia_esperado_sv→hb_dia_prod. 5 gaps de implementación pendientes.
ADR-Portal-Multi-Framework	Portal multi-framework Angular+Svelte por URL	Aceptada	—	2026-06-16	apps/portal-docs (Angular 21) = documentación/wiki; apps/portal-datos (Svelte 5 + Vite) = datos de negocio. Conviven bajo el mismo dominio por path/subdominio con links HTML normales y tokens visuales compartidos. La era agéntica elimina el costo cognitivo histórico del multi-stack.

Capabilities asociadas (openspec/specs/)

Algunas ADRs se materializan en una capability con su propio spec en openspec/specs/<capability>/spec.md. Mapa actual:

Capability	ADR que la respalda	Archives Engram
source-connectors	ADR-Source-Connectors	F1 #1238
imap-connector	ADR-Source-Connectors	F2 #1248 + F2.1 #1256 + F2.2 #1265 + F2.3 #1273 + F2.4+F2.5 #1281 + F2.6 #1289 + F2.7 (REMOVE R7, 8→7 Reqs) #1297

ADRs pendientes (apuntados desde ADRs existentes)

ADR pendiente	Razón	Origen
ADR-Orquestador-Composicion	Decisión sobre meta-orquestador (run_pipeline.py + epilogue) vs monolito	Discusión 2026-05-18
ADR-Maturity-Levels ⚡ prioritario	Definir 5 niveles L1-L5 de madurez del pipeline (qué metadata exige cada nivel)	Discusión 2026-05-18
ADR-Data-Contracts	Schema hash + freshness SLA por dataset	ADR-Source-Connectors §Ver también
ADR-Sink-Connectors	Patrón Hexagonal para publishers (Drive, GSheets, SQLite analítica) — cara opuesta de Source-Connectors	ADR-Source-Connectors §Ver también
ADR-Connector-Statefulness ⚡ prioritario	Cuándo se permiten connectors con estado (cache, pool, rate-limiter), qué garantías de concurrencia exigir, qué primitivas usar (threading.Lock, asyncio, queue). Relevante de inmediato para un futuro GSheetsConnector (F5) con rate-limit	Spec source-connectors-f1 §Non-Functional Requirements
ADR-Ingeldata-vs-Datawarehouse	Por qué hay dos BDs separadas (operacional vs analítica)	Auditoría DB 2026-05-18

Cómo crear un ADR nuevo

1. Nombre: ADR-<Tema-Descriptivo>.md en 01-Arquitectura/ADR/
2. Copiar frontmatter de un ADR existente (mantener type: decision)
3. Estado inicial: status: proposed
4. Cuerpo: seguir la estructura recomendada arriba
5. Guardar en Engram: mem_save(topic_key="ingelcoding/adr/<slug>", type="decision"|"architecture") y agregar engram_id al frontmatter
6. Actualizar este índice: agregar fila en la tabla de ADRs vigentes
7. Cambiar estado a accepted cuando se acepta (puede ser inmediato si es retroactiva)

Cómo se relacionan los ADRs con otros docs

Reference-BasePipeline.md     ← contrato técnico (single source)
       ↑
       │ enlaza
       │
ADR-Pipeline-V2-Framework     ← por qué se eligió
ADR-Source-Connectors         ← por qué Hexagonal
       ↑
       │ enlaza
       │
Como-Crear-Pipeline-Nuevo     ← cómo hacerlo (operativo)

Cada doc cumple un rol distinto (Diataxis):

• Reference = qué es el contrato exacto
• ADR = por qué se decidió así (con alternativas evaluadas)
• How-to = cómo aplicarlo en el día a día