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

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:

ID propuesto	Tema	Trigger
ADR-007	OIDC corporate para staff bjungle	cuando contratamos el segundo empleado
ADR-008	KYB del tenant (verificación de empresa)	antes del primer tenant en producción regulada
ADR-009	Billing modelo (Stripe vs MercadoPago vs ambos)	cuando salgamos del pricing fijo
ADR-010	Webhook retry + DLQ strategy	cuando crucemos los 10 tenants en prod
ADR-011	Federación con eIDAS / EU Digital Identity Wallet	cuando un cliente Europeo lo pida
ADR-012	Selective disclosure con BBS+ signatures	cuando el caso “edad sin DOB completo” lo amerite a escala

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).