DEV Community

Cover image for Modelo C4 na prática. Do contexto ao que acontece quando a resposta se perde
Sophie Pyxis
Sophie Pyxis

Posted on Fully Autonomous

Modelo C4 na prática. Do contexto ao que acontece quando a resposta se perde

Fotografia de estúdio com quatro lentes que revelam detalhes de um mecanismo de bronze. As ampliações representam os níveis de abstração do C4.

Parte 1 de 9 da série C4 e arquitetura de sistemas. Nesta série, vamos escolher o desenho que ajuda alguém a entender um sistema e decidir o que fazer com ele.

Você precisa decidir se pode trocar um fornecedor sem quebrar a abertura de contas. Qual desenho colocaria na frente de quem vai tomar a decisão?

Uma diretora pergunta se o banco pode trocar o fornecedor de verificação de identidade sem interromper a abertura de contas. Uma engenheira quer saber qual serviço guarda as evidências. A equipe de Operações pergunta o que fazer se o core aceitar uma abertura e a resposta se perder. As três perguntas são sobre o mesmo sistema. Cada uma pede um desenho diferente.

Parabéns a Simon Brown pela criação do modelo C4 e obrigada por compartilhá-lo com a comunidade de arquitetura de software. Gosto da forma como o modelo permite conversar primeiro sobre a fronteira do sistema e aproximar o olhar conforme a decisão exige. Ele oferece quatro níveis de abstração, sistemas, contêineres, componentes e código, e visões complementares, entre elas a dinâmica e a de implantação. Os exemplos deste capítulo usam Mermaid para representar essas ideias. Documentação oficial do modelo C4, por Simon Brown

Vou trabalhar com um banco fictício que quer reduzir de cinco dias úteis para um a abertura de contas elegíveis. O prazo começa no recebimento da solicitação completa e termina quando a conta fica disponível para uso. Os casos encaminhados para análise manual continuam acompanhados em separado. O desafio é acelerar a jornada com evidências de identidade e um status que o cliente possa usar para tomar decisões.

Um feixe vermelho que atravessa uma sequência de blocos azuis.

Pintura geométrica com um feixe vermelho que atravessa uma sequência de blocos azuis. A trajetória representa interações entre elementos do sistema.

Contexto. Quem depende de quem?

Eu começaria delimitando o Sistema de Abertura de Contas. A pessoa solicitante envia os dados e acompanha o pedido. Uma revisora trata os casos encaminhados. O provedor de identidade devolve o resultado da verificação. O core bancário confirma a ativação. O core está fora da fronteira deste sistema porque outra equipe responde por ele, embora ambos pertençam ao banco. Essa distinção muda quem negocia a interface e quem atua diante de uma falha.

Diagrama de contexto C4. Observe as pessoas e os sistemas externos à fronteira da abertura.

Figura 1. Diagrama de contexto C4. Observe as pessoas e os sistemas externos à fronteira da abertura.

Eu usaria essa visão na conversa com Produto, Risco e as áreas responsáveis pelas integrações. Trocar o provedor significa decidir quais evidências o banco continuará aceitando e como tratará solicitações que começaram com o fornecedor atual. A diretora consegue ver a dependência, nomear quem precisa participar e pedir uma visão dos contêineres afetados pela troca. Diagrama de contexto, modelo C4

Contêineres. Onde ficam os dados e as responsabilidades?

No C4, um contêiner representa uma aplicação ou um armazenamento de dados. Pode ser uma interface web, um serviço ou um esquema de banco. A visão revela as grandes escolhas técnicas e como esses elementos se comunicam. Eu escrevo uma responsabilidade curta em cada caixa e uso setas que descrevem a finalidade da interação. Diagrama de contêineres, modelo C4

No exemplo, a aplicação web recebe a solicitação. O portal interno permite analisar exceções. Ambos consultam o Serviço de Abertura por HTTPS. Esse serviço coordena verificações e decisões, grava a solicitação em PostgreSQL e armazena as evidências exigidas em um repositório protegido. O resultado da verificação fica associado ao caso por uma referência. O armazenamento tem regras próprias de acesso e retenção.

Diagrama de contêineres C4. Observe onde ficam a coordenação do caso, os dados e as integrações.

