Arquiteturas event-driven sao poderosas mas notoriamente dificeis de documentar. Eventos sao invisiveis, assincronos e desacoplados por design. Este guia mostra como usar o modelo C4 para documentar fluxos de eventos, event channels e padroes async -- e como o Archyl torna sistemas event-driven visiveis.

Documentacao de Arquitetura Event-Driven com Modelo C4

Arquitetura event-driven se tornou o padrao para construir sistemas escalaveis e fracamente acoplados. Servicos publicam eventos quando algo acontece. Outros servicos assinam esses eventos e reagem. O publicador nao sabe quem esta ouvindo. O assinante nao sabe quem publicou. O sistema e desacoplado, resiliente e flexivel.

Tambem e quase invisivel.

Quando voce olha para um diagrama C4 tradicional de um sistema event-driven, voce ve servicos com setas apontando para um message broker. Servico A publica para o Kafka. Servico B consome do Kafka. Mas quais eventos fluem entre eles? Qual e o schema? Quem mais esta ouvindo? O que acontece se um consumidor falha? O diagrama mostra o encanamento mas esconde o comportamento.

Documentar arquitetura event-driven requer tecnicas que tornam o invisivel visivel -- que mostram nao apenas a infraestrutura (brokers, filas, topicos) mas os eventos em si, seus fluxos, seus schemas e suas garantias. Este guia cobre como fazer isso usando o modelo C4 e como os recursos de event channel do Archyl tornam sistemas event-driven cidadaos de primeira classe na sua documentacao de arquitetura.

Por Que Sistemas Event-Driven Sao Dificeis de Documentar

Arquitetura event-driven introduz varios desafios de documentacao que nao existem em sistemas sincronos de request-response.

Fluxo de Controle Invisivel

Em um sistema sincrono, voce pode rastrear uma requisicao do cliente ao servidor seguindo a cadeia de chamadas. Servico A chama Servico B, que chama Servico C. O fluxo de controle e explicito e visivel no codigo.

Em um sistema event-driven, o fluxo de controle e implicito. Servico A publica um evento OrderCreated. Em algum lugar, Servico B reage a esse evento reservando estoque. Em outro lugar, Servico C reage enviando um email de confirmacao. Servico A nao sabe sobre B ou C. O fluxo de controle e definido pelas assinaturas de evento, nao pelo codigo do publicador.

Essa indirecao significa que voce nao pode entender o comportamento do sistema lendo o codigo de um unico servico. Voce precisa de uma visao de nivel mais alto que mostre os fluxos de eventos entre servicos -- e essa visao e exatamente o que a documentacao de arquitetura deve fornecer.

Relacionamentos Muitos-para-Muitos

Em arquiteturas sincronas, relacionamentos sao tipicamente um-para-um ou um-para-poucos. Servico A chama Servico B. O relacionamento e direto e documentado pela chamada de API.

Em arquiteturas event-driven, relacionamentos sao muitos-para-muitos. Um unico tipo de evento pode ter um produtor e cinco consumidores. Um unico servico pode consumir eventos de dez produtores diferentes. O grafo de relacionamentos e mais denso e complexo do que em sistemas sincronos.

Diagramas de arquitetura tradicionais tem dificuldade com essa densidade. Desenhar uma seta de cada produtor para cada consumidor atraves de cada topico cria um diagrama que parece um prato de spaghetti. Voce precisa de uma abordagem de documentacao que mostre fluxos de eventos no nivel certo de abstracao.

Evolucao de Schema

Schemas de eventos evoluem ao longo do tempo. O evento OrderCreated pode comecar com cinco campos e crescer para quinze em dois anos. Consumidores podem depender de campos especificos. Mudancas de schema podem quebrar consumidores se nao forem retrocompativeis.

Documentar o schema atual e necessario mas nao suficiente. Voce tambem precisa documentar a estrategia de versionamento de schema, garantias de compatibilidade e o historico de breaking changes.

Consistencia Eventual

Sistemas event-driven sao eventualmente consistentes por natureza. Quando Servico A publica um evento, Servico B pode processa-lo milissegundos depois ou minutos depois (se o consumidor estiver atrasado ou se retries forem necessarios). O sistema esta em um estado inconsistente durante essa janela.

A documentacao deve capturar esses limites de consistencia. Quais partes do sistema sao fortemente consistentes? Quais sao eventualmente consistentes? Qual e o atraso de propagacao esperado? O que acontece durante a janela de inconsistencia?

