Cómo Reconstruir la Arquitectura de una Aplicación Existente

La arquitectura de software suele estar menos documentada de lo que los equipos suponen. Los repositorios, las cuentas cloud, los pipelines de despliegue y el conocimiento operativo pueden revelar, cada uno, una parte del sistema, pero ninguno ofrece por sí solo la imagen completa.

La reconstrucción de arquitectura es el proceso de combinar esas fuentes en un modelo verificado de cómo se construye, despliega, protege y opera una aplicación. El objetivo no es crear un diagrama perfecto. Es establecer suficiente entendimiento compartido para respaldar el mantenimiento, la modernización, la respuesta a incidentes, las revisiones de seguridad y la planeación técnica.

Comienza con evidencia, no con supuestos

Una aplicación existente normalmente tiene al menos tres arquitecturas distintas:

• Arquitectura prevista: lo que proponía el diseño original.
• Arquitectura implementada: lo que define el código fuente y la infraestructura.
• Arquitectura en tiempo de ejecución: lo que está realmente desplegado y procesando tráfico.

Estas versiones pueden diferir entre sí.

Un repositorio podría contener un servicio sin usar. Una cuenta cloud puede incluir recursos remanentes de un despliegue anterior. Un diagrama de arquitectura puede omitir una cola introducida durante un incidente.

Por esta razón, toda conclusión arquitectónica debe estar respaldada por evidencia.

La evidencia útil incluye:

• Repositorios de aplicación e infraestructura
• Inventarios de recursos cloud
• Pipelines de despliegue
• Configuración en tiempo de ejecución
• Especificaciones de API
• Esquemas de bases de datos
• Logs, métricas y trazas distribuidas
• Políticas de identidad y acceso
• Entrevistas con desarrolladores y operadores

Trata los diagramas existentes como insumos, no como registros definitivos.

Un flujo de trabajo práctico de reconstrucción

1. Define el límite de la reconstrucción

Decide qué es lo que intentas entender.

Para una evaluación puntual, el límite podría ser un solo flujo de trabajo orientado al cliente. Para una iniciativa de modernización, puede incluir todos los servicios, almacenes de datos, integraciones, pipelines de despliegue y cuentas de AWS.

Documenta:

• Capacidades de negocio dentro del alcance
• Entornos dentro del alcance
• Cuentas y regiones de AWS
• Repositorios
• Sistemas externos
• Exclusiones conocidas

Sin un límite definido, el descubrimiento de arquitectura puede convertirse en un ejercicio de inventario sin fin.

2. Construye un inventario del sistema

Crea una tabla simple que enumere cada componente conocido y su rol.

Componente	Tipo	Responsabilidad	Propietario	Evidencia	Estado
API de clientes	Servicio Lambda	Gestiona las solicitudes de reserva	Equipo de plataforma	CDK y logs	Verificado
Cola de notificaciones	Amazon SQS	Almacena en búfer mensajes salientes	Desconocido	Inventario de AWS	Parcialmente verificado

Incluye servicios de aplicación, bases de datos, colas, almacenamiento de objetos, tareas programadas, APIs de terceros, proveedores de identidad y herramientas de despliegue.

No documentes cada recurso de AWS con el mismo nivel de detalle. Una tabla de rutas puede importar durante una investigación de red, pero normalmente no pertenece a un diagrama de arquitectura a nivel de aplicación.

3. Traza los flujos de trabajo críticos

Selecciona un pequeño número de operaciones críticas para el negocio y síguelas de principio a fin.

Ejemplos incluyen:

• Autenticación de usuarios
• Envío de pedidos
• Procesamiento de pagos
• Carga de archivos
• Generación de reportes
• Notificación a clientes

Para cada flujo, identifica:

1. El punto de entrada
2. Las verificaciones de autenticación y autorización
3. Las llamadas síncronas entre servicios
4. Los eventos y colas
5. Las lecturas y escrituras de datos
6. Las integraciones externas
7. Las rutas de falla y reintento
8. Los logs y métricas

Trazar los flujos revela dependencias que los inventarios de recursos frecuentemente pasan por alto.

4. Concilia código, infraestructura y tiempo de ejecución

Compara lo que la aplicación declara con lo que realmente existe.

