Documentar una arquitectura

Un diseño que vive solo en la cabeza de quien lo hizo no se puede revisar, operar ni defender. Documentar una arquitectura no es llenar plantillas: es dejar claro qué existe, por qué se eligió así, qué se supuso y qué falta decidir.

Un diagrama por nivel

El modelo C4 (c4model.com) propone diagramas por niveles de zoom: contexto, contenedores, componentes y código, más diagramas de apoyo como el de despliegue. Para una arquitectura en la nube, tres niveles cubren casi todo:

En C4, «contenedor» significa una unidad que se ejecuta o guarda datos (una aplicación web, una API, una base de datos), no necesariamente un contenedor Docker. Las vistas de plano de este curso siguen el estilo del nivel de despliegue: mira la de la ciudad VPC, que va de la región a la subred y al servicio.

Lo que todo diagrama debe decir

• Título y propósito: qué muestra y para qué decisión sirve.
• Versión, fecha y estado: borrador, propuesto, aprobado u obsoleto.
• Leyenda: qué significa cada color, línea y forma. Sin leyenda, cada lector inventa la suya.
• Supuestos y decisiones abiertas: lo que no está resuelto también se dibuja, marcado como tal.
• Flujo consistente: de izquierda a derecha, usuarios a la izquierda y datos a la derecha, en todos los diagramas del sistema.
• Límites de confianza: dónde cambia el nivel de confianza. Internet → borde, una cuenta → otra, tu sistema → un tercero. Ahí van los controles de seguridad, y ahí mira primero un revisor.

• 

  AWS Architecture Icons

  Los símbolos estándar del mapa

  El paquete oficial de iconos de AWS, para PowerPoint y como archivos sueltos. Se actualiza varias veces al año: usa la versión vigente.
• 

  AWS Architecture Center

  Arquitecturas de referencia, guías y patrones por industria y caso de uso. Buen punto de partida antes de dibujar desde cero.
• 

  AWS Well-Architected Tool

  Revisa una carga contra los pilares de Well-Architected y lentes especializados, como el SaaS Lens, y deja registro de riesgos y mejoras.

Registrar decisiones con ADR

Un diagrama dice qué. Un registro de decisión de arquitectura (ADR, Architecture Decision Record) dice por qué. Es un documento corto con cuatro partes: contexto, decisión, alternativas consideradas y consecuencias, buenas y malas.

ADR-007: Base de datos de pedidos en Aurora PostgreSQL
Estado: Aceptada · 2026-10-14 · Reemplaza a: ninguna

Contexto
  Los pedidos necesitan transacciones entre tablas y reportes en SQL.
  El equipo ya opera PostgreSQL. Objetivos: RPO 1 minuto, RTO 30 minutos.

Decisión
  Aurora PostgreSQL Multi-AZ en la región principal, con Aurora Global
  Database hacia una región secundaria.

Alternativas consideradas
  - DynamoDB: escala sin esfuerzo, pero los reportes ad hoc son difíciles.
  - PostgreSQL en EC2: más control, mucha más operación (parches, réplicas).

Consecuencias
  + Cambio de región administrado; sin curva de aprendizaje para el equipo.
  - Dependencia elegida: Global Database es propio de Aurora.
    Salida: replicación lógica hacia cualquier PostgreSQL.
  - Revisar cada trimestre el costo de la región secundaria.

Un ADR aceptado no se edita: si la decisión cambia, escribes uno nuevo que lo reemplaza y marcas el anterior como reemplazado. Así queda la historia completa de por qué el sistema es como es. Las consecuencias negativas son la parte más útil: es donde quedan escritas las dependencias elegidas, como las de portabilidad y dependencia del proveedor.

De «tiene que estar siempre arriba» a números

Los atributos de calidad (disponibilidad, latencia, durabilidad, seguridad, costo) solo sirven si se pueden medir. Un requisito que no se puede verificar no se puede cumplir.

Las cifras de la tabla son ejemplos. Las reales salen de una conversación con el negocio sobre cuánto cuesta cada hora caída y cada dato perdido. Profundiza en SLI y SLO y en RPO y RTO a fondo.

Supuestos, restricciones, riesgos y temas abiertos

Lo que más daño hace es lo implícito: un supuesto que nadie escribió y que todos creían distinto. Escribirlo cuesta una línea; descubrirlo en un incidente cuesta mucho más.