Figura 2. Diagrama de contêineres C4. Observe onde ficam a coordenação do caso, os dados e as integrações.

Se eu estivesse avaliando a troca do fornecedor, pediria à equipe que localizasse onde a resposta externa vira uma evidência reconhecida pelo banco. Neste desenho, essa tradução pertence ao Serviço de Abertura. A decisão de projeto seria preservar um formato interno com origem, identificador da verificação, resultado e momento da coleta. A equipe validaria se o fornecedor novo consegue preencher o formato e se a regra de elegibilidade distingue evidência válida, pendente ou inconclusiva. Uma mudança na exigência da evidência voltaria para decisão da área responsável pela política.

Se o serviço for grande o suficiente para justificar mais detalhe, eu acrescentaria uma visão de componentes para localizar a integração, a avaliação da evidência e a transição de estado. Um componente descreve uma parte interna de um contêiner. Uma vista de código pode ajudar quando alguém precisa discutir classes ou funções específicas. Para este capítulo, as dúvidas sobre a troca de fornecedor já têm responsáveis na visão de contêineres. Falta tratar o comportamento quando a operação recebe um resultado incerto. Conjunto de diagramas do modelo C4

Visão dinâmica. O que fazer quando a confirmação se perde?

Considere uma solicitação que passou pelas verificações. O Serviço de Abertura registra o início do processamento e envia ao core um identificador estável. O core aceita a instrução e ativa a conta. A conexão cai antes de o serviço receber a confirmação. Até recuperar o resultado, o serviço deve manter a solicitação como pendente. A aplicação web usa o mesmo caso para apresentar o status ao cliente.

Eu escolhi um diagrama de sequência em Mermaid para mostrar a ordem das interações entre elementos que já aparecem na visão de contêineres. A recuperação assume que o core oferece consulta pelo mesmo identificador. Eu validaria essa capacidade em homologação antes de aprovar o desenho. Diagrama dinâmico, modelo C4

Diagrama de sequência. Observe como a consulta ao core recupera o resultado após a perda da resposta.

Figura 3. Diagrama de sequência. Observe como a consulta ao core recupera o resultado após a perda da resposta.

Eu transformaria essa sequência em um teste de aceite. Primeiro, faria o core persistir a ativação antes de simular a perda da resposta. Depois, verificaria se a interface permanece pendente, se a consulta recupera a mesma conta e se a equipe consegue reconstruir os eventos a partir do identificador original. Se a consulta também expirar, o teste deve demonstrar que o caso gera uma exceção operacional após o limite acordado. Operações precisa de acesso ao identificador e ao procedimento de conciliação para atuar com segurança.

A troca do fornecedor como decisão de arquitetura

Para o piloto, eu avaliaria manter cada solicitação vinculada ao fornecedor que iniciou a verificação. As novas solicitações elegíveis poderiam usar o fornecedor novo, enquanto as verificações em andamento terminariam com o atual. Esse desenho exige capacidade de consultar ambos durante a transição. Também exige registrar, por amostra, se o resultado continua rastreável e se a nova integração altera a proporção de casos encaminhados à revisão manual.

Se a fila aumentar, Operações pode suspender a entrada no piloto e continuar acompanhando as solicitações já abertas. Antes de ampliar, Produto e Risco analisam a distribuição do tempo de abertura e a qualidade das evidências recuperadas.

Leve cada vista à conversa certa

Na decisão sobre o fornecedor, eu levaria o contexto e os contêineres. Na revisão de recuperação, levaria a sequência e os testes. Se a dúvida fosse se duas instâncias podem cair juntas, acrescentaria uma visão de implantação de produção com zonas e dependências compartilhadas. Ao revisar os desenhos, manteria nomes, fronteiras e responsabilidades consistentes entre as vistas. Diagrama de implantação · Checklist de revisão de diagramas C4

As três perguntas do início agora têm respostas que a equipe pode verificar. A substituição passa pela integração do Serviço de Abertura e pela validação das evidências aceitas. O repositório protegido guarda essas evidências. Uma resposta perdida deixa o caso pendente até que o core confirme a conta ativa. Eu manteria os diagramas junto às decisões e aos testes correspondentes, para que o próximo time consiga saber o que mudou e qual compromisso precisa preservar.