Dead Letter Queues e Tratamento de Erros

Quando um consumidor de eventos falha ao processar uma mensagem, o evento tipicamente vai para uma dead letter queue (DLQ). Mas o que acontece depois? Quem monitora a DLQ? Qual e a estrategia de retry? Como mensagens envenenadas sao tratadas?

Esses padroes de tratamento de erros sao criticos para o comportamento do sistema mas raramente sao documentados. Eles sao parte da arquitetura e devem ser visiveis na documentacao.

Modelando Sistemas Event-Driven com C4

O modelo C4 pode representar arquiteturas event-driven efetivamente com algumas adaptacoes em como voce usa cada nivel.

System Context: Foque em Fluxos de Dados, Nao Chamadas

No nivel de System Context, arquiteturas event-driven e sincronas parecem similares. Seu sistema interage com usuarios e sistemas externos. A diferenca-chave esta em como voce rotula os relationships.

Em vez de "chama" ou "consulta", use labels que descrevam fluxo de dados:

"Envia eventos de pedido para"
"Recebe confirmacoes de pagamento de"
"Publica eventos de analytics para"

Esses labels sugerem a natureza assincrona da comunicacao sem poluir a visao de alto nivel com detalhes de implementacao.

Diagrama de Container: Torne o Broker Visivel

O diagrama de Container e onde a arquitetura event-driven se torna distinta. O message broker (Kafka, RabbitMQ, Amazon SQS/SNS, Google Pub/Sub) deve ser um container de primeira classe no seu diagrama, nao um detalhe de implementacao invisivel.

Veja como um diagrama de Container para um sistema de e-commerce event-driven pode ser:

systems:
  - name: E-Commerce Platform
    type: software_system
    containers:
      - name: Order Service
        type: service
        technologies: [Go, PostgreSQL]
      - name: Inventory Service
        type: service
        technologies: [Java, PostgreSQL]
      - name: Notification Service
        type: service
        technologies: [Python, Redis]
      - name: Analytics Service
        type: service
        technologies: [Python, ClickHouse]
      - name: Event Bus
        type: queue
        technologies: [Apache Kafka]

relationships:
  - from: Order Service
    to: Event Bus
    label: "Publica OrderCreated, OrderCancelled"
  - from: Event Bus
    to: Inventory Service
    label: "Entrega eventos de pedido"
  - from: Event Bus
    to: Notification Service
    label: "Entrega eventos de pedido e pagamento"
  - from: Event Bus
    to: Analytics Service
    label: "Entrega todos os domain events"
  - from: Inventory Service
    to: Event Bus
    label: "Publica InventoryReserved, InventoryReleased"

Note como o Event Bus esta no centro do diagrama, e os relationships nomeiam explicitamente os tipos de evento que fluem atraves dele. Isso torna os fluxos de eventos visiveis sem criar setas diretas entre cada produtor e cada consumidor.

Event Channels: Um Conceito de Primeira Classe

Topicos, filas e streams individuais dentro do message broker merecem sua propria documentacao. Cada event channel tem propriedades que importam para entender o sistema:

Nome do channel: O topico Kafka, fila RabbitMQ ou fila SQS
Tipos de evento: Quais eventos fluem por este channel
Produtores: Quais servicos publicam neste channel
Consumidores: Quais servicos consomem deste channel
Serializacao: Como eventos sao codificados (JSON, Avro, Protobuf)
Estrategia de particionamento: Como eventos sao distribuidos entre particoes
Politica de retencao: Por quanto tempo eventos sao mantidos
Garantias de ordenacao: Se a ordem e preservada e em qual granularidade

No Archyl, event channels sao um tipo de entidade dedicado. Voce cria um event channel, especifica suas propriedades e o vincula aos servicos que produzem e consomem dele. Isso cria um modelo estruturado e consultavel dos seus fluxos de eventos.

Por exemplo, um event channel "orders" pode ser documentado como:

Nome: orders
Broker: Kafka
Produtores: Order Service
Consumidores: Inventory Service, Notification Service, Analytics Service, Billing Service
Tipos de Evento: OrderCreated, OrderUpdated, OrderCancelled, OrderCompleted
Serializacao: Avro com Schema Registry
Particionamento: Por order ID
Retencao: 7 dias

Esse nivel de detalhe torna a infraestrutura invisivel visivel e consultavel. Quando um desenvolvedor precisa saber quem esta consumindo eventos de pedido, a resposta esta documentada e acessivel.

