Un diagrama de arquitectura de software muestra cómo se reparten las responsabilidades de un sistema y cómo se comunican sus partes. Para leerlo, conviene empezar por su alcance y su leyenda, y después seguir una acción concreta del usuario a través de los componentes implicados. Las preguntas útiles son qué hace cada parte, qué datos guarda y qué ocurre cuando una dependencia tarda en responder o deja de estar disponible.
Un checkout ofrece un ejemplo concreto. La pantalla donde el cliente pulsa «Pagar» puede depender del procesamiento de pedidos, de los datos almacenados y de un proveedor de pagos externo. Un cambio que parece pequeño en esa pantalla puede afectar a varias de esas responsabilidades. El diagrama ayuda a identificar dónde corresponde hacer el trabajo y qué supuestos hay que comprobar antes de acordar una fecha de entrega.
Empezar por la pregunta que responde el diagrama
Los diagramas de arquitectura tienen distintos niveles de detalle. Una vista de contexto sitúa el producto junto a sus usuarios y los sistemas externos. Una vista más detallada muestra las aplicaciones y los almacenes de datos del producto. Una vista de despliegue muestra dónde se ejecuta el software, con la infraestructura y los límites de red. Mezclar estos niveles sin explicarlo puede dificultar la lectura.
El modelo C4 distingue expresamente estas vistas. En su diagrama de contenedores, «contenedor» significa una aplicación o un almacén de datos, sin que tenga que ser un contenedor Docker. El ejemplo de este artículo es una vista simplificada de responsabilidades y comunicaciones. No pretende ser un diagrama C4 completo ni un plano de infraestructura de producción, y tampoco prescribe una tecnología concreta.
Un diagrama de checkout con sus límites explicados
Mercato es una plataforma de comercio electrónico hipotética. En este ejemplo, el frontend web muestra el checkout, el backend de pedidos valida la petición y coordina el pago, y una base de datos guarda el pedido y su estado de pago. El proveedor de pagos queda fuera del límite de Mercato porque es un sistema independiente operado por otra organización. El frontend se ejecuta en el navegador del cliente, aunque su código pertenece a Mercato.
Abrir el diagrama en tamaño completo.
Las flechas continuas representan peticiones entre las partes del sistema; la discontinua representa una notificación posterior del proveedor de pagos. Los números orientan el recorrido explicado a continuación. Se omiten las respuestas y varios aspectos de un sistema de producción, como la comprobación de identidad, el inventario y la recogida de los datos de pago en el navegador mediante el proveedor. El dibujo no propone que los datos de tarjeta sin procesar deban pasar por el backend de pedidos.
Cada caja representa una responsabilidad dentro del nivel de detalle elegido. Varias responsabilidades pueden implementarse en una misma aplicación, y una aplicación puede ejecutarse en varias instancias. El número de cajas no permite deducir si el producto utiliza microservicios, cuántos servidores tiene ni cuánto tráfico puede soportar.
Seguir un pedido a través del sistema
El cliente envía el checkout a través del frontend. El backend valida la petición, comprueba la información necesaria para el pedido y registra un estado inicial. En este ejemplo, el servidor recalcula el importe en lugar de confiar en un total enviado por el navegador. Una nueva promoción tendría que relacionarse aquí con las reglas de precios y los requisitos para aplicarla.
Después, el backend solicita el pago al proveedor y utiliza una referencia que permite asociarlo con el pedido. Según el método de pago, el resultado puede llegar de inmediato o exigir una acción adicional del cliente y un procesamiento posterior. El diagrama separa la solicitud de pago de la recepción de su resultado final porque el producto tiene que gestionar el tiempo que transcurre entre ambas.
En este caso, una notificación del proveedor llega al backend, que la verifica y actualiza el estado del pago almacenado. La vista del cliente puede reflejar entonces el estado de referencia que mantiene el backend. Ese camino de vuelta no se ha dibujado para facilitar la lectura; su ausencia no significa que el frontend no pueda volver a consultar el estado.
Una notificación puede reenviarse o llegar después de otro evento. El procesamiento debe evitar que una misma acción de negocio se aplique varias veces y contemplar el orden de los cambios de estado. Stripe documenta estos comportamientos de entrega para sus webhooks. La consecuencia de producto es concreta: una notificación duplicada no debe generar una segunda instrucción de preparación para el mismo pedido.
Leer las flechas como dependencias
Una petición crea una dependencia respecto a la parte que la recibe. Si el proveedor de pagos responde despacio, el checkout puede tener que esperar o mostrar un estado pendiente. Si la base de datos no está disponible, el backend puede no ser capaz de registrar el pedido con seguridad. El diagrama señala dónde investigar, pero no revela el tiempo de espera, la política de reintentos ni el comportamiento de recuperación. Esos detalles necesitan una explicación del equipo.
Un timeout, o tiempo de espera agotado, puede dejar a quien llama sin conocer el resultado. El proveedor podría haber aceptado el pago aunque el backend no recibiera la respuesta. Mostrar «pago fallido» y crear inmediatamente un nuevo intento podría provocar una experiencia incorrecta para el cliente. El producto necesita una forma de resolver los estados inciertos y orientar al usuario mientras se comprueban los registros del proveedor.
Una notificación posterior evita tener que esperar a todos los resultados dentro de la petición inicial, pero introduce otra dependencia: el evento tiene que llegar y procesarse. Si se retrasa, un pedido pagado puede seguir figurando como pendiente. Soporte necesita información suficiente para distinguir esa situación de un pedido sin pagar antes de recomendar al cliente que vuelva a intentarlo.
Usar el dibujo para evaluar un cambio
Un descuento en los gastos de envío afectaría a lo que muestra el frontend, a cómo calcula el backend los requisitos y al importe enviado al proveedor de pagos. Si el pedido debe conservar las condiciones aceptadas durante el checkout, los datos almacenados también pueden necesitar recoger esas condiciones. El diagrama ofrece un lugar compartido donde seguir el cambio; por sí solo no permite calcular el esfuerzo de implementación.
El mismo dibujo puede servir para hablar de una caída del proveedor de pagos. Ingeniería podría explicar un recorrido de pedidos pendientes, la desactivación de un método de pago o un proceso de recuperación. Producto puede decidir entonces qué verá el cliente y qué comunicará soporte, dentro de las limitaciones técnicas y contractuales. Añadir un segundo proveedor es otra opción de arquitectura, pero exige trabajo de integración y operación que el dibujo no cuantifica.
- ¿Qué componente mantiene el estado de referencia del pedido y del pago, y quién puede modificarlo?
- ¿Qué llamadas deben terminar para que el cliente continúe y qué resultados pueden llegar más tarde?
- ¿Qué ocurre si una petición agota su tiempo de espera después de que el sistema receptor haya actuado?
- ¿Cómo se gestionan las notificaciones duplicadas y las actualizaciones contradictorias?
- ¿Qué partes cambian con esta funcionalidad y pueden mantener versiones compatibles durante el lanzamiento?
Qué no permite comprobar este diagrama
Un diagrama de alto nivel no demuestra que el checkout sea seguro, que pueda recuperarse de un fallo ni que soporte una campaña de ventas. Quedan fuera los controles de acceso, la distribución del despliegue y las mediciones de capacidad. Tampoco permite confirmar el comportamiento durante una incidencia sin evidencias de los componentes en funcionamiento. Estas conversaciones pueden necesitar una vista más detallada, mediciones de rendimiento o la traza de una petición real.
Antes de utilizar un diagrama para planificar trabajo, conviene comprobar su fecha, quién lo mantiene y si describe el sistema actual o una propuesta. Una conexión desactualizada puede hacer que el equipo pase por alto una dependencia que ya existe. La guía de arquitectura de software explica los conceptos de las cajas. Para cambiar versiones manteniendo el acceso de los clientes, puede consultarse desplegar frente a lanzar una funcionalidad.
El libro Arquitectura de software para Product Managers desarrolla la relación entre arquitectura y decisiones de producto. La guía de APIs ofrece más detalle sobre las peticiones y respuestas que conectan las partes de un sistema.
Referencias técnicas
- Modelo C4: diagramas de contenedores, alcance y límites de la vista de despliegue.
- Microsoft: capas lógicas y niveles físicos.
- Stripe: entrega de webhooks, reintentos y orden de eventos.
La notificación del proveedor de este diagrama se desarrolla en Webhooks, APIs y polling, que compara las formas de actualización y sus requisitos de recuperación.