Aprofunde o componente em que o banco toma a decisão

Gosto de fazer uma pergunta antes de abrir uma caixa em um diagrama. O que alguém vai conseguir decidir depois de olhar o desenho? Para este banco, eu detalharia o Serviço de Abertura porque é ali que a resposta do fornecedor precisa se transformar em informação compreensível pelo restante da jornada. O desenho precisa mostrar onde acaba a interpretação do formato do provedor e onde começa a aplicação da política do banco. Esses pontos mudam quando substituímos o fornecedor e quando a área de controle aprova outra regra de elegibilidade.

Eu imaginaria quatro componentes no contêiner. A API recebe comandos e consultas. O avaliador coordena a verificação e a regra. Os adaptadores traduzem as respostas dos fornecedores para o vocabulário local. O repositório do caso mantém o estado, a versão da decisão e as referências às evidências. A divisão serve para localizar responsabilidades de software e pode caber em uma aplicação. Uma equipe pode implementar os componentes como módulos do mesmo processo e validar se as dependências do código seguem o desenho. Diagrama de componentes no modelo C4

Diagrama de componentes C4. Observe onde acabam as responsabilidades do adaptador e começa a avaliação.

Figura 4. Diagrama de componentes C4. Observe onde acabam as responsabilidades do adaptador e começa a avaliação.

Eu escolheria um vocabulário interno pequeno, com um estado que preserve dúvida. O exemplo seguinte mostra como o domínio recebe uma decisão do provedor anterior e interpreta o retorno de um provedor novo. Os campos são fictícios e o tratamento em produção depende do contrato real. A função que recebe os dados evita registrar documentos originais e carrega uma referência opaca para a evidência. Se o provedor enviar um valor diferente dos que testamos, a aplicação registra um caso inconclusivo para revisão. Um identificador em branco também impede que o resultado seja usado para aprovar automaticamente a solicitação.

from dataclasses import dataclass
from enum import Enum
from typing import Mapping


class Resultado(str, Enum):
    VERIFICADO = "verificado"
    PENDENTE = "pendente"
    INCONCLUSIVO = "inconclusivo"


@dataclass(frozen=True)
class Evidencia:
    fornecedor: str
    referencia: str | None
    resultado: Resultado


def traduzir(fornecedor: str, dados: Mapping[str, str]) -> Evidencia:
    if fornecedor == "atual":
        referencia = dados.get("verification_id")
        resultado = {
            "pass": Resultado.VERIFICADO,
            "progress": Resultado.PENDENTE,
        }.get(dados.get("state"), Resultado.INCONCLUSIVO)
    elif fornecedor == "novo":
        referencia = dados.get("reference")
        resultado = {
            "approved": Resultado.VERIFICADO,
            "processing": Resultado.PENDENTE,
        }.get(dados.get("outcome"), Resultado.INCONCLUSIVO)
    else:
        raise ValueError("Fornecedor fora da configuração da jornada")
    if not referencia or not referencia.strip():
        return Evidencia(fornecedor, None, Resultado.INCONCLUSIVO)
    return Evidencia(fornecedor, referencia, resultado)


assert traduzir("atual", {"verification_id": "v-1", "state": "pass"}).resultado == Resultado.VERIFICADO
assert traduzir("novo", {"reference": "v-2", "outcome": "processing"}).resultado == Resultado.PENDENTE
assert traduzir("novo", {"outcome": "approved"}).resultado == Resultado.INCONCLUSIVO
Enter fullscreen mode Exit fullscreen mode

Para avançar, eu pediria mais duas decisões. A primeira é quem assume a ocorrência quando o tradutor encontra um valor desconhecido. A segunda é em quais condições o banco pode reavaliar a evidência enviada pela rota anterior. O caso em andamento preserva o fornecedor, a referência e a versão de decisão usadas naquele momento. Esse conjunto também ajuda a investigar um aumento nos encaminhamentos manuais depois da troca. Se o novo fornecedor devolve mais estados inconclusivos, posso dimensionar a fila adicional sem revisitar a regra de todo o banco.

Um pulso luminoso no ponto da falha.

