ADRs — Architecture Decision Records

Un ADR (Architecture Decision Record) es una decisión de arquitectura documentada: el contexto que la motivó, las opciones evaluadas, el rumbo elegido y las consecuencias. Los ADRs son la memoria del equipo. Sin ellos, las decisiones que llevaron semanas de debate se vuelven a discutir cada 6 meses porque nadie recuerda por qué se eligió X sobre Y.

bjungle mantiene sus ADRs en website/.../content/docs/conceptos/ porque son públicos — los lee tanto el equipo interno como los clientes técnicos que evalúan si bjungle es la fit correcta para su problema.

Convenciones

• Status: Draft | Proposed | Accepted | Superseded | Deprecated.
• Fecha: cada ADR tiene Accepted: YYYY-MM-DD. Si se modifica, se publica un ADR nuevo que Supersedes al anterior; el viejo queda marcado Superseded pero no se borra.
• Re-evaluar: cada ADR declara las condiciones bajo las cuales amerita revisión. No es expiración — es trigger.

Catálogo actual

Fundacionales

ID	Título	Status	Fecha
—	Visión general del ecosistema	Accepted	2025
—	Wallet SSI — Modelo C híbrido	Accepted	2026-04-22
—	Wallet de identidad — UX	Accepted	2026-04-22
—	Trust policy por flow	Accepted	2026-04-22
—	Data dividends 20/7/5	Accepted	2026-04-22

Autenticación y portabilidad

ID	Título	Status	Fecha
ADR-001	Audiencias de autenticación	Accepted	2026-05-30
ADR-002	Face-MFA y recovery del wallet	Accepted	2026-05-30
ADR-003	Sign-in with bjungle (OIDC)	Accepted	2026-05-30
ADR-004	API keys — scopes + rotation + audit	Accepted	2026-05-30
ADR-005	Multi-operator wallet	Accepted	2026-05-30
ADR-006	Composición de flows + LoA matrix	Accepted	2026-05-30

Stack y operación

ID	Título	Status	Fecha
—	Stack frontend	Accepted	2025
—	Desarrollo local	Accepted	2025
—	Suscripción y pagos	Accepted	2025

Blockchain + bhawk

ID	Título	Status	Fecha
—	Blockchain strategy (anchoring + Açaí)	Implemented-Phase-1	2026-05-31
ADR-007	bhawk como compliance engine — (en repo aparte)	Accepted	2026-05

Cashpaya como primer cliente (Wave A → D, 2026-06)

ID	Título	Status	Fecha
ADR-009	Cashpaya como primer cliente — modelo de integración	Draft	2026-06-05
ADR-010	Mercado Pago Açaí topup público	Draft	2026-06-05
ADR-011	Multi-firma bseal para docs bipartitos	Draft	2026-06-05
ADR-012	SARLAFT continuo parametrizable	Draft	2026-06-05
ADR-013	X.509 cert genérica bjungle + tenant opt-in	Draft	2026-06-05

Estos 5 ADRs son gate antes de implementar las Waves A/A+/B/C/D del backlog cashpaya-integration-backlog.md. Sin ellos en estado Accepted, ningún backend-dev arranca código de Wave A o posterior.

Mapa de dependencias dentro del bloque:

        ADR-009 (frontera DJ ↔ cashpaya)
            │
            ├─── ADR-010 (MP Açaí topup)
            ├─── ADR-012 (SARLAFT continuo)
            │
            └─── ADR-013 (X.509 cert)  ───┐
                                          │
                                          ▼
                                    ADR-011 (multi-firma)

ADR-011 depende de ADR-013 (necesita el modelo de cert para firma corporativa). Los demás son hijos directos de ADR-009.

Mapa de dependencias

                       wallet-modelo-c
                              │
                              ▼
                       ┌──────────────┐
        wallet-identidad │              │ data-dividends
              │          │              │      │
              ▼          ▼              ▼      ▼
            ADR-001 audiencias ◄─────────────┐
              │   │   │   │   │              │
              ▼   ▼   ▼   ▼   ▼              │
         002 003 004 005 006              flow-composition
        face OIDC keys multi LoA                │
                                                │
                              ◄─────────────────┘
                              ▼
                          trust-policy

ADR-001 es el centro: todos los demás de auth/portabilidad lo referencian. ADR-006 (flow composition) es la herramienta concreta para que cada tenant arme su onboarding según su vertical, leyendo el catálogo de ADR-001.

Roadmap (ADRs futuros)

Decisiones que estamos por tomar, en orden de prioridad. (ADRs 009-013 ya escritos arriba en estado Draft; este roadmap es lo que sigue.)

ID propuesto	Tema	Trigger
ADR-014	KYB del tenant (verificación de empresa)	cuando llegue el segundo tenant en producción regulada
ADR-015	Webhook retry + DLQ strategy genérica	cuando crucemos los 10 tenants en prod
ADR-016	Federación con eIDAS / EU Digital Identity Wallet	cuando un cliente Europeo lo pida
ADR-017	Selective disclosure con BBS+ signatures	cuando el caso “edad sin DOB completo” lo amerite a escala
ADR-018	PAdES B-LT embedded en bseal	cuando un juez pida ver “firma dentro del PDF”
ADR-019	UIAF reporting automatizado	post-launch cashpaya, cuando volumen lo justifique

Cada uno se crea como Draft cuando alguien lo propone y se promueve a Accepted después de discusión documentada en el archivo.

Cómo escribir un ADR nuevo

1. Copiar uno reciente como template (e.g. ADR-001 o ADR-006).
2. Frontmatter: title corto, description que explique el problema en una línea.
3. Estructura sugerida:
   • Resumen del problema (1-3 párrafos)
   • Opciones evaluadas (qué se consideró, por qué)
   • Decisión con tabla resumen al final
   • Implicaciones para otros ADRs
   • Anti-patrones que esta decisión previene
4. PR review por al menos 2 miembros del equipo + un Tech Lead.
5. Mergeado → status pasa a Accepted.

ADRs viven, no mueren

Cuando una decisión cambia, NO se borra el ADR. Se publica uno nuevo que Supersedes al anterior, el viejo se marca Superseded y queda visible. Esto preserva el “por qué” histórico — saber que hace 6 meses elegimos Modelo C en lugar de A, y por qué, es información que vale oro cuando alguien pregunta de nuevo.

Status semántico

Draft        Un equipo individual lo escribió, falta revisión.
Proposed     En review, abierto a comentarios.
Accepted     Decisión vigente. Es lo que el código implementa.
Superseded   Reemplazado por otro ADR (link al sucesor en el header).
Deprecated   Sin sucesor pero ya no aplica (e.g. funcionalidad removida).