Decisiones de arquitectura¶
Las decisiones que atraviesan más de un repositorio viven acá, con el prefijo SYS-ADR. Las
que afectan a un solo componente viven en el repositorio de ese componente, y desde acá solo
se enlazan.
Qué entra y qué no¶
| Dónde vive | Prefijo | |
|---|---|---|
| Decisión que cruza dos o más repos, o que fija un contrato entre ellos | este repositorio | SYS-ADR-NNN |
| Decisión interna de un componente | repositorio del componente | CLOUD-ADR, EDGE-ADR, … |
Una ADR es inmutable: no se edita para reflejar un cambio de opinión. Si una decisión deja
de valer, se escribe una nueva que la reemplaza, y la vieja pasa a estado Reemplazada
con un puntero a la que la sustituye.
Decisiones de sistema¶
| ID | Decisión | Estado |
|---|---|---|
SYS-ADR-001 |
Arquitectura en cuatro piezas, con InfluxDB como desacople dentro de la Pi | Aceptada |
SYS-ADR-002 |
Ingesta por HTTP en lotes, con idempotencia y clave de API por dispositivo | Aceptada |
SYS-ADR-003 |
Mediciones en MongoDB; identidad y configuración en Postgres | Aceptada |
SYS-ADR-004 |
aasPath como identificador semántico común |
Aceptada, con un defecto conocido |
SYS-ADR-005 |
Chequeos del Cloud hacia el Edge sin autenticación | Aceptada, riesgo asumido |
SYS-ADR-006 |
Plataformas de despliegue: Vercel, Cloud Run y la Raspberry Pi | Aceptada |
SYS-ADR-007 |
Sistema de monitoreo, no de control | Aceptada |
SYS-ADR-008 |
Servidor AAS resuelto con FA³ST en la Pi | Aceptada |
SYS-ADR-009 |
Forma canónica del aasPath cuando la colección está vacía |
Aceptada y aplicada; falta el paso 3 |
Reemplazos¶
Dos decisiones de componente quedan reemplazadas por decisiones de sistema. Las originales
quedan en su repositorio, en estado Reemplazada.
| Reemplazada | Por | Motivo |
|---|---|---|
CLOUD-ADR-003 — eventos en Postgres con JSONB y particionado |
SYS-ADR-003 |
Nunca se implementó así: las mediciones están en MongoDB |
CLOUD-ADR-004 — idempotencia por eventId único global |
SYS-ADR-002 |
La unicidad global rompía el aislamiento entre tenants |
Y una queda matizada sin ser reemplazada: CLOUD-ADR-002 afirma que el tenant_id sale
exclusivamente del claim del JWT y que el header X-Tenant-ID se ignora. La implementación
actual hace lo contrario —lee el header y valida la membresía del lado del servidor— y
CLOUD-ADR-015 documenta esa evolución. Quien lea CLOUD-ADR-002 aislada va a sacar una
conclusión equivocada sobre cómo funciona el sistema hoy.
Decisiones de componente¶
Viven en sus repositorios y no se copian acá.
| Componente | Dónde | Cuántas |
|---|---|---|
| Frontend | docs/adr/ en main |
15 FE-ADR-001 a 015, una por archivo, sin colisiones. La 015 reemplaza a la 010 |
| Cloud | docs/adr/ en main |
11 CLOUD-ADR-001–005 y 014–019, una por archivo. Los huecos 006–013 quedan a propósito |
| Edge | docs/adr/ en main |
12 EDGE-ADR-001 a 012, una por archivo. La 012 es la que aplica SYS-ADR-009 |
| historian | — | ninguna: las decisiones están en el README y en la tesis. Es el único de los cuatro sin ADR |
Decisiones de sistema que viven en una ADR de componente¶
Tres decisiones que afectan al sistema entero quedaron registradas en el repositorio del frontend o del Cloud. Conviene leerlas desde acá.
| Tema | Resuelto en | Qué se decidió |
|---|---|---|
| Verificación de los 13 contratos Pact | FE-ADR-013 |
Se eliminan, no se verifican: ningún test los generaba, nadie los verificaba, y eran dos familias incompatibles entre sí |
| Motor de reglas de alarma | FE-ADR-014 |
El módulo no se expone en el MVP: ALERTS_MODULE_ENABLED=false, el ítem del menú queda deshabilitado con badge «Pendiente» y la campana de notificaciones se oculta. El código no se borra. El objetivo específico 5 del anteproyecto queda como no cumplido, no como pendiente |
| AAS fuera del Cloud | CLOUD-ADR-019 |
Registra del lado del Cloud lo que SYS-ADR-008 ya decía |
SYS-ADR-009 fija la forma canónica del aasPath —colapsar el segmento de
colección vacío—, y el Edge y el frontend la respetan. Falta dejar bloqueante el control del
frontend: ver estado de aplicación.
Decisiones que todavía no tienen ADR¶
Registradas acá para que no se pierdan. Cada una espera una decisión, no una redacción:
| Tema | Por qué falta |
|---|---|
| Respaldos y recuperación | No hay evidencia de que existan respaldos propios. Primero la decisión |
| Retención de datos, en InfluxDB y en MongoDB | Ninguna de las dos tiene política configurada |
| Recolección de métricas Prometheus | Dos componentes las exponen y no se sabe si alguien las consume |
| Fallo abierto del límite de tasa | Es una decisión de seguridad —disponibilidad sobre limitación— implementada y nunca decidida por escrito. Ver seguridad |
| Dueño y versionado del catálogo de variables | Vive en el repositorio de un autor externo, con un solo tag de abril. Bloquea el validador de aasPath |
Formato¶
Cada SYS-ADR sigue una variante reducida de MADR: encabezado con estado, fecha y relaciones;
después contexto, decisión, alternativas consideradas, consecuencias y evidencia.
La sección de evidencia es obligatoria: cada afirmación tiene que poder rastrearse hasta un archivo de un repositorio, fijado por commit.