Fotografia macro de uma trilha de cobre interrompida sobre cerâmica, com um pulso luminoso no ponto da falha. A interrupção representa a perda da confirmação durante a abertura.

Use a vista de implantação para examinar a perda de uma dependência

Eu levaria o mesmo nome de contêiner à vista de produção, identificando as instâncias e os recursos que elas compartilham. Imagine duas instâncias do Serviço de Abertura em zonas distintas. Ambas usam o mesmo meio de acesso ao core, que pode interromper a ativação em qualquer uma das zonas. Mostrar a dependência torna mais útil a pergunta sobre resiliência. Posso medir o que continua funcionando quando perco uma zona e o que fica pendente quando perco o acesso compartilhado. O ambiente de homologação merece uma vista própria se a topologia tiver diferenças relevantes. Diagrama de implantação no C4

Diagrama de implantação C4. Observe as zonas distintas e a dependência compartilhada de acesso ao core.

Figura 5. Diagrama de implantação C4. Observe as zonas distintas e a dependência compartilhada de acesso ao core.

Eu faria um ensaio em que a zona A fica indisponível. A expectativa é que a instância restante continue aceitando as consultas previstas e que o banco saiba a capacidade disponível. Em outro ensaio, deixaria as duas instâncias no ar e interromperia o acesso ao core. Nesse cenário, a interface pode continuar apresentando o estado pendente, enquanto o serviço conserva as instruções registradas e aciona o procedimento de recuperação. Uma medida do tempo de resposta da aplicação web sozinha deixaria de mostrar que a ativação está atrasada.

Escolheria um pequeno cenário de dimensionamento antes do ensaio. Com 120 solicitações elegíveis por hora, 30 minutos de interrupção podem acumular cerca de 60 instruções. Se após a recuperação o sistema processa 180 por hora enquanto continuam chegando 120, a capacidade líquida para reduzir o estoque é de 60 por hora. É razoável preparar um teste com uma hora adicional para validar a hipótese. Alguns casos terão esforço de conciliação e precisam entrar na amostra. O cálculo serve de ponto de partida para uma discussão com quem controla a carga e com quem atende o cliente.

Registre a transição de estado que o cliente pode observar

Eu traduziria a sequência dinâmica em um contrato que possa orientar a API e seus testes. Quero mostrar explicitamente a diferença entre o core aceitar a instrução e a conta estar ativa. A aplicação web apresenta o mesmo estado de processamento para uma confirmação pendente e para um resultado que precisa ser conciliado. A distinção interna fica disponível a Operações, com os controles de acesso previstos. O exemplo abaixo usa Python e uma função pura para exercitar a regra sem depender de infraestrutura. O processamento real precisa persistir o estado de forma atômica e tratar concorrência e reentregas.

from enum import Enum


class Status(str, Enum):
    RECEBIDO = "recebido"
    PENDENTE = "pendente"
    ATIVO = "ativo"
    EXCECAO = "excecao"


def proximo_estado(atual: Status, evento: str) -> Status:
    if evento not in {"aceite_core", "timeout", "confirmacao_core", "encaminhar"}:
        raise ValueError("Evento fora do contrato")
    if atual is Status.ATIVO:
        return atual
    if evento == "confirmacao_core":
        return Status.ATIVO
    if evento == "encaminhar":
        return Status.EXCECAO
    if atual is Status.EXCECAO:
        return atual
    return Status.PENDENTE


assert proximo_estado(Status.RECEBIDO, "aceite_core") is Status.PENDENTE
assert proximo_estado(Status.PENDENTE, "timeout") is Status.PENDENTE
assert proximo_estado(Status.PENDENTE, "confirmacao_core") is Status.ATIVO
assert proximo_estado(Status.ATIVO, "timeout") is Status.ATIVO
assert proximo_estado(Status.EXCECAO, "aceite_core") is Status.EXCECAO
Enter fullscreen mode Exit fullscreen mode

Diagrama de estados. Observe a confirmação que permite ao serviço avançar para conta ativa.

Figura 6. Diagrama de estados. Observe a confirmação que permite ao serviço avançar para conta ativa.

