Dibuja la vista que necesita tu lector

Empieza desde fuera del sistema

Una vista de contexto ubica a Relay entre personas y sistemas vecinos.

Debería responder quién lo usa, qué ofrece y dónde están las dependencias externas. Por ejemplo, el backend de un producto envía trabajos y un proveedor de correo produce un efecto externo. Evita los detalles de implementación en este nivel.

Un interesado debería poder ubicar la frontera del sistema sin aprender un framework. Incluye una leyenda para cualquier notación que pueda ser ambigua, sobre todo las fronteras de confianza y la propiedad de los datos.

Acércate a las aplicaciones y los almacenes

Una vista de contenedores de C4 describe las principales aplicaciones en ejecución y los almacenes de datos dentro de un sistema.

Aquí «contenedor» es una abstracción de arquitectura, no necesariamente un contenedor de Docker. Relay podría tener una aplicación de API, un proceso worker y una base de datos de trabajos. Etiqueta cada responsabilidad y cada interacción: «envía un trabajo validado por HTTPS» informa más que una flecha sin etiqueta.

Agrega una vista de componentes solo cuando responda una pregunta que la vista más amplia no puede responder. Más detalle no es automáticamente más útil.

Muestra un escenario que se desarrolla en el tiempo

Un diagrama estático no puede mostrar cuándo un worker confirma (commit) un resultado en relación con el aviso de que el trabajo terminó (acknowledge, ack).

Ese aviso le dice a la cola que el trabajo ya está hecho, para que no lo vuelva a entregar. Usa un diagrama de secuencia u otra vista dinámica para ese escenario. Recorre una caída entre el efecto externo y el aviso de terminado.

¿Quién reintenta? ¿Dónde se comprueba la clave de idempotencia? Una clave de idempotencia (idempotency key) es un identificador único de una operación prevista, para reconocer una repetición de esa operación y no hacerla dos veces.

Una vista de despliegue puede mostrar por separado dónde se ejecutan los procesos y qué fallas comparten. Mantén los nombres coherentes entre vistas y revisa los diagramas cuando cambie la implementación. Trata cada diagrama como una afirmación que hay que contrastar con el sistema.