Software Architecture
Explica cómo registrar decisiones arquitectónicas con contexto, drivers, alternativas, consecuencias, estado y señales de revisión mediante ADRs.
Una decisión arquitectónica no queda explicada por el código final. Para poder revisarla cuando cambien los drivers, debe conservar el problema, las alternativas consideradas, las consecuencias aceptadas y la evidencia que justificó elegirla.
Una arquitectura evoluciona mediante decisiones. Algunas son reversibles y locales; otras condicionan datos, equipos, contratos y operación durante años.
Un Architecture Decision Record —ADR— es un registro breve pero suficiente de una decisión importante. Su propósito no es producir burocracia, sino evitar que el equipo pierda el razonamiento y repita discusiones sin contexto.
contexto
→ fuerzas y restricciones
→ alternativas
→ decisión
→ consecuencias
→ evidencia y señales de revisiónEl código muestra qué se implementó, pero rara vez explica:
Sin esa información, una persona puede “corregir” una decisión antigua y reintroducir el riesgo que intentaba evitar. También puede conservarla por inercia cuando sus condiciones ya cambiaron.
Registra decisiones con impacto amplio, alto costo de reversión o riesgo significativo:
No necesitas un ADR para cada nombre de función o librería menor. El registro debe concentrarse en decisiones que otra persona razonablemente necesitaría comprender o cuestionar.
Expresa la decisión, no solo el tema:
Usar un monolito modular como topología inicialPropuesta, aceptada, rechazada, reemplazada o deprecada. El estado permite distinguir una idea de una decisión vigente.
Describe el problema y las fuerzas reales: equipo pequeño, dominio cambiante, transacciones locales y baja capacidad operativa distribuida.
Indica qué se hará y el alcance. Evita frases ambiguas como “usar buenas prácticas”.
Incluye opciones razonables y por qué no fueron elegidas. No inventes alternativas absurdas para hacer parecer obvia la decisión.
Explica beneficios, costos, riesgos, trabajo adicional y efectos sobre otras partes.
Registra prototipos, métricas o experiencia que respaldan la decisión y qué hechos justificarían revisarla.
# ADR-007: Usar monolito modular como topología inicial
## Estado
Aceptada
## Contexto
DomiSys es desarrollado por un equipo pequeño. El dominio todavía cambia y los flujos de inventario y pedidos necesitan transacciones locales. No existe una plataforma madura para operar múltiples servicios.
## Decisión
Desplegar una sola aplicación organizada en módulos por capacidad de negocio. Cada módulo tendrá API pública, ownership lógico de datos y reglas de dependencia verificadas.
## Alternativas
- Microservicios: ofrecen independencia potencial, pero añaden red, consistencia eventual, observabilidad distribuida y operación que el equipo aún no necesita.
- Monolito organizado solo por capas técnicas: menor disciplina inicial, pero aumenta el riesgo de límites difusos.
## Consecuencias
- Despliegue y debugging simples.
- Transacciones locales.
- Escalado conjunto.
- Se requieren pruebas de arquitectura para evitar imports y escrituras cruzadas.
## Señales de revisión
- Equipos diferentes necesitan desplegar capacidades de forma independiente.
- Inventario presenta un perfil de escala claramente distinto.
- Un límite de dominio se mantiene estable y medido.El ADR no promete que el monolito sea permanente. Explica por qué es correcto ahora y qué evidencia cambiaría la decisión.
preferencia:
“me gusta PostgreSQL”
decisión:
“PostgreSQL permite restricciones y transacciones necesarias para inventario,
el equipo sabe operarlo y el volumen estimado cabe dentro de una instancia gestionada”Una decisión arquitectónica conecta una opción con drivers. Sin esa conexión solo existe una preferencia técnica.
Decisión barata de revertir. Conviene limitar análisis y aprender mediante implementación.
Decisión con migración costosa, datos persistentes o contratos públicos. Necesita más evidencia, prototipos y estrategia de salida.
La clasificación no es permanente. Una decisión reversible puede volverse costosa cuando acumula consumidores o datos.
Un ADR útil no enumera solo ventajas. Debe indicar qué se sacrifica.
usar eventos para notificaciones
optimiza:
desacoplamiento temporal y fan-out
sacrifica:
consistencia inmediata y simplicidad de diagnóstico
riesgo residual:
mensajes duplicados o retrasados
mitigación:
idempotencia, DLQ, trazas y reconciliaciónNo reescribas un ADR aceptado para fingir que siempre fue correcto. Cuando cambia la decisión:
Esto permite aprender de supuestos que resultaron incorrectos.
¿Qué comportamiento o riesgo importa?
¿Qué opciones son inviables por tiempo, regulación, capacidad o compatibilidad?
Usa escenarios, pruebas de concepto y matrices cuando ayuden.
No diseñes detalles innecesarios ni dejes abierta una restricción central.
Incluye trabajo operativo y migración, no solo desarrollo.
Conecta la decisión con fitness functions, métricas o pruebas.
Registra la decisión como provisional y define un experimento. No presentes una suposición como certeza.
Elige considerando reversibilidad, conocimiento del equipo y costo total. No siempre existe una respuesta objetivamente superior.
Incluye consumidores y operadores en la revisión. Una decisión local puede trasladar costos a otros.
Revisa el ADR; no lo obedezcas como una ley histórica.
Sin contexto y alternativas, el ADR no ayuda a evaluar vigencia.
Un ADR debe ser navegable y centrado. La evidencia extensa puede enlazarse.
La revisión debe corresponder al riesgo. Una gobernanza pesada ralentiza decisiones reversibles.
Un ADR que dice “los módulos no acceden a internals” necesita lint o pruebas de arquitectura.
Ocultar costos impide planear operación y hace parecer incorrecta cualquier dificultad futura.
No conviertas cada detalle trivial en un ADR. Usa documentación local, commits o convenciones para decisiones de bajo impacto y fácilmente reversibles.
Cohesión, acoplamiento y connascence aporta criterios para evaluar si los límites y dependencias elegidos localizan cambios o los propagan por todo el sistema.