Diagrama de Component: Event Handlers e Publishers

No nivel de Component, servicos event-driven tem estruturas internas distintas que valem documentar para servicos complexos:

Event Handlers: Componentes que consomem e processam tipos de evento especificos
Event Publishers: Componentes que produzem eventos
Sagas / Process Managers: Componentes que orquestram workflows multi-etapa atraves de eventos
Projections: Componentes que constroem read models a partir de event streams

Um diagrama de Component para o Order Service pode incluir:

Order Controller -- lida com requisicoes HTTP para gerenciamento de pedidos
Order Processor -- logica de negocio principal para criacao e validacao de pedidos
Event Publisher -- publica OrderCreated, OrderUpdated, OrderCancelled para o Kafka
Payment Event Handler -- consome eventos PaymentProcessed e PaymentFailed
Order Saga -- gerencia o workflow de cumprimento de pedidos entre servicos

Documente esses componentes quando o servico e complexo o suficiente para justifica-lo -- particularmente para servicos que participam de padroes de coreografia ou orquestracao.

Documentando Padroes Comuns de Event-Driven

Certos padroes aparecem repetidamente em sistemas event-driven. Documenta-los explicitamente evita que equipes tenham que fazer engenharia reversa dos padroes a partir do codigo.

Event Sourcing

Em sistemas event-sourced, o estado de uma entidade e derivado de uma sequencia de eventos em vez de armazenado como um snapshot. O event stream e a fonte de verdade, e o estado atual e uma projecao.

Documente event sourcing:

Identificando quais entidades sao event-sourced
Listando os tipos de evento no event stream de cada entidade
Documentando as projecoes que derivam read models dos streams
Anotando a estrategia de snapshotting (se houver)

CQRS (Command Query Responsibility Segregation)

CQRS separa operacoes de escrita (commands) de operacoes de leitura (queries), frequentemente usando eventos para manter o read model sincronizado com o write model.

Documente CQRS:

Separando claramente containers do command-side dos containers do query-side no modelo C4
Documentando o fluxo de eventos do write side para o read side
Anotando o modelo de consistencia (quao atrasado o read model pode ficar)

Coreografia vs. Orquestracao

Na coreografia, servicos reagem a eventos independentemente. Nenhum coordenador central existe. Na orquestracao, um servico central (o orquestrador ou saga) coordena o workflow enviando commands e ouvindo respostas.

Documente qual padrao seu sistema usa para cada workflow. Se voce usa coreografia, documente a sequencia esperada de eventos e os servicos que participam. Se voce usa orquestracao, documente a maquina de estados da saga e os commands que ela emite.

Dead Letter Queues e Padroes de Retry

Documente sua estrategia de tratamento de erros para processamento de eventos:

Quais eventos tem dead letter queues?
Qual e a politica de retry (quantidade, estrategia de backoff)?
Quem e responsavel por monitorar e reprocessar eventos da DLQ?
Qual alerta esta configurado para acumulacao na DLQ?

No Archyl, voce pode modelar DLQs como event channels adicionais vinculados aos channels primarios. Isso torna a infraestrutura de tratamento de erros visivel na documentacao de arquitetura.

Documentando Schemas de Eventos

Schemas de eventos sao contratos entre produtores e consumidores. Eles merecem o mesmo nivel de documentacao que contratos de API em sistemas sincronos.

Documentacao de Schema

Para cada tipo de evento, documente:

Nome do evento: Um nome claro e especifico do dominio (OrderCreated, nao GenericEvent)
Versao do schema: A versao atual do schema
Campos: Todos os campos com seus tipos, descricoes e se sao obrigatorios ou opcionais
Payload de exemplo: Um exemplo representativo em JSON/Avro/Protobuf
Compatibilidade: Se o schema e forward-compatible, backward-compatible ou totalmente compativel

O recurso de API Contract do Archyl pode ser usado para documentar schemas de eventos junto com especificacoes REST e gRPC. Vincule o contrato ao event channel para criar uma conexao direta entre o schema e a infraestrutura.

Estrategia de Evolucao de Schema

Documente a abordagem da sua equipe para evolucao de schema:

Voce usa um schema registry (Confluent Schema Registry, AWS Glue)?
Qual modo de compatibilidade e aplicado (backward, forward, full)?
Como breaking changes sao comunicadas aos consumidores?
Qual e o processo de deprecacao para versoes antigas de schema?