A função recebe eventos já validados. Antes de chamar a regra, a aplicação confere a autorização da origem e a associação da confirmação à solicitação. O diagrama ajuda a discutir esse requisito com quem revisa o fluxo. O teste de aceitação deve incluir a confirmação recebida antes de um aceite intermediário atrasado. A aplicação precisa conservar o estado ativo quando lê a mensagem antiga. Em outro caso, o serviço recebe uma confirmação para uma solicitação diferente. A evidência dessa divergência deve ficar disponível ao papel que consegue corrigi-la.

Eu manteria a função local independente do formato de cada integração. A equipe pode trocar o código responsável pela tradução sem alterar a regra de status. Quando a regra precisar mudar, o desenho aponta os consumidores, a matriz de estados e os testes que precisam acompanhar a alteração. Essa conversa evita que um único campo da integração vire uma regra de negócio espalhada por várias telas.

Converta as vistas em consultas concretas de evidência

Para fechar o ciclo, eu combinaria com Operações como recuperar a confirmação e descobrir há quanto tempo um caso está pendente. Em um PostgreSQL hipotético, as tabelas locais de solicitação e de eventos podem guardar apenas o identificador, o tipo, a origem, a hora e a referência permitida. A consulta abaixo busca os casos pendentes há mais de 30 minutos sem confirmação do core. O prazo é um parâmetro de exercício. O banco decide o intervalo operacional baseado na janela que prometeu ao cliente, nas caudas de processamento observadas e nas regras de privacidade. Subconsultas EXISTS no PostgreSQL

SELECT
    c.solicitacao_id,
    c.status,
    c.status_desde
FROM solicitacao AS c
WHERE c.status IN ('pendente', 'excecao')
  AND c.status_desde < CURRENT_TIMESTAMP - INTERVAL '30 minutes'
  AND NOT EXISTS (
      SELECT 1
      FROM evento_ativacao AS e
      WHERE e.solicitacao_id = c.solicitacao_id
        AND e.origem = 'core'
        AND e.tipo = 'conta_ativa_confirmada'
  )
ORDER BY c.status_desde, c.solicitacao_id
LIMIT 100;
Enter fullscreen mode Exit fullscreen mode

Essa consulta tem um propósito específico. Ela encontra trabalho de conciliação, com recorte de idade e sem dados de identidade. Uma consulta separada pode detectar divergência entre o estado local e um evento de confirmação retido na trilha. O primeiro grupo precisa recuperar o que aconteceu com o core. O segundo já tem uma confirmação e precisa verificar a atualização do caso. Eu explicaria os dois caminhos no procedimento operacional para evitar que o time acione a integração externa quando a informação necessária já chegou.

Fluxograma de conciliação. Observe a diferença entre uma confirmação ausente e um estado local desatualizado.

Figura 7. Fluxograma de conciliação. Observe a diferença entre uma confirmação ausente e um estado local desatualizado.

Revise os desenhos com as pessoas que sentem a falha

Eu encerraria com três conversas curtas. Com Produto, revisaria como a promessa aparece em uma solicitação enviada perto do corte. Com Engenharia, pediria a distribuição de responsabilidades nos componentes e a evidência de que uma mensagem atrasada não muda o resultado correto. Com Operações, percorreria o monitoramento, a consulta e o procedimento de conciliação. A mesma jornada sustenta as três conversas. Cada pessoa vê o grau de detalhe necessário para assumir a sua decisão.

O desenho pode durar mais do que a implementação inicial se a equipe combinar quando revisá-lo. Eu usaria como gatilhos uma mudança de fornecedor, um novo caminho de consulta, a substituição da fonte de confirmação e uma alteração da topologia de produção. O revisor confere se a mudança aparece na vista apropriada, identifica o teste associado e registra os limites da evidência. Isso ajuda a manter a ligação entre decisão e software sem transformar toda alteração de código em um trabalho de documentação extensa.

Faça o ensaio da troca com dados que o banco consegue comparar

Eu montaria uma pequena matriz de decisão antes de mover uma solicitação para o fornecedor novo. Na linha de aprovação, o fornecedor responde com uma referência consultável e o banco consegue verificar a origem e o horário da evidência. Na linha de processamento pendente, a aplicação permite acompanhar o caso sem repetir a coleta. Na linha de resultado inconclusivo, o caso segue para a fila prevista e a operadora entende o motivo do encaminhamento. Um cenário adicional cobre a emissão de uma resposta válida para um identificador inesperado. A aplicação precisa registrar o problema no caso correto e restringir o avanço até que a associação seja esclarecida.

