Diagrama de arquitectura orientada a eventos: cómo dibujar productores, topics y consumidores de Kafka

En un sistema de petición y respuesta, las flechas del diagrama son el grafo de llamadas. En un sistema orientado a eventos, no. Un productor escribe un evento en un topic y no sabe quién lo lee. Si lo dibujas de forma ingenua, con todos los servicios conectados a una gran caja de Kafka, el diagrama oculta todo lo que necesitas: qué eventos existen, quién reacciona a ellos, en qué orden y qué pasa cuando un consumidor falla.

Esta guía te da una notación para diagramas de arquitectura orientada a eventos que mantiene el flujo legible, recorre un ejemplo de procesamiento de pedidos en Kafka y cubre los detalles que se suelen olvidar al dibujar: claves, grupos de consumidores, el outbox y la ruta de dead-letter.

Lo que el diagrama tiene que mostrar

Un diagrama orientado a eventos debería responder a estas preguntas sin un documento aparte:

• ¿Qué eventos existen? Con nombres en pasado, como OrderPlaced o PaymentFailed.
• ¿Quién produce cada uno? Lo sano por defecto es que cada tipo de evento tenga exactamente un propietario.
• ¿Quién lo consume y con qué grupo de consumidores? En Kafka, cada grupo de consumidores recibe todos los eventos, así que cada grupo es un lector independiente.
• ¿Qué determina el orden? Kafka solo mantiene el orden dentro de una partición, y la clave decide la partición.
• ¿Qué pasa cuando algo falla? Reintentos, dead-letter topics y quién hace el replay.

Una notación que funciona

Elemento	Cómo dibujarlo
Productor	Un nodo de servicio con una conexión discontinua hacia el topic, etiquetada con el tipo de evento
Topic	Un nodo propio, con el nombre que tiene en el clúster (orders.v1) y la clave en la etiqueta
Grupo de consumidores	Una conexión discontinua del topic al consumidor, etiquetada con el id del grupo
Evento frente a comando	Eventos en pasado (OrderPlaced), comandos en imperativo (ReserveStock)
Dead-letter topic	Un nodo de topic aparte, alimentado por el consumidor que se dio por vencido
Conector	Un nodo entre un topic y un almacenamiento externo, como un sink hacia el almacén de datos
Clúster de brokers	Un marco alrededor de los topics; los brokers y las particiones van en el diagrama de operaciones

Usa conexiones continuas solo para llamadas síncronas, como una petición HTTP a un proveedor de pagos. Así, quien lea el diagrama sabrá de un vistazo qué partes de un flujo ocurren en la misma petición y cuáles después.

El ejemplo: eventos de pedidos en Kafka

Una tienda online procesa los pedidos con eventos:

1. El servicio orders escribe el pedido y una fila de outbox en la misma transacción de base de datos.
2. Un outbox relay (Debezium sobre Kafka Connect) lee el outbox a través del log de la base de datos y publica OrderPlaced en orders.v1, con order_id como clave.
3. Tres grupos de consumidores leen orders.v1: payments cobra la tarjeta, inventory reserva stock y un warehouse sink carga cada evento en el almacén de datos.
4. Payments publica PaymentSucceeded o PaymentFailed en payments.v1, también con order_id como clave, y el servicio orders lo consume para actualizar el estado del pedido.
5. Cuando inventory no puede procesar un mensaje tras tres intentos, lo escribe en inventory.dlq y sigue adelante.

Este es el flujo completo en un solo lienzo:

Fíjate en lo que el diagrama deja claro: nadie llama a payments, añadir un cuarto grupo de consumidores no cambia nada aguas arriba, y los eventos de un mismo pedido mantienen su orden dentro de cada topic porque ambos usan order_id como clave (Kafka no garantiza el orden entre topics).

Cinco reglas para diagramas orientados a eventos

1. Los topics son nodos, no flechas

Una flecha de orders a payments con la etiqueta "Kafka" sugiere una llamada que no existe. Dibuja el topic como un nodo entre ambos. Es algo real, con un nombre, un propietario, un periodo de retención y un esquema.

2. Las flechas siguen a los datos

Dibuja del productor al topic y del topic al consumidor, en la dirección en la que se mueven los datos. Los consumidores de Kafka hacen pull, pero un diagrama con flechas que van de los consumidores a los topics se lee al revés para casi todo el mundo. Si la semántica pull importa para la discusión, añade una nota.

3. Etiqueta los eventos y los grupos de consumidores