Essa informacao pertence a um ADR vinculado a sua infraestrutura de eventos. E uma decisao que afeta todo o sistema e deve ser documentada uma vez, claramente, e referenciada por todas as equipes.

Visualizando Fluxos de Eventos

Diagramas estaticos podem mostrar infraestrutura de eventos, mas tem dificuldade em mostrar fluxos de eventos -- a sequencia de eventos que implementa um processo de negocio.

Use Flows para Processos de Negocio

O recurso de Flow do Archyl permite documentar a sequencia de eventos que implementa um processo de negocio. Por exemplo, um flow de "Realizacao de Pedido" pode mostrar:

Cliente submete pedido via Web App
API Gateway encaminha requisicao para o Order Service
Order Service valida e persiste o pedido
Order Service publica evento OrderCreated para o Kafka
Inventory Service consome OrderCreated, reserva estoque
Inventory Service publica evento InventoryReserved
Payment Service consome InventoryReserved, processa pagamento
Payment Service publica evento PaymentProcessed
Notification Service consome PaymentProcessed, envia email de confirmacao

Esse flow mostra o comportamento end-to-end que emerge da arquitetura event-driven. Nenhum codigo de um unico servico revela esse flow -- ele so existe no nivel de arquitetura.

Use Overlays para Diferentes Visoes

Crie overlays para mostrar diferentes aspectos da sua arquitetura event-driven:

Overlay de Fluxo de Eventos: Destaca apenas os relationships relacionados a eventos, escondendo comunicacao sincrona
Overlay de Produtor/Consumidor: Colore servicos baseado em se produzem, consomem ou ambos
Overlay de Tratamento de Erros: Mostra DLQs, caminhos de retry e monitoramento

Overlays permitem criar visoes focadas a partir de um unico modelo de arquitetura, evitando a necessidade de multiplos diagramas redundantes.

Melhores Praticas

Nomeie Eventos com Acoes do Dominio, Nao Operacoes Tecnicas

Use nomes como OrderCreated, PaymentFailed, InventoryReserved -- nao DataUpdated, MessageSent ou RecordInserted. Nomes especificos do dominio tornam os fluxos de eventos legiveis no nivel de arquitetura.

Documente a Decisao "Por Que Nao Sincrono"

Para cada interacao event-driven, houve uma decisao de usar comunicacao async em vez de sync. Documente essa decisao. Por que o Order Service publica um evento em vez de chamar o Inventory Service diretamente? A resposta (desacoplamento, resiliencia, escalabilidade) deve ser capturada em um ADR.

Mantenha a Documentacao de Event Channel Proxima ao Codigo

Se seus schemas de eventos sao definidos em codigo (arquivos Protobuf, schemas Avro, JSON Schema), vincule a documentacao de arquitetura a esses arquivos. Isso cria uma conexao entre a documentacao abstrata e a implementacao concreta.

Revise Fluxos de Eventos Durante Revisoes de Arquitetura

Durante revisoes de arquitetura trimestrais, percorra seus fluxos de eventos documentados. Pergunte:

Ha novos tipos de evento que nao estao documentados?
Ha tipos de evento documentados que nao sao mais usados?
Novos consumidores foram adicionados sem atualizar a documentacao?
Os schemas documentados ainda estao precisos?

A deteccao de drift do Archyl ajuda a responder essas perguntas automaticamente, mas revisao humana periodica captura coisas que verificacoes automatizadas nao pegam.

Conclusao

Documentacao de arquitetura event-driven requer esforco intencional para tornar o invisivel visivel. Eventos, por design, desacoplam produtores de consumidores. Essa e uma forca arquitetural mas um desafio de documentacao.

O modelo C4 fornece o framework: System Context para o panorama geral, diagramas de Container com o message broker como elemento de primeira classe, event channels para documentacao detalhada de topicos e filas, e diagramas de Component para event handlers e sagas complexos.

O Archyl fornece as ferramentas: event channels como entidades de primeira classe, flows para documentar processos de negocio event-driven, contratos de API para schemas de eventos, overlays para visoes focadas e deteccao de drift para capturar mudancas nao documentadas.

Documente sua arquitetura event-driven da mesma forma que voce a projeta: com intencao, estrutura e o entendimento de que o comportamento do sistema emerge das interacoes entre servicos, nao de qualquer servico isolado.

Comece com o Archyl e torne sua arquitetura event-driven visivel, documentada e compreendida.

Documentacao de Arquitetura Event-Driven com Modelo C4 - Archyl Blog