Para medir o piloto, eu selecionaria solicitações com os mesmos critérios de entrada e dividiria os resultados por fornecedor, janela de atendimento e tipo de evidência. Suponha que cada grupo tenha 200 solicitações elegíveis para teste e que o grupo novo produza 24 encaminhamentos à revisão, contra 12 no grupo atual. As taxas são 12% e 6%. A diferença é uma indicação para investigar, especialmente se os grupos tiveram horários ou tipos de documento diferentes. Eu levaria a composição da amostra, o tempo de espera e os motivos dos encaminhamentos para uma revisão com Risco e Operações. Isso ajuda a separar um efeito da integração de uma diferença entre as solicitações.

É possível que o fornecedor novo responda mais rápido e ainda aumente o trabalho manual. A composição do resultado pode mudar a decisão de expansão. Eu pediria que o time estimasse o volume adicional na janela em que a fila já recebe mais casos. Se o piloto prevê 400 solicitações por dia e a diferença de seis pontos percentuais se repetir, a operação pode receber cerca de 24 revisões adicionais por dia. Essa projeção precisa ser confrontada com o tempo de atendimento e a distribuição por turno. Antes de ampliar, o banco decide quais ajustes de escala, integração ou política cabem e quem poderá verificar seu efeito.

A decisão também precisa prever a retirada do fornecedor anterior. Para o caso fictício, eu verificaria quantas solicitações em andamento ainda dependem da consulta antiga e se existem referências disponíveis para investigar casos concluídos. A nova rota pode ser aprovada para mais clientes enquanto o banco conserva uma capacidade de consulta limitada para as solicitações anteriores. Produto e Operações precisam saber em que condição essa capacidade termina e o que o atendimento faz se alguém consultar uma solicitação depois da retirada.

Feche a revisão com um registro de decisão reproduzível

Eu registraria as duas opções de transição que o time avaliou, a evidência que levou à escolha e os critérios para reavaliá-la. A vista de contexto mostra as fronteiras e as áreas envolvidas. A de contêineres identifica a aplicação que mantém cada responsabilidade. A de componentes localiza a adaptação de respostas. A de implantação evidencia a dependência compartilhada que pode interromper a ativação. O cenário dinâmico e o diagrama de estados fornecem casos que podem ir direto para testes. Juntos, esses recortes dão à equipe uma forma de reconstruir a decisão quando uma condição real mudar.

Antes de encerrar a discussão, eu escolheria um caso perdido durante a troca e pediria que uma pessoa da operação o encontre com a referência disponível ao cliente. Depois pediria a alguém da engenharia que mostre a resposta recebida, o módulo que a interpretou e o teste correspondente. Se o caminho estiver claro nas duas conversas, o capítulo deixa de ser apenas uma descrição do sistema e passa a orientar uma mudança que alguém pode implementar e operar.

Veja o que acontece quando a mesma caixa muda de dono

Em um cenário hipotético de separação entre dois produtos, imagine que a equipe de abertura continue mantendo o portal, enquanto o adaptador do core passa a outra diretoria. Se eu redesenho as caixas sem atualizar a fronteira de suporte, a nova equipe pode receber o alerta e descobrir que o procedimento de recuperação exige acesso de quem saiu. A vista de containers me ajuda a localizar o adaptador. Ao lado dela, eu deixaria a pessoa ou o grupo que opera o componente e o caminho que o incidente seguirá no turno da noite.

A mesma mudança merece uma vista dinâmica breve. Peço que duas pessoas descrevam juntas a recuperação quando a resposta do core se perde. Se cada uma escolher uma fonte diferente para o estado final, trago o desacordo para o diagrama, com a consulta e o ponto em que a decisão precisa voltar à jornada. Assim a liderança pode avaliar a transferência com a responsabilidade de operação visível no mesmo cenário que motivou a mudança.

A preparação do texto e a criação das ilustrações tiveram apoio de IA generativa.

Top comments (0)