Los Diagramas de Arquitectura No Son Documentación de Arquitectura
Un diagrama de arquitectura es útil, pero es solo una vista de un sistema. Si el diagrama es la documentación, quedan sin respuesta preguntas importantes: por qué existe el diseño, qué suposiciones lo moldearon, qué pasa cuando algo falla y quién es responsable de mantenerlo sano.
Una buena documentación de arquitectura le da contexto al diagrama. Permite entender no solo qué está desplegado, sino cómo se espera que el sistema se comporte y evolucione.
Un diagrama te dice qué existe
Considera un diagrama típico de AWS: CloudFront frente a un Application Load Balancer, servicios ECS en subredes privadas, Aurora para datos relacionales y SQS para trabajo asíncrono.
Esa vista puede comunicar componentes, conexiones, fronteras de red y quizás el flujo de datos. Lo que normalmente no puede decirte es por qué se eligió ECS en lugar de Lambda, si los mensajes de SQS deben procesarse en orden, cuál es el objetivo de recuperación de Aurora o qué pasa si una dependencia externa no está disponible.
Esos detalles también son arquitectura.
La distinción es simple: un diagrama describe la estructura. La documentación preserva el razonamiento y el modelo operativo detrás de esa estructura.
Qué debe contener una documentación de arquitectura útil
No necesitas un documento de 70 páginas. Para muchos sistemas, un conjunto pequeño de artefactos mantenidos es más útil que un documento enorme en el que nadie confía.
- Contexto del sistema. Indica el propósito del sistema, sus usuarios, sus dependencias externas, sus fronteras principales y las restricciones de negocio o técnicas importantes.
- Vistas de arquitectura. Mantén los diagramas enfocados. Una vista de contexto, una vista de ejecución/componentes, una vista de flujo de datos y una vista de seguridad o fronteras de confianza responden preguntas distintas. No fuerces todo en una sola imagen.
- Decisiones de arquitectura. Registra las decisiones significativas con Architecture Decision Records (ADRs) breves: el problema, las opciones consideradas, la decisión, las consecuencias y el estado.
- Realidad operativa. Documenta los modos de fallo esperados, las restricciones de escalado, la observabilidad, los backups, las expectativas de recuperación y los runbooks importantes.
- Responsabilidad y vigencia. Identifica un responsable, una fuente de verdad y un disparador de revisión. La documentación sin responsable termina convirtiéndose en evidencia histórica en lugar de guía operativa.
Un flujo de trabajo práctico
Empieza por el sistema, no por una plantilla de documentación.
Primero, crea un diagrama de contexto de alto nivel que muestre la frontera del sistema, los usuarios y los sistemas externos. Luego añade solo las vistas de arquitectura necesarias para explicar el comportamiento relevante: rutas de solicitud, procesamiento asíncrono, movimiento de datos o fronteras de confianza.
Después, asocia las decisiones a la arquitectura. Si existe una cola porque una API externa no es confiable, dilo. Si se usa Aurora porque la carga de trabajo requiere transacciones relacionales, captura ese razonamiento. Seis meses después, la razón suele ser más valiosa que el ícono de la base de datos.
A continuación, documenta cómo se comporta el diseño bajo estrés y ante fallos. Haz preguntas concretas: ¿Qué se reintenta? ¿Qué puede duplicarse? ¿Dónde ocurre el backpressure? ¿Qué alarmas importan? ¿Qué se restaura tras un fallo regional o de datos?
Por último, revisa la documentación cuando cambie la arquitectura, no simplemente una vez por trimestre. Un pull request que cambia una integración importante, un modelo de persistencia, una frontera de red o una estrategia de resiliencia es un disparador natural de documentación.
Ejemplo: la razón ausente detrás de una cola SQS
Imagina un diagrama que muestra API Gateway → Lambda → SQS → Lambda → API de terceros.
Las cajas y las flechas parecen sencillas. Un desarrollador que reemplace la cola por una llamada síncrona directa podría incluso verlo como una simplificación.
La documentación ausente cambia el panorama: la API de terceros tiene fallos intermitentes; las solicitudes deben aceptarse incluso durante una caída; es posible la entrega duplicada; el consumidor está diseñado para ser idempotente; los mensajes fallidos terminan en una dead-letter queue para su investigación.
Ahora SQS no es solo una caja. Su propósito arquitectónico, su semántica de fallo y sus consecuencias operativas quedan claros.
Compromisos y errores comunes
Más documentación no es automáticamente mejor. Los documentos detallados generan costo de mantenimiento, y la información que cambia con frecuencia puede quedar obsoleta rápidamente. Documenta la intención estable y las decisiones importantes; genera los inventarios de recursos y otros datos que cambian rápido a partir del entorno cuando sea práctico.
Un error común es un diagrama enorme que contiene cada subred, rol IAM, cola, función y almacén de datos. Puede ser técnicamente exacto y a la vez difícil de usar. Es preferible tener múltiples vistas, cada una diseñada para responder una pregunta específica.
Otro error es documentar solo el diseño previsto. La documentación de arquitectura debe reconocer las restricciones operativas y las debilidades conocidas. Una limitación actual registrada con honestidad es más útil que un diagrama limpio que implica que no existe.
La conclusión práctica
Conserva el diagrama, pero deja de pedirle que cargue con toda la arquitectura. Combina la estructura visual con decisiones, restricciones, comportamiento ante fallos, expectativas operativas y responsabilidad, para que el siguiente ingeniero entienda tanto qué es el sistema como por qué llegó a ser así.
Para un entorno AWS que además necesita una vista actual de lo que realmente está desplegado, ArchNube.com ofrece un enfoque complementario. Archnube Assess se conecta a través de un rol IAM de solo lectura, estrecho y controlado por el cliente, descubre los recursos de AWS soportados y aplica reglas deterministas para producir hallazgos explicables sobre riesgos, debilidades e ineficiencias de arquitectura, sin acceso de escritura ni juicio de IA de caja negra.