Para una aplicación en AWS, esto puede implicar revisar:

• Definiciones de AWS Cloud Development Kit o Terraform
• Rutas de API Gateway
• Variables de entorno de Lambda
• Reglas de EventBridge
• Suscripciones de SQS y dead-letter queues
• Conexiones a bases de datos
• Roles y políticas de IAM
• Logs y alarmas de CloudWatch
• Etapas de despliegue de CI/CD

Cuando las fuentes no coincidan, registra la discrepancia en lugar de elegir la respuesta más conveniente.

Por ejemplo:

El repositorio define un consumidor de EventBridge, pero no existe ninguna regla equivalente en producción. Confirma si el consumidor está obsoleto o si el despliegue está incompleto.

Las incógnitas son resultados válidos de la reconstrucción. Ocultarlas hace que el modelo final sea menos confiable.

5. Produce diagramas en varios niveles

Un solo diagrama grande rara vez funciona.

Crea vistas separadas para:

• Contexto del sistema: usuarios, la aplicación y los sistemas externos
• Vista de servicios: aplicaciones desplegables y los principales almacenes de datos
• Flujo crítico: movimiento de solicitudes, eventos y datos
• Vista de despliegue: cuentas de AWS, regiones, redes y servicios en tiempo de ejecución
• Límites de confianza: puntos donde cambia la identidad, los permisos o la sensibilidad de los datos

Cada conexión debe representar una relación en tiempo de ejecución verificada o explícitamente marcada como supuesto. Evita dibujar líneas simplemente porque dos servicios parecen relacionados.

Ejemplo: reconstrucción de una plataforma de reservas

Considera una aplicación de reservas serverless con un frontend en React y un backend en AWS.

La inspección del repositorio muestra un frontend en Amazon S3, Amazon API Gateway, varias funciones Lambda y una base de datos Aurora. La cuenta de AWS también contiene EventBridge, SQS y workers de notificación que no aparecen en el diagrama original.

Trazar una solicitud de reserva revela el flujo real:

1. El navegador carga la aplicación a través de CloudFront.
2. API Gateway valida la solicitud e invoca la función Lambda de reservas.
3. La función Lambda escribe la cita en Aurora.
4. El servicio publica un evento BookingCreated en EventBridge.
5. Una regla de EventBridge envía el evento a una cola SQS.
6. Una función Lambda de notificaciones lee el mensaje y llama a un proveedor externo de mensajería.
7. Las notificaciones fallidas se mueven a una dead-letter queue.

La arquitectura reconstruida ahora explica tanto la solicitud orientada al cliente como la ruta asíncrona de notificación.

También expone una pregunta operativa: ¿quién monitorea y reprocesa la dead-letter queue?

Esa pregunta puede ser más valiosa que el propio diagrama.

Compensaciones y errores comunes

La reconstrucción de arquitectura es un ejercicio de muestreo. Los logs y las trazas muestran comportamiento observado, no cada ruta de ejecución posible. Los flujos de bajo volumen, las tareas programadas, los componentes de recuperación ante desastres y las integraciones inactivas pueden requerir una investigación separada.

Un error común es generar diagramas automáticamente a partir de una cuenta de AWS y tratar ese resultado como documentación de arquitectura. El descubrimiento automatizado es útil para el inventario, pero no puede explicar de forma confiable las responsabilidades de negocio, la propiedad de los componentes, la importancia de un flujo, o si un recurso está obsoleto.

Otro error es documentar únicamente el camino exitoso. Las políticas de reintento, los timeouts, las dead-letter queues, los procedimientos de recuperación manual y las fallas parciales son parte de la arquitectura.

Finalmente, evita pulir los diagramas antes de validarlos. Un modelo visualmente impresionante pero inexacto genera una falsa confianza.

Conclusión

Reconstruye la arquitectura moviéndote de la evidencia a los flujos de trabajo, y de los flujos de trabajo a diagramas verificados. Registra la incertidumbre explícitamente y separa la realidad desplegada del diseño previsto.

Comienza con un flujo de negocio crítico y trázalo a través de los repositorios, el entorno de AWS, los almacenes de datos, las integraciones y los logs operativos antes de intentar mapear todo el sistema.