Pon el tipo de evento en la conexión del productor y el grupo de consumidores en cada conexión de consumidor. Cuando alguien pregunte "¿quién más lee OrderPlaced?", la respuesta es la lista de conexiones etiquetadas que salen del topic.

4. Muestra la clave cuando el orden importa

Kafka garantiza el orden dentro de una partición, y los eventos con la misma clave van a la misma partición. Si tus consumidores dependen de ver OrderPlaced antes que OrderCancelled, escribe la clave en el topic: orders.v1 · key order_id. Un topic sin clave en la etiqueta invita a hacerse esa pregunta.

5. Dibuja el camino de fallo

Los grupos de consumidores de Kafka no tienen una dead-letter queue integrada: el código de tu consumidor o tu framework decide cuántas veces reintentar y dónde dejar un mensaje que no puede procesar (los conectores sink de Kafka Connect sí tienen un ajuste de dead-letter topic). Dibuja esa decisión. Un dead-letter topic con una conexión desde el consumidor, y una nota sobre quién lo vigila y cómo se reprocesan los mensajes, te ahorra un incidente.

Dibuja el outbox, no el atajo

Si un servicio escribe en su base de datos y luego publica en Kafka en dos pasos separados, una caída entre ambos hace que se pierda un evento o que se publique uno de un cambio que nunca se confirmó. El patrón outbox evita esa doble escritura: el servicio escribe el evento en una tabla outbox dentro de la misma transacción, y un relay lo publica.

En el diagrama, dibuja el camino real: del servicio a la base de datos, de ahí al relay y del relay al topic. Una flecha directa del servicio al topic describiría un sistema distinto y menos fiable, y la gente tomará decisiones basándose en ella.

Coreografía u orquestación

El ejemplo usa coreografía: los servicios reaccionan a los eventos de los demás y nadie está a cargo del flujo completo. Si en su lugar usas un orquestador, es decir, un motor de workflows que envía comandos como ReserveStock y espera respuestas, dibuja el orquestador como un servicio en el centro y etiqueta sus conexiones como comandos. En cualquier caso, numera los pasos del flujo principal en las conexiones para que se pueda seguir la saga en orden.

Deja el clúster fuera de la vista lógica

Los brokers, las particiones, los factores de replicación y los nodos controladores importan para la capacidad y la operación, no para entender el flujo. Ponlos en un diagrama de operaciones aparte. En la vista lógica basta con un marco con la etiqueta "Kafka cluster" alrededor de los topics.

Constrúyelo en Archboard

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Añade los servicios como nodos Contenedor del pack Modelo C4, y la base de datos de orders desde el pack Datos (Postgres).
3. Añade un Marco del pack Básico con la etiqueta Kafka cluster y coloca dentro nodos Tema del pack Datos.
4. Añade el outbox relay y el warehouse sink como contenedores con Kafka Connect en el campo Tecnología, y un nodo Almacén de datos del pack Datos.
5. Conecta los puertos, pon las conexiones de eventos en línea discontinua y etiquétalas con los tipos de evento y los grupos de consumidores.
6. Ábrelo en modo presentación para la revisión, comparte el enlace en vivo o exporta SVG y PNG.

El ejemplo usa 11 nodos de diagrama, dentro de los 15 del plan Free. Para otro layout de streaming, consulta /examples/streaming-data-platform, y para la parte síncrona de una tienda similar, la guía del diagrama de arquitectura de microservicios.

Preguntas frecuentes

¿Debo dibujar las particiones? No en la vista lógica. Escribe el número de particiones en la etiqueta del topic si importa, y dibuja las particiones y los brokers en un diagrama de operaciones.

¿En qué se diferencia una cola de un topic en el diagrama? En una cola, cada mensaje va a un solo consumidor; en un topic de Kafka, cada grupo de consumidores recibe todos los mensajes. Usa un nodo Cola para colas como SQS o RabbitMQ, e indica de qué semántica dependes.

¿Dónde van los esquemas de eventos? En una nota o en la etiqueta del topic, con un enlace al schema registry o al repositorio dueño del esquema. El diagrama debe mostrar que existe un contrato y dónde está.

¿Cómo muestro el replay? Escribe la retención en el topic (por ejemplo retention 7d) y añade una nota sobre cómo un grupo de consumidores restablece sus offsets. El replay es una característica de diseño; hazlo visible.

¿Necesito un diagrama por evento? No. Un diagrama por flujo de negocio funciona bien. Enumera los eventos en las conexiones y mantén un catálogo de eventos para la lista completa.

Empieza gratis — un puesto, sin tarjeta de crédito.