O que é o modelo C4

O modelo C4 é uma forma de desenhar a arquitetura de um software em vários níveis de detalhe. O site oficial o descreve como um jeito de criar “mapas do seu código”, aproximando e afastando a visão como num aplicativo de mapas. ^[1] O nome vem dos quatro diagramas principais: Contexto, Contêineres, Componentes e Código. ^[7]

Ele resolve um problema conhecido: o diagrama de “caixinhas e setas” que cada pessoa desenha de um jeito, sem dizer o que é cada caixa nem o que significa cada seta. O C4 define um pequeno vocabulário (pessoa, sistema, contêiner, componente) e uma hierarquia entre eles. Com isso, todos sabem em que nível de zoom estão olhando.

Este tutorial explica a teoria e depois a pratica no C4 Studio, um app em um único arquivo HTML. Com ele você desenha os diagramas, simula por onde passam as chamadas e o que cai quando algo falha, e gera a documentação. Nada é enviado para a rede: o projeto fica salvo no seu navegador.

Abrir o C4 Studio →

Uma breve história

O C4 foi criado pelo arquiteto de software Simon Brown, a partir do que ele via ao ensinar equipes a desenhar arquitetura. ^[5] A linha do tempo traz os marcos, com as datas das fontes consultadas.

• 1995. Philippe Kruchten publica o modelo “4+1”: quatro visões da arquitetura (lógica, de processo, de desenvolvimento e física) ilustradas por cenários, a “+1”. A ideia de olhar o mesmo sistema por perspectivas diferentes é uma das inspirações do C4. ^[9][5]
• 2006 a 2009. Surgem as raízes do modelo, inspiradas em UML e no 4+1. ^[5][8]
• 2010. Os tipos de diagrama ganham nome: contexto, contêineres, componentes e classes. ^[5]
• 2011. O nome “C4” aparece pela primeira vez, numa palestra na QCon London. O último C ainda era de “classes”. ^[6]
• 2015 a 2018. “Classes” vira “Código”. O FAQ do site dá 2015–2016, e a página de história diz que a troca só se completou em março de 2018. ^[5][6]
• 2018. Um artigo de Simon Brown na InfoQ, junto com o site oficial sob licença Creative Commons, ajuda a popularizar a técnica. ^[7][8]

Brown também escreveu o livro Software Architecture for Developers e fundou o Structurizr, ferramenta que gera vários diagramas a partir de um único modelo. ^[11][8] O site e os exemplos estão sob a licença Creative Commons Atribuição 4.0. ^[1]

A teoria: as abstrações

O C4 começa pelas abstrações, e não pelos desenhos. São cinco, e cada uma está dentro da anterior: um sistema tem contêineres, um contêiner tem componentes, um componente é feito de código. ^[2]

Contêiner não é Docker. O próprio site avisa: no C4, contêiner é uma aplicação ou um armazenamento de dados. ^[2] Um banco de dados é um contêiner mesmo que rode num servidor comum, e dois contêineres Docker da mesma aplicação continuam sendo um contêiner C4.

Mitos comuns

• “Preciso dos quatro níveis”

  Não. Contexto e contêineres bastam para a maioria dos times. Use os outros só quando agregarem valor. ^[3]

• “C4 é uma notação”

  É um conjunto de abstrações e diagramas. O site diz que ele é independente de notação: formas e cores ficam a seu critério, desde que haja legenda. ^[1][4]

• “C4 substitui UML”

  Ele nasceu inspirado em UML e convive com ela. Os diagramas dinâmico e de implantação, por exemplo, se baseiam nos de comunicação e de implantação da UML. ^[3]

• “Microsserviço é componente”

  Um microsserviço que roda e é implantado sozinho é um contêiner (ou um sistema, se tiver vários contêineres e outro time). Componente não se implanta separado. ^[2]

Os quatro níveis e os diagramas extras

Cada diagrama principal dá um zoom no elemento destacado do anterior. Para cada nível, o site informa o escopo, o público e se vale a pena fazer. ^[3]

O público muda com o zoom: o diagrama de contexto é para todos, inclusive quem não é técnico; o de contêineres é para a equipe técnica, a operação e o suporte; o de componentes, para arquitetos e desenvolvedores. ^[3]

As regras de notação

O C4 não impõe formas nem cores, mas pede que cada diagrama se explique sozinho. ^[4] A figura mostra o que cada elemento e cada relação devem trazer.

• Título com o tipo e o escopo do diagrama, como “Diagrama de contêineres do Sistema da Biblioteca”.
• Legenda que explique formas, cores, linhas e setas.
• Tipo explícito em cada elemento (Pessoa, Sistema de Software, Contêiner, Componente) e uma descrição curta das responsabilidades.
• Tecnologia em todo contêiner e componente.
• Relações num só sentido, cada uma com um rótulo coerente com a seta. Evite palavras soltas como “Usa”.
• Protocolo nas relações entre contêineres, que costumam ser comunicação entre processos.
• Siglas que todo o público entenda, ou explicadas na legenda. Cores, se usadas, com o mesmo significado em todos os diagramas.

O site transforma essas regras num checklist de perguntas de sim ou não, como “o diagrama tem título?” e “cada seta tem um rótulo que descreve a intenção da relação?”. ^[4] O C4 Studio ajuda em várias delas: a linha de tipo ([Contêiner: React]) aparece sozinha, a legenda se monta com os tipos usados, e a documentação gerada aponta elementos sem descrição e relações sem tecnologia.

Como modelar, passo a passo

Com as abstrações e as regras em mãos, o trabalho segue uma ordem simples, de fora para dentro:

1. Escolha o escopo. Um sistema de software, de preferência o que um time mantém. Se o assunto é a empresa inteira, comece pelo panorama.
2. Desenhe o contexto. Ponha o sistema no centro. Pergunte quem o usa (pessoas e papéis) e com quais sistemas ele troca dados, e em que sentido. Ignore tecnologia por enquanto.
3. Dê zoom nos contêineres. O que roda separado dentro do sistema? Cada aplicação, banco, fila e tarefa agendada vira um contêiner, com tecnologia. Cada seta ganha protocolo. Repita as pessoas e os sistemas externos do contexto que se ligam a esses contêineres.
4. Vá aos componentes só onde precisar. Um contêiner complexo ou crítico pode merecer um diagrama de componentes. Para documentação de longa duração, gere esse nível a partir do código, se puder. ^[3]
5. Pule o código, em geral. A IDE mostra as classes quando alguém precisa delas.
6. Acrescente os diagramas extras que responderem a uma pergunta real: “onde isso roda?” (implantação), “o que acontece quando o cliente compra?” (dinâmico), “quais sistemas a empresa tem?” (panorama).
7. Revise com o checklist e mantenha os nomes iguais em todos os diagramas. O mesmo elemento deve ter o mesmo nome no contexto e nos contêineres.

A tela do app

Na primeira vez, o C4 Studio abre o exemplo Loja Online, com sete diagramas: panorama, contexto, contêineres, componentes, código, dinâmico e implantação. Vale passear pelas abas antes de desenhar. Para voltar a ele depois, use Arquivo → Carregar exemplo.

Barra do alto

Uma aba por diagrama, com o nível antes do título, e + para criar outro. À direita: desfazer e refazer, ▶ Simular, Documentar, Arquivo ▾ e Exportar ▾.

Paleta (Elementos)

Clique num item para criá-lo no centro da tela, ou arraste-o até o ponto desejado. Embaixo há um resumo dos atalhos.

Área de desenho

Arraste o fundo para mover a vista e use a roda do mouse para o zoom. No canto, −, a porcentagem (volta a 100%), + e Ajustar, que enquadra o diagrama.

Painel à direita

Muda conforme a seleção: Diagrama (nada selecionado), Elemento, Fronteira, Relação, vários elementos selecionados ou Simulação.

Elementos da paleta

Cada item corresponde a uma abstração do C4 e a uma macro do C4-PlantUML, usada na exportação. ^[10]

O campo Nível C4 de cada diagrama aceita Panorama do Sistema, Contexto do Sistema, Contêineres, Componentes, Código, Dinâmico, Implantação e Outro. O app não impede misturar níveis: quem garante a coerência é você.

Seu primeiro diagrama de contexto

Vamos modelar o sistema de uma biblioteca municipal. Leitores pesquisam e reservam livros, bibliotecários registram empréstimos, e o sistema manda avisos por e-mail. Faça cada passo no app:

1. Abra o C4 Studio e escolha Arquivo → Novo projeto. Confirme. (Dá para desfazer com Ctrl+Z.)
2. Com nada selecionado, o painel mostra Diagrama. Em Título, escreva Biblioteca Municipal. Deixe o Nível C4 em Contexto do Sistema, escreva uma Descrição e marque Mostrar legenda.
3. Clique em Pessoa na paleta. O elemento surge no centro, com o nome já selecionado: escreva Leitor. Em Descrição, escreva Pessoa que pesquisa, reserva e empresta livros. Arraste-o para o alto, à esquerda.
4. Crie outra Pessoa, Bibliotecário (Funcionário que cadastra livros e registra empréstimos.), e arraste-a para o alto, à direita.
5. Crie um Sistema de software, Sistema da Biblioteca (Catálogo, reservas, empréstimos e devoluções.), no centro, e um Sistema externo, Serviço de E-mail (Envia e-mails transacionais.), embaixo.
6. Para ligar, clique no Leitor. Aparece um círculo laranja à direita dele: arraste esse círculo até o Sistema da Biblioteca e solte quando o destino ficar com contorno verde.
7. A relação nasce com o rótulo Usa já selecionado. Troque por Pesquisa e reserva livros e, em Tecnologia / protocolo, escreva HTTPS.
8. Faça o mesmo do Bibliotecário para o sistema (Registra empréstimos e devoluções, HTTPS) e do sistema para o e-mail (Envia avisos de devolução, SMTP).
9. Clique no fundo e depois em Ajustar.

Repare no que o app fez por você: a linha [Pessoa] ou [Sistema de Software] em cada caixa, as setas tracejadas (estilo padrão do C4 no app) e a legenda só com os tipos usados. Com duplo clique num elemento, o cursor vai direto para o nome.

Descer para os contêineres

Agora o zoom no Sistema da Biblioteca: o que roda dentro dele?

1. Clique no + ao lado das abas. O diagrama novo já vem com o nível seguinte, Contêineres. Dê o título Biblioteca — Contêineres e marque Mostrar legenda.
2. Volte à aba do contexto, selecione o Leitor e clique em Copiar para outro diagrama. O navegador pergunta o número do diagrama de destino: confirme 1. Faça o mesmo com o Serviço de E-mail. A cópia leva nome e descrição, para que os dois diagramas usem os mesmos nomes.
3. Na aba de contêineres, crie uma Fronteira chamada Sistema da Biblioteca. Em diagramas de contêineres, o Tipo da fronteira já vem como Sistema de Software. Aumente a Largura para 800 e a Altura para 560. Para mover a fronteira, arraste a borda tracejada.
4. Dentro da fronteira, crie um App web / mobile, Site da Biblioteca (tecnologia React); um Contêiner, API (Java / Spring Boot); e um Banco de dados, Banco de Dados (PostgreSQL). Ponha o leitor acima da fronteira e o e-mail à direita, do lado de fora.
5. Ligue: Leitor → Site (Pesquisa e reserva livros, HTTPS), Site → API (Chama a API, JSON/HTTPS), API → Banco (Lê e grava, SQL/TCP) e API → E-mail (Envia avisos de devolução, SMTP).
6. Clique no fundo e em Ajustar. O painel deve mostrar 5 elementos · 4 relações: a fronteira não conta como elemento.

Quando você move uma fronteira, tudo que está inteiramente dentro dela vai junto. Por isso, posicione a fronteira antes de pôr os contêineres dentro. Se um elemento ficar escondido atrás de outro, use os botões de Sobreposição do painel ou Ctrl+] e Ctrl+[.

Organizar o diagrama

Diagramas bagunçados são difíceis de ler. Selecione vários elementos com Shift+clique, ou com Shift arrastando no fundo para desenhar um retângulo de seleção. O painel passa a mostrar as ferramentas de arrumação.

• Alinhar: pelas bordas ou pelo centro, na horizontal e na vertical.
• Distribuir: espaços iguais entre três ou mais elementos.
• Espaçamento: enfileira os elementos com a distância que você escolher, em pixels.
• Dimensionamento: copia a largura, a altura ou o tamanho da referência, o último elemento clicado (contorno mais forte), ou aplica um tamanho digitado.
• Ajustar altura ao texto, Encaixar na grade e Remover sobreposições, que afasta elementos encavalados.

Atalhos

Simular fluxos e falhas

Um diagrama C4 é estático. O C4 Studio acrescenta uma leitura dinâmica das relações: clique em ▶ Simular. Uma faixa verde avisa que o diagrama não é alterado, e a paleta fica desativada. Esc ou Sair da simulação voltam à edição.

Fluxo de chamadas

Na aba Fluxo de chamadas, clique num elemento. O app segue as setas a partir dele, em ondas: o passo 1 são os destinos diretos, o passo 2 os destinos desses, e assim por diante. Relações bidirecionais valem nos dois sentidos. O painel lista cada passo com o rótulo e o protocolo e conta quem foi alcançado. A Velocidade controla a animação, e Repetir roda de novo.

No diagrama de contêineres da biblioteca, a partir do Leitor, o resultado foi: 5 alcançados, 0 fora do caminho, 3 passos.

Elementos fora do caminho merecem atenção: ou não participam daquela jornada, o que é normal, ou falta uma relação no diagrama.

Falhas

Na aba Falhas, cada clique tira um elemento do ar (clique de novo para restaurar). A regra de leitura é: uma relação A → B significa “A depende de B”. Se B cai, A fica indisponível, e a falha se propaga para quem depende de A. Três ajustes mudam o resultado:

• Regra de propagação. Com redundância (padrão): dependências do mesmo tipo e da mesma tecnologia contam como cópias uma da outra, e a origem só cai se todas caírem. Sem redundância: qualquer dependência fora do ar derruba quem depende dela.
• Não bloqueante. Marcada no painel da relação, faz a falha do destino apenas degradar a origem, sem derrubá-la. Serve para chamadas assíncronas ou opcionais.
• Encontrar pontos únicos de falha. Testa cada elemento sozinho, com a regra com redundância, e lista os que derrubam outros, do pior para o menor. Clicar num item da lista simula aquela falha.

Um experimento

No diagrama de contêineres da biblioteca, os pontos únicos de falha listados foram: Serviço de E-mail e Banco de Dados (cada um derruba 3), API (derruba 2) e Site da Biblioteca (derruba 1). Depois, a relação API → Serviço de E-mail foi marcada como não bloqueante, já que um aviso pode esperar. Os contadores do painel, nas três situações:

O elemento que cai entra na conta dos indisponíveis. Com a relação não bloqueante, só o e-mail fica indisponível, e API, site e leitor passam a degradados. Isso não mede disponibilidade real: é uma leitura das dependências que você desenhou. Se uma seta falta ou está no sentido errado, a simulação erra junto. Use-a para fazer perguntas ao time, como “o que acontece mesmo com o site se o servidor de e-mail cair?”.

No exemplo Loja Online, aba de contêineres, o pior ponto único de falha apontado é a Fila de Pedidos, que derruba 6 elementos.

Documentar, exportar e salvar

Documentar

O botão Documentar monta um documento de arquitetura a partir do diagrama atual ou de todos os diagramas do projeto. Para cada diagrama, ele traz nível, descrição, as Notas para a documentação do painel Diagrama, a imagem, a estrutura de fronteiras e tabelas de elementos, de relações e de dependências por elemento. No fim vêm os pontos de atenção, gerados automaticamente: pontos únicos de falha, elementos sem descrição, relações sem tecnologia e elementos sem nenhuma relação.

Você pode copiar o Markdown, baixar em .md ou HTML, ou imprimir e salvar em PDF. Desmarque Incluir imagens quando for colar o Markdown numa ferramenta de IA: as imagens entram como texto codificado e ocupam muito espaço.

Exportar

• Imagem SVG e Imagem PNG (em resolução dobrada), com título e descrição embaixo do desenho.
• Código C4-PlantUML, para versionar o diagrama como texto. As posições não vão junto: o PlantUML refaz o desenho. O código inclui a biblioteca C4-PlantUML por um endereço do GitHub, então quem renderiza precisa de acesso à internet. ^[10]

Salvar, abrir e importar

• Salvar projeto (.json) baixa todos os diagramas num arquivo .c4.json.
• Abrir projeto (.json)… troca o projeto atual pelo do arquivo. Dá para desfazer.
• Importar diagramas em novas abas (.json)… acrescenta diagramas sem mexer nos atuais. Uma janela deixa escolher quais entram e renomeá-los. Arrastar um .json para a área de desenho faz o mesmo. É o caminho para juntar o trabalho de colegas ou trazer diagramas gerados por IA.

O app não tem campo para o nome do projeto, usado no título da documentação e no nome do arquivo. Um projeto novo se chama “Projeto”. Para mudar, edite o campo "name" no .json salvo e abra-o de novo.

Prompts de IA

Uma IA ajuda a sair da página em branco, a extrair elementos de documentação espalhada e a revisar um diagrama contra as regras do C4. Ela também erra com confiança: inventa sistemas, troca o sentido das setas e confunde contêiner com componente. Trate a saída como rascunho. Para escrever prompts melhores, veja o tutorial de prompts.

Antes de colar: diagramas de arquitetura revelam nomes de servidores, fornecedores e pontos fracos. Tire endereços, senhas e nomes internos, e siga a política da sua organização para uso de IA. O app não envia nada para a rede, mas o serviço de IA recebe o que você colar.

Troque os trechos entre colchetes e cole na ferramenta de IA que você usa.

1. Entrevistar para montar o contexto

Faz a IA perguntar em vez de supor. É o melhor começo quando o sistema está só na cabeça das pessoas.

Você é um arquiteto de software que usa o modelo C4 (c4model.com).
Quero desenhar o diagrama de contexto deste sistema: [descreva em poucas frases].

Antes de propor qualquer diagrama, me entreviste:
- Faça uma pergunta por vez e espere minha resposta.
- Descubra quem usa o sistema (pessoas e papéis) e para quê, com quais sistemas externos ele troca dados, em que sentido e por qual meio, e quem é dono de cada sistema externo.
- Pergunte também o que acontece quando cada sistema externo fica fora do ar.
- Não invente respostas. Se eu não souber, registre como pendência.

Ao final, entregue:
1. Tabela de elementos: nome, tipo C4 (Pessoa, Sistema de Software ou Sistema externo) e descrição de uma frase.
2. Tabela de relações: origem, destino, rótulo com verbo no sentido da seta, tecnologia ou protocolo.
3. Lista de pendências.

2. Extrair contêineres de material existente

Para README, wiki, docker-compose ou atas. Pede a origem de cada item, o que facilita conferir.

A partir do material abaixo, extraia os elementos de um diagrama de contêineres C4 do sistema [nome].

Regras:
- No C4, contêiner é uma aplicação ou um armazenamento de dados que roda separadamente. Não é o mesmo que contêiner Docker. Bibliotecas e módulos internos não são contêineres.
- Use só o que está no material. Para cada item, cite o trecho de origem.
- Marque como [SUPOSIÇÃO] tudo que você deduziu.

Entregue:
1. Pessoas e sistemas externos.
2. Contêineres: nome, tipo (aplicação web, API, banco de dados, fila, tarefa agendada...), tecnologia e responsabilidade em uma frase.
3. Relações: origem → destino, rótulo e protocolo.
4. Contradições e o que falta saber.

Material:
"""
[cole aqui, sem senhas, endereços internos ou dados pessoais]
"""

3. Gerar o JSON para o C4 Studio

Gera um arquivo que o app importa. Salve a resposta num arquivo de texto com a extensão .c4.json e use Arquivo → Importar diagramas em novas abas (.json)…, ou arraste o arquivo para a área de desenho. Depois arrume o desenho e rode a simulação de falhas. Mantenha "Sistema de Software" escrito assim: o app usa esse texto para exportar a fronteira como System_Boundary.

Gere um arquivo JSON para o C4 Studio com dois diagramas C4 deste sistema: um de contexto e um de contêineres.
Sistema: [descreva o sistema ou cole as tabelas dos prompts 1 e 2].

Responda só com o JSON, neste formato:
{
  "format": "c4studio",
  "version": 1,
  "name": "[nome do projeto]",
  "diagrams": [
    {
      "id": "d1", "title": "...", "level": "context",
      "desc": "...", "notes": "...", "legend": true,
      "nodes": [
        {"id": "n1", "type": "person", "name": "...", "tech": "", "desc": "...", "x": 0, "y": 0, "w": 200, "h": 190}
      ],
      "edges": [
        {"id": "r1", "from": "n1", "to": "n2", "label": "...", "tech": "...", "style": "dashed", "both": false, "soft": false}
      ]
    }
  ]
}

Regras:
- level: context ou container (outros valores aceitos: landscape, component, code, dynamic, deployment).
- type: person, person_ext, system, system_ext, container, database, queue, webapp, component, code ou boundary.
- Tamanhos (w × h): person 200×190; system e system_ext 240×150; container 240×150; database 240×160; queue 260×130; webapp 240×160; component 230×140.
- No diagrama de contêineres, envolva os contêineres do sistema com um nó "boundary" com "tech": "Sistema de Software" e coloque-o primeiro na lista de nós. Os contêineres ficam inteiramente dentro dele; pessoas e sistemas externos ficam fora.
- x e y em múltiplos de 10, com pelo menos 140 de folga entre elementos. Pessoas no alto; sistemas externos embaixo ou à direita.
- ids únicos em cada diagrama; from e to sempre apontam para nós do mesmo diagrama.
- Uma relação A → B significa "A depende de B" ou "A chama B". Rótulo específico, com verbo (evite "Usa"). Em contêineres, informe a tecnologia ou o protocolo em "tech".
- Todo contêiner tem "tech", e toda descrição é uma frase curta.
- "soft": true só quando a falha do destino não impede a origem de funcionar, como um envio assíncrono de e-mail.
- Em "notes", liste as suposições que você fez.

4. Revisar contra o checklist do C4

Cole o Markdown de Documentar → Copiar Markdown, sem imagens. A IA olha o sentido, que as verificações automáticas não enxergam.

Revise a documentação de arquitetura abaixo, gerada pelo C4 Studio, usando as regras de notação e o checklist do modelo C4.

Confira:
1. O título, o tipo e o escopo de cada diagrama estão claros?
2. Cada elemento tem nome, tipo, descrição e, se for contêiner ou componente, tecnologia?
3. Cada relação tem rótulo específico, coerente com o sentido da seta (sem "Usa" genérico), e protocolo quando liga processos diferentes?
4. O nível de detalhe combina com o tipo de diagrama? Por exemplo: classes num diagrama de contêineres.
5. Há elementos isolados, siglas sem explicação ou responsabilidades repetidas?
6. Os diagramas se contradizem, com nomes ou relações diferentes para a mesma coisa?

Para cada problema, informe: diagrama, elemento ou relação, problema, correção sugerida e gravidade (alta, média ou baixa). Separe certeza de suspeita. Não invente fatos sobre o sistema; se depender deles, pergunte.

Documentação:
"""
[cole o Markdown]
"""

5. Explicar a arquitetura para quem não é técnico

Bom para validar o diagrama de contexto com gestores e usuários.

Explique a arquitetura abaixo para [público, como: diretoria, atendimento, auditoria], sem jargão técnico.

Entregue:
- Em três frases: o que o sistema faz, quem usa e de quais outros sistemas depende.
- Uma lista "o que acontece quando...": para cada sistema externo e cada banco de dados, o efeito de ele ficar fora do ar.
- Um glossário curto para os termos que não puderem ser evitados.
- Cinco perguntas para eu confirmar com esse público se o desenho corresponde ao que ele conhece.

Use só o que está na documentação. Se algo estiver ambíguo, diga.

Documentação:
"""
[cole o Markdown, sem as imagens]
"""

6. Tratar os pontos únicos de falha

Leva o resultado da simulação para uma conversa sobre resiliência.

O C4 Studio analisou o diagrama de contêineres abaixo e apontou os pontos únicos de falha listados.
Na simulação, uma relação A → B significa "A depende de B". Dependências do mesmo tipo e tecnologia contam como redundantes, e relações marcadas como não bloqueantes só degradam a origem.

Pontos únicos de falha:
[cole a lista de Simular → Falhas → Encontrar pontos únicos de falha]

Diagrama:
"""
[cole o Markdown da documentação, sem as imagens]
"""

Para cada ponto único de falha, proponha até duas mitigações (redundância, fila, cache, modo degradado, tempo-limite com alternativa), com custo relativo (baixo, médio ou alto) e o que muda no diagrama: elementos novos, relações novas ou relações que passam a ser não bloqueantes.
Diga quais pontos você manteria como estão e por quê. Não presuma requisitos de disponibilidade que eu não informei: pergunte.

7. Registrar uma decisão de arquitetura

O texto resultante cabe no campo Notas para a documentação do diagrama e entra no documento gerado.

Escreva um registro de decisão de arquitetura (ADR) curto para esta decisão: [ex.: pôr uma fila entre a API e o envio de avisos].

Contexto do sistema: [cole a descrição do diagrama de contêineres ou o Markdown sem imagens].

Formato:
- Título
- Status: proposta
- Contexto: o problema e as restrições, em até cinco frases
- Decisão
- Consequências: positivas, negativas e riscos
- Alternativas consideradas, com o motivo da rejeição
- Impacto nos diagramas C4: elementos e relações que entram, saem ou mudam

No máximo 300 palavras. Marque com [CONFIRMAR] o que você supôs.

8. Descer aos componentes a partir do código

Para quando um contêiner merece o terceiro nível. Depois, peça ao prompt 3 o JSON com "level": "component".

Quero o diagrama de componentes C4 do contêiner [nome], feito em [tecnologia]. Abaixo estão a estrutura de pastas e os principais arquivos.

Lembre: no C4, componente é um agrupamento de funcionalidades relacionadas atrás de uma interface bem definida, dentro de um único contêiner, e não é implantado separadamente.

Entregue:
1. Componentes: nome, tecnologia, responsabilidade em uma frase e os arquivos ou pastas que o formam.
2. Relações entre componentes e com elementos de fora do contêiner (outros contêineres, bancos, sistemas externos): origem → destino, rótulo e protocolo quando houver.
3. Partes do código que não se encaixam em nenhum componente ou parecem pertencer a mais de um.

Prefira de 5 a 12 componentes. Não liste classes uma a uma.

Estrutura:
"""
[cole a árvore de pastas e trechos relevantes, sem segredos]
"""

O que foi testado nestes prompts

O formato do prompt 3 foi testado: um JSON escrito pelo Claude com essas regras, para uma clínica veterinária, foi importado pelo menu do app (2 diagramas, com 5 e 9 elementos), simulou falhas e exportou C4-PlantUML sem erros. Nesse teste, a folga entre elementos era de 100, e alguns rótulos de relação ficaram sobrepostos; por isso o prompt pede 140. Mesmo assim, conte com ajustes manuais no desenho. Os outros prompts não foram executados, e as respostas mudam a cada vez e de uma IA para outra.

Boas práticas e erros comuns

Revisão rápida

Tente responder antes de abrir.

Abrir o C4 Studio →

Referências

1. Simon Brown. The C4 model for visualising software architecture e Introduction. Fonte da analogia com mapas, da independência de notação e da licença Creative Commons Atribuição 4.0.
2. Simon Brown. Abstractions, com as páginas de software system, container, component e code.
3. Simon Brown. Diagrams, com as páginas de contexto, contêineres, componentes, código, panorama, dinâmico e implantação. Fonte de escopo, público e recomendação de cada diagrama.
4. Simon Brown. Notation e Review checklist.
5. Simon Brown. FAQ. Fonte da autoria, das raízes entre 2006 e 2009, dos nomes de 2010 e do nome “C4” em 2011. Dá a troca de “classes” por “code” em 2015–2016, o que diverge da página de história [6].
6. Simon Brown. History. Situa o primeiro uso do nome “C4” na QCon London de 2011 e a troca definitiva de “Classes” por “Code” numa palestra de março de 2018.
7. Simon Brown. The C4 Model for Software Architecture. InfoQ, 25 de junho de 2018.
8. Wikipédia. C4 model. Situa a criação entre 2006 e 2011, faixa mais larga que a do FAQ [5], e atribui a popularização ao site oficial e ao artigo de 2018.
9. Philippe Kruchten. Architectural Blueprints — The “4+1” View Model of Software Architecture. IEEE Software, 12(6), novembro de 1995, p. 42–50.
10. plantuml-stdlib. C4-PlantUML, sob licença MIT. Fonte das macros usadas na exportação.
11. Simon Brown. Software Architecture for Developers. Leanpub. A página do livro apresenta o autor como criador do modelo C4 e fundador do Structurizr.

What the C4 model is

The C4 model is a way to draw the architecture of a piece of software at several levels of detail. The official site describes it as a way to create “maps of your code”, zooming in and out as you would in a map app. ^[1] The name comes from the four core diagrams: Context, Containers, Components and Code. ^[7]

It solves a familiar problem: the “boxes and arrows” diagram that everyone draws differently, without saying what each box is or what each arrow means. C4 defines a small vocabulary (person, system, container, component) and a hierarchy between those terms. Everyone then knows which zoom level they are looking at.

This tutorial explains the theory and then puts it into practice in C4 Studio, an app in a single HTML file. With it you draw the diagrams, simulate where calls go and what breaks when something fails, and generate the documentation. Nothing is sent over the network: the project is saved in your browser.

Open C4 Studio →

A brief history

C4 was created by software architect Simon Brown, based on what he saw while teaching teams to draw architecture. ^[5] The timeline shows the milestones, with dates from the sources consulted.

• 1995. Philippe Kruchten publishes the “4+1” model: four views of the architecture (logical, process, development and physical) illustrated by scenarios, the “+1”. The idea of looking at the same system from different perspectives is one of C4’s inspirations. ^[9][5]
• 2006 to 2009. The roots of the model appear, inspired by UML and 4+1. ^[5][8]
• 2010. The diagram types get names: context, containers, components and classes. ^[5]
• 2011. The name “C4” appears for the first time, in a talk at QCon London. The last C still stood for “classes”. ^[6]
• 2015 to 2018. “Classes” becomes “Code”. The site’s FAQ says 2015–2016, and the history page says the switch was only completed in March 2018. ^[5][6]
• 2018. An article by Simon Brown on InfoQ, together with the official site under a Creative Commons licence, helps popularise the technique. ^[7][8]

Brown also wrote the book Software Architecture for Developers and founded Structurizr, a tool that produces several diagrams from a single model. ^[11][8] The site and its examples are licensed under Creative Commons Attribution 4.0. ^[1]

The theory: abstractions

C4 starts with abstractions, not drawings. There are five, each inside the previous one: a system has containers, a container has components, a component is made of code. ^[2]

A container is not Docker. The site itself warns: in C4, a container is an application or a data store. ^[2] A database is a container even when it runs on an ordinary server, and two Docker containers of the same application are still one C4 container.

Common myths

• “I need all four levels”

  No. Context and containers are enough for most teams. Use the others only when they add value. ^[3]

• “C4 is a notation”

  It is a set of abstractions and diagrams. The site says it is notation independent: shapes and colours are up to you, as long as there is a key. ^[1][4]

• “C4 replaces UML”

  It was inspired by UML and lives alongside it. The dynamic and deployment diagrams, for instance, are based on UML’s communication and deployment diagrams. ^[3]

• “A microservice is a component”

  A microservice that runs and is deployed on its own is a container (or a system, if it has several containers and another team). A component is not deployed separately. ^[2]

The four levels and the extra diagrams

Each core diagram zooms into the highlighted element of the previous one. For each level, the site gives the scope, the audience and whether it is worth drawing. ^[3]

The audience changes with the zoom: the context diagram is for everybody, including non-technical people; the container diagram is for the technical team, operations and support; the component diagram is for architects and developers. ^[3]

The notation rules

C4 does not impose shapes or colours, but it asks that every diagram explain itself. ^[4] The figure shows what each element and each relationship should carry.

• A title with the diagram’s type and scope, such as “Container diagram for the Library System”.
• A key/legend explaining shapes, colours, lines and arrows.
• An explicit type on every element (Person, Software System, Container, Component) and a short description of its responsibilities.
• A technology on every container and component.
• One-way relationships, each with a label that matches the arrow. Avoid single words such as “Uses”.
• A protocol on relationships between containers, which are usually inter-process communication.
• Acronyms the whole audience understands, or explained in the key. Colours, if used, mean the same in every diagram.

The site turns these rules into a checklist of yes-or-no questions, such as “does the diagram have a title?” and “does every arrow have a label describing the intent of that relationship?”. ^[4] C4 Studio helps with several of them: the type line ([Contêiner: React]) appears automatically, the key is built from the types used, and the generated documentation points out elements without a description and relationships without a technology.

How to model, step by step

With the abstractions and rules in hand, the work follows a simple order, from the outside in:

1. Pick the scope. One software system, ideally the one a team maintains. If the subject is the whole company, start with the landscape.
2. Draw the context. Put the system in the middle. Ask who uses it (people and roles) and which systems it exchanges data with, and in which direction. Ignore technology for now.
3. Zoom into containers. What runs separately inside the system? Each application, database, queue and scheduled job becomes a container, with a technology. Each arrow gets a protocol. Repeat the people and external systems from the context that connect to these containers.
4. Go to components only where needed. A complex or critical container may deserve a component diagram. For long-lived documentation, generate this level from the code if you can. ^[3]
5. Usually skip the code. The IDE shows the classes when someone needs them.
6. Add the extra diagrams that answer a real question: “where does this run?” (deployment), “what happens when the customer buys?” (dynamic), “which systems does the company have?” (landscape).
7. Review with the checklist and keep names consistent across diagrams. The same element should have the same name in the context and in the containers.

The app screen

The first time, C4 Studio opens the Loja Online (online shop) sample, with seven diagrams: landscape, context, containers, components, code, dynamic and deployment. It is worth browsing the tabs before drawing. To get back to it later, use Arquivo → Carregar exemplo (File → Load sample).

Top bar

One tab per diagram, with the level before the title, and + to create another. On the right: undo and redo, ▶ Simular (simulate), Documentar (document), Arquivo ▾ (file) and Exportar ▾ (export).

Palette (Elementos)

Click an item to create it in the middle of the screen, or drag it to the spot you want. Below it is a summary of the shortcuts.

Drawing area

Drag the background to move the view and use the mouse wheel to zoom. In the corner: −, the percentage (back to 100%), + and Ajustar (fit), which frames the diagram.

Right panel

Changes with the selection: Diagrama (nothing selected), Elemento, Fronteira (boundary), Relação (relationship), several selected elements or Simulação.

Palette elements

Each item corresponds to a C4 abstraction and to a C4-PlantUML macro, used in the export. ^[10]

Each diagram’s Nível C4 (C4 level) field accepts Panorama do Sistema (system landscape), Contexto do Sistema (system context), Contêineres, Componentes, Código, Dinâmico, Implantação (deployment) and Outro (other). The app does not stop you from mixing levels: keeping them coherent is up to you.

Button names

Your first context diagram

Let’s model a city library system. Readers search for and reserve books, librarians record loans, and the system sends notices by e-mail. Do each step in the app. The screenshots show the same example with Portuguese names.

1. Open C4 Studio and choose Arquivo → Novo projeto (File → New project). Confirm. (You can undo it with Ctrl+Z.)
2. With nothing selected, the panel shows Diagrama. In Título (title), type City Library. Leave Nível C4 on Contexto do Sistema (system context), write a Descrição (description) and tick Mostrar legenda (show key).
3. Click Pessoa (person) in the palette. The element appears in the middle with its name already selected: type Reader. In Descrição, type Person who searches for, reserves and borrows books. Drag it to the top left.
4. Create another Pessoa, Librarian (Employee who catalogues books and records loans.), and drag it to the top right.
5. Create a Sistema de software (software system), Library System (Catalogue, reservations, loans and returns.), in the middle, and a Sistema externo (external system), E-mail Service (Sends transactional e-mails.), at the bottom.
6. To connect, click Reader. An orange circle appears to its right: drag that circle onto Library System and release when the target gets a green outline.
7. The relationship is created with the label Usa (uses) already selected. Replace it with Searches for and reserves books and, in Tecnologia / protocolo, type HTTPS.
8. Do the same from Librarian to the system (Records loans and returns, HTTPS) and from the system to the e-mail service (Sends return reminders, SMTP).
9. Click the background, then Ajustar (fit).

Notice what the app did for you: the [Pessoa] or [Sistema de Software] line in each box, the dashed arrows (the app’s default C4 style) and a key showing only the types used. Double-clicking an element takes the cursor straight to its name.

Zooming into containers

Now the zoom into Library System: what runs inside it?

1. Click the + next to the tabs. The new diagram already comes with the next level, Contêineres (containers). Give it the title Library — Containers and tick Mostrar legenda.
2. Go back to the context tab, select Reader and click Copiar para outro diagrama (copy to another diagram). The browser asks for the number of the target diagram: confirm 1. Do the same with E-mail Service. The copy carries the name and description, so both diagrams use the same names.
3. On the containers tab, create a Fronteira (boundary) named Library System. In container diagrams, the Tipo da fronteira (boundary type) is already Sistema de Software. Increase Largura (width) to 800 and Altura (height) to 560. To move the boundary, drag its dashed border.
4. Inside the boundary, create an App web / mobile, Library Website (technology React); a Contêiner, API (Java / Spring Boot); and a Banco de dados (database), Database (PostgreSQL). Put the reader above the boundary and the e-mail service to the right, outside it.
5. Connect: Reader → Website (Searches for and reserves books, HTTPS), Website → API (Calls the API, JSON/HTTPS), API → Database (Reads and writes, SQL/TCP) and API → E-mail (Sends return reminders, SMTP).
6. Click the background and Ajustar. The panel should show 5 elementos · 4 relações (5 elements · 4 relationships): the boundary does not count as an element.

When you move a boundary, everything entirely inside it moves too. So position the boundary before placing the containers in it. If an element ends up hidden behind another, use the Sobreposição (stacking order) buttons in the panel or Ctrl+] and Ctrl+[.

Tidying the diagram

Messy diagrams are hard to read. Select several elements with Shift+click, or hold Shift and drag on the background to draw a selection rectangle. The panel then shows the layout tools.

• Alinhar (align): by edges or centre, horizontally and vertically.
• Distribuir (distribute): equal gaps between three or more elements.
• Espaçamento (spacing): lines the elements up with the distance you choose, in pixels.
• Dimensionamento (sizing): copies the width, height or size of the reference, the last element clicked (stronger outline), or applies a typed size.
• Ajustar altura ao texto (fit height to text), Encaixar na grade (snap to grid) and Remover sobreposições (remove overlaps), which pushes overlapping elements apart.

Shortcuts

Simulating flows and failures

A C4 diagram is static. C4 Studio adds a dynamic reading of the relationships: click ▶ Simular (simulate). A green banner says the diagram is not changed, and the palette is disabled. Esc or Sair da simulação (leave the simulation) go back to editing.

Call flow

On the Fluxo de chamadas (call flow) tab, click an element. The app follows the arrows from it in waves: step 1 is the direct targets, step 2 their targets, and so on. Bidirectional relationships work both ways. The panel lists each step with its label and protocol and counts what was reached. Velocidade (speed) controls the animation, and Repetir (replay) runs it again.

In the library container diagram, starting from the reader, the result was: 5 reached, 0 off the path, 3 steps.

Elements off the path deserve attention: either they take no part in that journey, which is normal, or a relationship is missing from the diagram.

Failures

On the Falhas (failures) tab, each click takes an element down (click again to restore it). The reading rule is: a relationship A → B means “A depends on B”. If B goes down, A becomes unavailable, and the failure spreads to whoever depends on A. Three settings change the result:

• Regra de propagação (propagation rule). Com redundância (with redundancy, the default): dependencies of the same type and technology count as copies of each other, and the source only goes down if all of them do. Sem redundância (without redundancy): any dependency that is down takes down whoever depends on it.
• Não bloqueante (non-blocking). Ticked in the relationship panel, it makes the target’s failure only degrade the source instead of taking it down. Use it for asynchronous or optional calls.
• Encontrar pontos únicos de falha (find single points of failure). Tests each element alone, with the redundancy rule, and lists those that take others down, worst first. Clicking an item in the list simulates that failure.

An experiment

In the library container diagram, the single points of failure listed were: the e-mail service and the database (each takes down 3), the API (takes down 2) and the website (takes down 1). Then the API → e-mail relationship was marked as non-blocking, since a notice can wait. The panel counters in the three situations:

The element that goes down counts as unavailable. With the non-blocking relationship, only the e-mail service is unavailable, and the API, website and reader become degraded. This does not measure real availability: it is a reading of the dependencies you drew. If an arrow is missing or points the wrong way, the simulation is wrong too. Use it to ask the team questions, such as “what really happens to the website if the mail server goes down?”.

In the Loja Online sample, on the container tab, the worst single point of failure reported is Fila de Pedidos (order queue), which takes down 6 elements.

Documenting, exporting and saving

Documentar (document)

The Documentar button builds an architecture document from the current diagram or from all diagrams in the project. For each diagram it includes the level, the description, the Notas para a documentação (notes for the documentation) from the Diagram panel, the image, the boundary structure and tables of elements, relationships and dependencies per element. At the end come the automatically generated pontos de atenção (points of attention): single points of failure, elements without a description, relationships without a technology and elements with no relationship at all. The document text is in Portuguese.

You can copy the Markdown, download it as .md or HTML, or print it and save as PDF. Untick Incluir imagens (include images) when you are going to paste the Markdown into an AI tool: the images go in as encoded text and take up a lot of space.

Exportar (export)

• Imagem SVG and Imagem PNG (at double resolution), with the title and description under the drawing.
• Código C4-PlantUML, to version the diagram as text. Positions are not exported: PlantUML lays the drawing out again. The code includes the C4-PlantUML library from a GitHub address, so whoever renders it needs internet access. ^[10]

Saving, opening and importing

• Salvar projeto (.json) (save project) downloads all the diagrams in a .c4.json file.
• Abrir projeto (.json)… (open project) replaces the current project with the one in the file. It can be undone.
• Importar diagramas em novas abas (.json)… (import diagrams into new tabs) adds diagrams without touching the current ones. A window lets you choose which ones come in and rename them. Dragging a .json onto the drawing area does the same. This is how you merge colleagues’ work or bring in AI-generated diagrams.

The app has no field for the project name, which is used in the documentation title and the file name. A new project is called “Projeto”. To change it, edit the "name" field in the saved .json and open it again.

AI prompts

An AI helps you get past the blank page, extract elements from scattered documentation and review a diagram against the C4 rules. It also makes mistakes with confidence: it invents systems, reverses arrows and confuses containers with components. Treat its output as a draft. To write better prompts, see the prompt tutorial.

Before pasting: architecture diagrams reveal server names, suppliers and weak spots. Remove addresses, passwords and internal names, and follow your organisation’s AI policy. The app sends nothing over the network, but the AI service receives whatever you paste.

Replace the parts in square brackets and paste into the AI tool you use. If your AI answers in English, the generated names will be in English too; the app accepts any language.

1. Interview to build the context

Makes the AI ask instead of assume. The best start when the system exists only in people’s heads.

You are a software architect who uses the C4 model (c4model.com).
I want to draw the context diagram of this system: [describe it in a few sentences].

Before proposing any diagram, interview me:
- Ask one question at a time and wait for my answer.
- Find out who uses the system (people and roles) and what for, which external systems it exchanges data with, in which direction and by what means, and who owns each external system.
- Also ask what happens when each external system is down.
- Do not make up answers. If I do not know, record it as an open item.

At the end, deliver:
1. Element table: name, C4 type (Person, Software System or External system) and a one-sentence description.
2. Relationship table: source, target, label with a verb matching the arrow, technology or protocol.
3. List of open items.

2. Extract containers from existing material

For a README, wiki, docker-compose file or meeting notes. It asks for the source of each item, which makes checking easier.

From the material below, extract the elements of a C4 container diagram for the system [name].

Rules:
- In C4, a container is an application or a data store that runs separately. It is not the same as a Docker container. Libraries and internal modules are not containers.
- Use only what is in the material. For each item, quote the source passage.
- Mark everything you inferred as [ASSUMPTION].

Deliver:
1. People and external systems.
2. Containers: name, kind (web application, API, database, queue, scheduled job...), technology and responsibility in one sentence.
3. Relationships: source → target, label and protocol.
4. Contradictions and what is still unknown.

Material:
"""
[paste here, without passwords, internal addresses or personal data]
"""

3. Generate the JSON for C4 Studio

Produces a file the app can import. Save the answer in a text file with the .c4.json extension and use Arquivo → Importar diagramas em novas abas (.json)…, or drag the file onto the drawing area. Then tidy up the drawing and run the failure simulation. Keep "Sistema de Software" written exactly like that, in Portuguese: the app uses that text to export the boundary as System_Boundary.

Generate a JSON file for C4 Studio with two C4 diagrams of this system: one context diagram and one container diagram.
System: [describe the system or paste the tables from prompts 1 and 2].

Reply only with the JSON, in this format:
{
  "format": "c4studio",
  "version": 1,
  "name": "[project name]",
  "diagrams": [
    {
      "id": "d1", "title": "...", "level": "context",
      "desc": "...", "notes": "...", "legend": true,
      "nodes": [
        {"id": "n1", "type": "person", "name": "...", "tech": "", "desc": "...", "x": 0, "y": 0, "w": 200, "h": 190}
      ],
      "edges": [
        {"id": "r1", "from": "n1", "to": "n2", "label": "...", "tech": "...", "style": "dashed", "both": false, "soft": false}
      ]
    }
  ]
}

Rules:
- level: context or container (other accepted values: landscape, component, code, dynamic, deployment).
- type: person, person_ext, system, system_ext, container, database, queue, webapp, component, code or boundary.
- Sizes (w × h): person 200×190; system and system_ext 240×150; container 240×150; database 240×160; queue 260×130; webapp 240×160; component 230×140.
- In the container diagram, wrap the system's containers in a "boundary" node with "tech": "Sistema de Software" and put it first in the node list. The containers sit entirely inside it; people and external systems stay outside.
- x and y in multiples of 10, with at least 140 of clearance between elements. People at the top; external systems at the bottom or on the right.
- Unique ids in each diagram; from and to always point to nodes in the same diagram.
- A relationship A → B means "A depends on B" or "A calls B". Specific label with a verb (avoid "Uses"). For containers, give the technology or protocol in "tech".
- Every container has a "tech", and every description is one short sentence.
- "soft": true only when the target's failure does not stop the source from working, such as sending an e-mail asynchronously.
- In "notes", list the assumptions you made.

4. Review against the C4 checklist

Paste the Markdown from Documentar → Copiar Markdown, without images. The AI looks at meaning, which the automatic checks cannot see.

Review the architecture documentation below, generated by C4 Studio, using the notation rules and the review checklist of the C4 model. The documentation may be in Portuguese; answer in English.

Check:
1. Are the title, type and scope of each diagram clear?
2. Does every element have a name, a type, a description and, if it is a container or component, a technology?
3. Does every relationship have a specific label that matches the arrow direction (no generic "Uses"), and a protocol when it links different processes?
4. Does the level of detail match the diagram type? For example: classes in a container diagram.
5. Are there isolated elements, unexplained acronyms or duplicated responsibilities?
6. Do the diagrams contradict each other, with different names or relationships for the same thing?

For each problem, give: diagram, element or relationship, problem, suggested fix and severity (high, medium or low). Separate certainty from suspicion. Do not invent facts about the system; if something depends on them, ask.

Documentation:
"""
[paste the Markdown]
"""

5. Explain the architecture to non-technical people

Good for validating the context diagram with managers and users.

Explain the architecture below to [audience, such as: the board, customer service, auditors], with no technical jargon.

Deliver:
- In three sentences: what the system does, who uses it and which other systems it depends on.
- A "what happens when..." list: for each external system and each database, the effect of it being down.
- A short glossary for the terms that cannot be avoided.
- Five questions for me to check with that audience whether the drawing matches what they know.

Use only what is in the documentation. If something is ambiguous, say so.

Documentation:
"""
[paste the Markdown, without the images]
"""

6. Deal with single points of failure

Takes the simulation result into a conversation about resilience.

C4 Studio analysed the container diagram below and reported the single points of failure listed.
In the simulation, a relationship A → B means "A depends on B". Dependencies of the same type and technology count as redundant, and relationships marked as non-blocking only degrade the source.

Single points of failure:
[paste the list from Simular → Falhas → Encontrar pontos únicos de falha]

Diagram:
"""
[paste the documentation Markdown, without the images]
"""

For each single point of failure, propose up to two mitigations (redundancy, queue, cache, degraded mode, timeout with fallback), with a relative cost (low, medium or high) and what changes in the diagram: new elements, new relationships or relationships that become non-blocking.
Say which points you would leave as they are and why. Do not assume availability requirements I have not given: ask.

7. Record an architecture decision

The resulting text fits in the diagram’s Notas para a documentação field and goes into the generated document.

Write a short architecture decision record (ADR) for this decision: [e.g.: put a queue between the API and the sending of notices].

System context: [paste the description of the container diagram or the Markdown without images].

Format:
- Title
- Status: proposed
- Context: the problem and the constraints, in up to five sentences
- Decision
- Consequences: positive, negative and risks
- Alternatives considered, with the reason each was rejected
- Impact on the C4 diagrams: elements and relationships that are added, removed or changed

At most 300 words. Mark what you assumed with [CONFIRM].

8. Go down to components from the code

For when a container deserves the third level. Afterwards, ask prompt 3 for the JSON with "level": "component".

I want the C4 component diagram of the container [name], written in [technology]. Below are the folder structure and the main files.

Remember: in C4, a component is a grouping of related functionality behind a well-defined interface, inside a single container, and it is not deployed separately.

Deliver:
1. Components: name, technology, responsibility in one sentence and the files or folders that make it up.
2. Relationships between components and with elements outside the container (other containers, databases, external systems): source → target, label and protocol where there is one.
3. Parts of the code that fit no component or seem to belong to more than one.

Prefer 5 to 12 components. Do not list classes one by one.

Structure:
"""
[paste the folder tree and relevant excerpts, without secrets]
"""

What was tested in these prompts

The prompt 3 format was tested: a JSON written by Claude under these rules, for a veterinary clinic, was imported through the app’s menu (2 diagrams, with 5 and 9 elements), simulated failures and exported C4-PlantUML without errors. In that test the clearance between elements was 100, and some relationship labels overlapped; that is why the prompt asks for 140. Even so, expect to adjust the drawing by hand. The other prompts were not run, and the answers change every time and from one AI to another.

Good practices and common mistakes

Quick review

Try to answer before opening.

Open C4 Studio →

References

1. Simon Brown. The C4 model for visualising software architecture and Introduction. Source of the maps analogy, notation independence and the Creative Commons Attribution 4.0 licence.
2. Simon Brown. Abstractions, with the pages on software system, container, component and code.
3. Simon Brown. Diagrams, with the pages on system context, container, component, code, system landscape, dynamic and deployment diagrams. Source of each diagram’s scope, audience and recommendation.
4. Simon Brown. Notation and Review checklist.
5. Simon Brown. FAQ. Source of the authorship, the roots in 2006–2009, the 2010 names and the “C4” name in 2011. It dates the switch from “classes” to “code” to 2015–2016, which differs from the history page [6].
6. Simon Brown. History. Places the first use of the “C4” name at QCon London 2011 and the final switch from “Classes” to “Code” in a talk in March 2018.
7. Simon Brown. The C4 Model for Software Architecture. InfoQ, June 25, 2018.
8. Wikipedia. C4 model. Dates the creation to 2006–2011, a wider range than the FAQ [5], and credits the official site and the 2018 article with popularising it.
9. Philippe Kruchten. Architectural Blueprints — The “4+1” View Model of Software Architecture. IEEE Software, 12(6), November 1995, pp. 42–50.
10. plantuml-stdlib. C4-PlantUML, under the MIT licence. Source of the macros used in the export.
11. Simon Brown. Software Architecture for Developers. Leanpub. The book page introduces the author as the creator of the C4 model and founder of Structurizr.

Che cos’è il modello C4

Il modello C4 è un modo di disegnare l’architettura di un software a più livelli di dettaglio. Il sito ufficiale lo descrive come un modo per creare “mappe del tuo codice”, ingrandendo e rimpicciolendo la vista come in un’app di mappe. ^[1] Il nome viene dai quattro diagrammi principali, in inglese: Context, Containers, Components e Code, cioè contesto, container, componenti e codice. ^[7]

Risolve un problema noto: il diagramma a “scatole e frecce” che ognuno disegna a modo suo, senza dire che cosa sia ogni scatola né che cosa significhi ogni freccia. Il C4 definisce un piccolo vocabolario (persona, sistema, container, componente) e una gerarchia tra questi termini. Così tutti sanno a quale livello di zoom stanno guardando.

Questo tutorial spiega la teoria e poi la mette in pratica nel C4 Studio, un’app in un unico file HTML. Con l’app disegni i diagrammi, simuli dove passano le chiamate e che cosa cade quando qualcosa si guasta, e generi la documentazione. Niente viene inviato in rete: il progetto resta salvato nel browser.

Apri il C4 Studio →

Una breve storia

Il C4 è stato creato dall’architetto software Simon Brown, a partire da ciò che vedeva insegnando ai team a disegnare l’architettura. ^[5] La cronologia riporta le tappe, con le date delle fonti consultate.

• 1995. Philippe Kruchten pubblica il modello “4+1”: quattro viste dell’architettura (logica, dei processi, di sviluppo e fisica) illustrate da scenari, il “+1”. L’idea di guardare lo stesso sistema da prospettive diverse è una delle ispirazioni del C4. ^[9][5]
• Dal 2006 al 2009. Nascono le radici del modello, ispirate a UML e al 4+1. ^[5][8]
• 2010. I tipi di diagramma ricevono un nome: contesto, container, componenti e classi. ^[5]
• 2011. Il nome “C4” compare per la prima volta, in un intervento alla QCon London. L’ultima C stava ancora per “classi”. ^[6]
• Dal 2015 al 2018. “Classi” diventa “Codice”. Le FAQ del sito indicano il 2015–2016, mentre la pagina sulla storia dice che il passaggio si è completato solo a marzo 2018. ^[5][6]
• 2018. Un articolo di Simon Brown su InfoQ, insieme al sito ufficiale con licenza Creative Commons, contribuisce a diffondere la tecnica. ^[7][8]

Brown ha scritto anche il libro Software Architecture for Developers e ha fondato Structurizr, uno strumento che produce più diagrammi da un unico modello. ^[11][8] Il sito e gli esempi sono rilasciati con licenza Creative Commons Attribuzione 4.0. ^[1]

La teoria: le astrazioni

Il C4 parte dalle astrazioni, non dai disegni. Sono cinque, e ognuna sta dentro la precedente: un sistema ha container, un container ha componenti, un componente è fatto di codice. ^[2]

Un container non è Docker. Lo avverte il sito stesso: nel C4 un container è un’applicazione o un archivio di dati. ^[2] Un database è un container anche se gira su un server qualsiasi, e due container Docker della stessa applicazione restano un solo container C4.

Miti comuni

• “Servono tutti e quattro i livelli”

  No. Contesto e container bastano alla maggior parte dei team. Usa gli altri solo quando aggiungono valore. ^[3]

• “Il C4 è una notazione”

  È un insieme di astrazioni e di diagrammi. Il sito dice che è indipendente dalla notazione: forme e colori sono a tua scelta, purché ci sia una legenda. ^[1][4]

• “Il C4 sostituisce UML”

  È nato ispirandosi a UML e ci convive. I diagrammi dinamico e di deployment, per esempio, si basano su quelli di comunicazione e di deployment di UML. ^[3]

• “Un microservizio è un componente”

  Un microservizio che gira ed è rilasciato da solo è un container (o un sistema, se ha più container e un altro team). Un componente non si rilascia separatamente. ^[2]

I quattro livelli e i diagrammi aggiuntivi

Ogni diagramma principale ingrandisce l’elemento evidenziato del precedente. Per ogni livello il sito indica l’ambito, il pubblico e se vale la pena disegnarlo. ^[3]

Il pubblico cambia con lo zoom: il diagramma di contesto è per tutti, anche per chi non è tecnico; quello dei container è per il team tecnico, le operazioni e il supporto; quello dei componenti, per architetti e sviluppatori. ^[3]

Le regole di notazione

Il C4 non impone forme né colori, ma chiede che ogni diagramma si spieghi da solo. ^[4] La figura mostra che cosa devono riportare ogni elemento e ogni relazione.

• Un titolo con il tipo e l’ambito del diagramma, come “Diagramma dei container del Sistema della biblioteca”.
• Una legenda che spieghi forme, colori, linee e frecce.
• Un tipo esplicito su ogni elemento (Persona, Sistema software, Container, Componente) e una breve descrizione delle responsabilità.
• Una tecnologia su ogni container e componente.
• Relazioni in un solo verso, ognuna con un’etichetta coerente con la freccia. Evita parole isolate come “Usa”.
• Un protocollo sulle relazioni tra container, che di solito sono comunicazioni tra processi.
• Sigle comprensibili a tutto il pubblico, o spiegate nella legenda. I colori, se usati, hanno lo stesso significato in tutti i diagrammi.

Il sito trasforma queste regole in una checklist di domande sì o no, come “il diagramma ha un titolo?” e “ogni freccia ha un’etichetta che descrive l’intento della relazione?”. ^[4] Il C4 Studio aiuta in parecchie: la riga del tipo ([Contêiner: React]) compare da sola, la legenda si costruisce con i tipi usati, e la documentazione generata segnala gli elementi senza descrizione e le relazioni senza tecnologia.

Come modellare, passo dopo passo

Con le astrazioni e le regole in mano, il lavoro segue un ordine semplice, dall’esterno verso l’interno:

1. Scegli l’ambito. Un sistema software, meglio se quello che un team mantiene. Se l’argomento è l’intera azienda, comincia dal panorama.
2. Disegna il contesto. Metti il sistema al centro. Chiediti chi lo usa (persone e ruoli) e con quali sistemi scambia dati, e in che verso. Per ora ignora la tecnologia.
3. Ingrandisci i container. Che cosa gira separatamente dentro il sistema? Ogni applicazione, database, coda e attività pianificata diventa un container, con una tecnologia. Ogni freccia riceve un protocollo. Ripeti le persone e i sistemi esterni del contesto che si collegano a questi container.
4. Vai ai componenti solo dove serve. Un container complesso o critico può meritare un diagramma dei componenti. Per una documentazione di lunga durata, genera questo livello dal codice, se puoi. ^[3]
5. Di solito salta il codice. L’IDE mostra le classi quando qualcuno ne ha bisogno.
6. Aggiungi i diagrammi aggiuntivi che rispondono a una domanda reale: “dove gira?” (deployment), “che cosa succede quando il cliente compra?” (dinamico), “quali sistemi ha l’azienda?” (panorama).
7. Rivedi con la checklist e mantieni gli stessi nomi in tutti i diagrammi. Lo stesso elemento deve avere lo stesso nome nel contesto e nei container.

La schermata dell’app

La prima volta, il C4 Studio apre l’esempio Loja Online (negozio online), con sette diagrammi: panorama, contesto, container, componenti, codice, dinamico e deployment. Conviene sfogliare le schede prima di disegnare. Per tornarci più tardi, usa Arquivo → Carregar exemplo (File → Carica esempio).

Barra in alto

Una scheda per diagramma, con il livello prima del titolo, e + per crearne un altro. A destra: annulla e ripeti, ▶ Simular (simula), Documentar (documenta), Arquivo ▾ (file) ed Exportar ▾ (esporta).

Tavolozza (Elementos)

Fai clic su una voce per crearla al centro dello schermo, oppure trascinala dove vuoi. Sotto c’è un riepilogo delle scorciatoie.

Area di disegno

Trascina lo sfondo per spostare la vista e usa la rotellina per lo zoom. Nell’angolo: −, la percentuale (torna al 100%), + e Ajustar (adatta), che inquadra il diagramma.

Pannello a destra

Cambia con la selezione: Diagrama (niente selezionato), Elemento, Fronteira (confine), Relação (relazione), più elementi selezionati o Simulação.

Elementi della tavolozza

Ogni voce corrisponde a un’astrazione del C4 e a una macro del C4-PlantUML, usata nell’esportazione. ^[10]

Il campo Nível C4 (livello C4) di ogni diagramma accetta Panorama do Sistema (panorama), Contexto do Sistema (contesto), Contêineres, Componentes, Código, Dinâmico, Implantação (deployment) e Outro (altro). L’app non ti impedisce di mescolare i livelli: la coerenza dipende da te.

Nomi dei pulsanti

Il tuo primo diagramma di contesto

Modelliamo il sistema di una biblioteca comunale. I lettori cercano e prenotano libri, i bibliotecari registrano i prestiti, e il sistema invia avvisi via e-mail. Fai ogni passo nell’app. Le schermate mostrano lo stesso esempio con i nomi in portoghese.

1. Apri il C4 Studio e scegli Arquivo → Novo projeto (File → Nuovo progetto). Conferma. (Si può annullare con Ctrl+Z.)
2. Senza niente selezionato, il pannello mostra Diagrama. In Título (titolo) scrivi Biblioteca Comunale. Lascia Nível C4 su Contexto do Sistema (contesto del sistema), scrivi una Descrição (descrizione) e spunta Mostrar legenda (mostra legenda).
3. Fai clic su Pessoa (persona) nella tavolozza. L’elemento compare al centro con il nome già selezionato: scrivi Lettore. In Descrição scrivi Persona che cerca, prenota e prende in prestito libri. Trascinalo in alto a sinistra.
4. Crea un’altra Pessoa, Bibliotecario (Dipendente che cataloga i libri e registra i prestiti.), e trascinala in alto a destra.
5. Crea un Sistema de software (sistema software), Sistema della Biblioteca (Catalogo, prenotazioni, prestiti e restituzioni.), al centro, e un Sistema externo (sistema esterno), Servizio E-mail (Invia e-mail transazionali.), in basso.
6. Per collegare, fai clic sul Lettore. Alla sua destra compare un cerchio arancione: trascinalo sul Sistema della Biblioteca e rilascia quando la destinazione ha il contorno verde.
7. La relazione nasce con l’etichetta Usa già selezionata. Sostituiscila con Cerca e prenota libri e, in Tecnologia / protocolo, scrivi HTTPS.
8. Fai lo stesso dal Bibliotecario al sistema (Registra prestiti e restituzioni, HTTPS) e dal sistema all’e-mail (Invia promemoria di restituzione, SMTP).
9. Fai clic sullo sfondo e poi su Ajustar (adatta).

Nota che cosa ha fatto l’app per te: la riga [Pessoa] o [Sistema de Software] in ogni riquadro, le frecce tratteggiate (lo stile C4 predefinito dell’app) e una legenda con i soli tipi usati. Con un doppio clic su un elemento, il cursore va dritto al nome.

Scendere ai container

Ora lo zoom sul Sistema della Biblioteca: che cosa gira al suo interno?

1. Fai clic sul + accanto alle schede. Il nuovo diagramma ha già il livello successivo, Contêineres (container). Dagli il titolo Biblioteca — Container e spunta Mostrar legenda.
2. Torna alla scheda del contesto, seleziona il Lettore e fai clic su Copiar para outro diagrama (copia in un altro diagramma). Il browser chiede il numero del diagramma di destinazione: conferma 1. Fai lo stesso con il Servizio E-mail. La copia porta con sé nome e descrizione, così i due diagrammi usano gli stessi nomi.
3. Nella scheda dei container, crea una Fronteira (confine) chiamata Sistema della Biblioteca. Nei diagrammi dei container il Tipo da fronteira (tipo di confine) è già Sistema de Software. Porta la Largura (larghezza) a 800 e l’Altura (altezza) a 560. Per spostare il confine, trascina il bordo tratteggiato.
4. Dentro il confine crea un App web / mobile, Sito della Biblioteca (tecnologia React); un Contêiner, API (Java / Spring Boot); e un Banco de dados (database), Database (PostgreSQL). Metti il lettore sopra il confine e l’e-mail a destra, all’esterno.
5. Collega: Lettore → Sito (Cerca e prenota libri, HTTPS), Sito → API (Chiama l’API, JSON/HTTPS), API → Database (Legge e scrive, SQL/TCP) e API → E-mail (Invia promemoria di restituzione, SMTP).
6. Fai clic sullo sfondo e su Ajustar. Il pannello deve mostrare 5 elementos · 4 relações (5 elementi · 4 relazioni): il confine non conta come elemento.

Quando sposti un confine, tutto ciò che sta interamente al suo interno lo segue. Quindi posiziona il confine prima di metterci dentro i container. Se un elemento resta nascosto dietro un altro, usa i pulsanti di Sobreposição (ordine di sovrapposizione) del pannello oppure Ctrl+] e Ctrl+[.

Riordinare il diagramma

I diagrammi disordinati sono difficili da leggere. Seleziona più elementi con Shift+clic, oppure tieni premuto Shift e trascina sullo sfondo per tracciare un rettangolo di selezione. Il pannello mostra allora gli strumenti di impaginazione.

• Alinhar (allinea): sui bordi o al centro, in orizzontale e in verticale.
• Distribuir (distribuisci): spazi uguali tra tre o più elementi.
• Espaçamento (spaziatura): mette in fila gli elementi alla distanza che scegli, in pixel.
• Dimensionamento (dimensioni): copia larghezza, altezza o dimensione del riferimento, l’ultimo elemento cliccato (contorno più marcato), oppure applica una misura scritta.
• Ajustar altura ao texto (adatta l’altezza al testo), Encaixar na grade (aggancia alla griglia) e Remover sobreposições (rimuovi sovrapposizioni), che allontana gli elementi accavallati.

Scorciatoie

Simulare flussi e guasti

Un diagramma C4 è statico. Il C4 Studio aggiunge una lettura dinamica delle relazioni: fai clic su ▶ Simular (simula). Una fascia verde avverte che il diagramma non viene modificato, e la tavolozza si disattiva. Esc o Sair da simulação (esci dalla simulazione) riportano alla modifica.

Flusso di chiamate

Nella scheda Fluxo de chamadas (flusso di chiamate), fai clic su un elemento. L’app segue le frecce a partire da lì, a ondate: il passo 1 sono le destinazioni dirette, il passo 2 le loro destinazioni, e così via. Le relazioni bidirezionali valgono in entrambi i versi. Il pannello elenca ogni passo con etichetta e protocollo e conta chi è stato raggiunto. Velocidade (velocità) regola l’animazione, e Repetir (ripeti) la riavvia.

Nel diagramma dei container della biblioteca, partendo dal lettore, il risultato è stato: 5 raggiunti, 0 fuori percorso, 3 passi.

Gli elementi fuori percorso meritano attenzione: o non partecipano a quel percorso, il che è normale, o manca una relazione nel diagramma.

Guasti

Nella scheda Falhas (guasti), ogni clic mette fuori servizio un elemento (un altro clic lo ripristina). La regola di lettura è: una relazione A → B significa “A dipende da B”. Se B cade, A diventa non disponibile, e il guasto si propaga a chi dipende da A. Tre impostazioni cambiano il risultato:

• Regra de propagação (regola di propagazione). Com redundância (con ridondanza, predefinita): le dipendenze dello stesso tipo e della stessa tecnologia valgono come copie l’una dell’altra, e l’origine cade solo se cadono tutte. Sem redundância (senza ridondanza): qualsiasi dipendenza fuori servizio fa cadere chi ne dipende.
• Não bloqueante (non bloccante). Spuntata nel pannello della relazione, fa sì che il guasto della destinazione degradi soltanto l’origine, senza farla cadere. Serve per chiamate asincrone o facoltative.
• Encontrar pontos únicos de falha (trova i singoli punti di guasto). Prova ogni elemento da solo, con la regola con ridondanza, ed elenca quelli che ne fanno cadere altri, dal peggiore. Un clic su una voce dell’elenco simula quel guasto.

Un esperimento

Nel diagramma dei container della biblioteca, i singoli punti di guasto elencati sono stati: il servizio e-mail e il database (ognuno ne fa cadere 3), l’API (ne fa cadere 2) e il sito (ne fa cadere 1). Poi la relazione API → e-mail è stata segnata come non bloccante, perché un avviso può aspettare. I contatori del pannello nelle tre situazioni:

L’elemento che cade rientra nel conteggio dei non disponibili. Con la relazione non bloccante, solo l’e-mail è non disponibile, e API, sito e lettore diventano degradati. Questo non misura la disponibilità reale: è una lettura delle dipendenze che hai disegnato tu. Se una freccia manca o ha il verso sbagliato, sbaglia anche la simulazione. Usala per fare domande al team, come “che cosa succede davvero al sito se il server di posta si ferma?”.

Nell’esempio Loja Online, scheda dei container, il peggior singolo punto di guasto segnalato è la Fila de Pedidos (coda degli ordini), che fa cadere 6 elementi.

Documentare, esportare e salvare

Documentar (documenta)

Il pulsante Documentar costruisce un documento di architettura dal diagramma corrente o da tutti i diagrammi del progetto. Per ogni diagramma riporta livello, descrizione, le Notas para a documentação (note per la documentazione) del pannello Diagramma, l’immagine, la struttura dei confini e le tabelle di elementi, relazioni e dipendenze per elemento. Alla fine ci sono i pontos de atenção (punti di attenzione), generati automaticamente: singoli punti di guasto, elementi senza descrizione, relazioni senza tecnologia ed elementi senza alcuna relazione. Il testo del documento è in portoghese.

Puoi copiare il Markdown, scaricarlo in .md o HTML, oppure stamparlo e salvarlo in PDF. Togli la spunta da Incluir imagens (includi immagini) quando incolli il Markdown in uno strumento di IA: le immagini entrano come testo codificato e occupano molto spazio.

Exportar (esporta)

• Imagem SVG e Imagem PNG (a risoluzione doppia), con titolo e descrizione sotto il disegno.
• Código C4-PlantUML, per versionare il diagramma come testo. Le posizioni non vengono esportate: PlantUML ridisegna da sé. Il codice include la libreria C4-PlantUML da un indirizzo GitHub, quindi chi lo visualizza ha bisogno di internet. ^[10]

Salvare, aprire e importare

• Salvar projeto (.json) (salva progetto) scarica tutti i diagrammi in un file .c4.json.
• Abrir projeto (.json)… (apri progetto) sostituisce il progetto corrente con quello del file. Si può annullare.
• Importar diagramas em novas abas (.json)… (importa diagrammi in nuove schede) aggiunge diagrammi senza toccare quelli esistenti. Una finestra permette di scegliere quali entrano e di rinominarli. Trascinare un .json sull’area di disegno fa lo stesso. È il modo per unire il lavoro dei colleghi o portare diagrammi generati dall’IA.

L’app non ha un campo per il nome del progetto, usato nel titolo della documentazione e nel nome del file. Un progetto nuovo si chiama “Projeto”. Per cambiarlo, modifica il campo "name" nel .json salvato e riaprilo.

Prompt di IA

Un’IA aiuta a superare la pagina bianca, a estrarre elementi da una documentazione sparsa e a rivedere un diagramma secondo le regole del C4. Sbaglia anche con sicurezza: inventa sistemi, inverte le frecce e confonde container e componenti. Tratta il risultato come una bozza. Per scrivere prompt migliori, vedi il tutorial sui prompt.

Prima di incollare: i diagrammi di architettura rivelano nomi di server, fornitori e punti deboli. Togli indirizzi, password e nomi interni, e segui la politica della tua organizzazione sull’uso dell’IA. L’app non invia niente in rete, ma il servizio di IA riceve tutto ciò che incolli.

Sostituisci le parti tra parentesi quadre e incolla nello strumento di IA che usi. Se l’IA risponde in italiano, anche i nomi generati saranno in italiano; l’app accetta qualsiasi lingua.

1. Intervistare per costruire il contesto

Fa sì che l’IA chieda invece di supporre. È il miglior inizio quando il sistema esiste solo nella testa delle persone.

Sei un architetto software che usa il modello C4 (c4model.com).
Voglio disegnare il diagramma di contesto di questo sistema: [descrivilo in poche frasi].

Prima di proporre qualsiasi diagramma, intervistami:
- Fai una domanda alla volta e aspetta la mia risposta.
- Scopri chi usa il sistema (persone e ruoli) e per che cosa, con quali sistemi esterni scambia dati, in che verso e con quale mezzo, e chi è il proprietario di ogni sistema esterno.
- Chiedi anche che cosa succede quando ogni sistema esterno è fuori servizio.
- Non inventare risposte. Se non lo so, registralo come punto aperto.

Alla fine, consegna:
1. Tabella degli elementi: nome, tipo C4 (Persona, Sistema software o Sistema esterno) e descrizione di una frase.
2. Tabella delle relazioni: origine, destinazione, etichetta con un verbo nel verso della freccia, tecnologia o protocollo.
3. Elenco dei punti aperti.

2. Estrarre i container da materiale esistente

Per README, wiki, file docker-compose o verbali. Chiede la fonte di ogni voce, il che facilita il controllo.

Dal materiale qui sotto, estrai gli elementi di un diagramma dei container C4 del sistema [nome].

Regole:
- Nel C4, un container è un'applicazione o un archivio di dati che gira separatamente. Non è la stessa cosa di un container Docker. Librerie e moduli interni non sono container.
- Usa solo ciò che c'è nel materiale. Per ogni voce, cita il passo di origine.
- Segna come [IPOTESI] tutto ciò che hai dedotto.

Consegna:
1. Persone e sistemi esterni.
2. Container: nome, genere (applicazione web, API, database, coda, attività pianificata...), tecnologia e responsabilità in una frase.
3. Relazioni: origine → destinazione, etichetta e protocollo.
4. Contraddizioni e ciò che manca sapere.

Materiale:
"""
[incolla qui, senza password, indirizzi interni o dati personali]
"""

3. Generare il JSON per il C4 Studio

Produce un file che l’app può importare. Salva la risposta in un file di testo con estensione .c4.json e usa Arquivo → Importar diagramas em novas abas (.json)…, oppure trascina il file sull’area di disegno. Poi riordina il disegno e lancia la simulazione dei guasti. Lascia "Sistema de Software" scritto esattamente così, in portoghese: l’app usa quel testo per esportare il confine come System_Boundary.

Genera un file JSON per il C4 Studio con due diagrammi C4 di questo sistema: uno di contesto e uno dei container.
Sistema: [descrivi il sistema o incolla le tabelle dei prompt 1 e 2].

Rispondi solo con il JSON, in questo formato:
{
  "format": "c4studio",
  "version": 1,
  "name": "[nome del progetto]",
  "diagrams": [
    {
      "id": "d1", "title": "...", "level": "context",
      "desc": "...", "notes": "...", "legend": true,
      "nodes": [
        {"id": "n1", "type": "person", "name": "...", "tech": "", "desc": "...", "x": 0, "y": 0, "w": 200, "h": 190}
      ],
      "edges": [
        {"id": "r1", "from": "n1", "to": "n2", "label": "...", "tech": "...", "style": "dashed", "both": false, "soft": false}
      ]
    }
  ]
}

Regole:
- level: context o container (altri valori accettati: landscape, component, code, dynamic, deployment).
- type: person, person_ext, system, system_ext, container, database, queue, webapp, component, code o boundary.
- Dimensioni (w × h): person 200×190; system e system_ext 240×150; container 240×150; database 240×160; queue 260×130; webapp 240×160; component 230×140.
- Nel diagramma dei container, racchiudi i container del sistema in un nodo "boundary" con "tech": "Sistema de Software" e mettilo per primo nell'elenco dei nodi. I container stanno interamente al suo interno; persone e sistemi esterni restano fuori.
- x e y multipli di 10, con almeno 140 di spazio tra gli elementi. Persone in alto; sistemi esterni in basso o a destra.
- id unici in ogni diagramma; from e to puntano sempre a nodi dello stesso diagramma.
- Una relazione A → B significa "A dipende da B" o "A chiama B". Etichetta specifica, con un verbo (evita "Usa"). Per i container, indica la tecnologia o il protocollo in "tech".
- Ogni container ha una "tech", e ogni descrizione è una frase breve.
- "soft": true solo quando il guasto della destinazione non impedisce all'origine di funzionare, come un invio asincrono di e-mail.
- In "notes", elenca le ipotesi che hai fatto.

4. Rivedere con la checklist del C4

Incolla il Markdown di Documentar → Copiar Markdown, senza immagini. L’IA guarda il significato, che i controlli automatici non vedono.

Rivedi la documentazione di architettura qui sotto, generata dal C4 Studio, usando le regole di notazione e la checklist del modello C4. La documentazione può essere in portoghese; rispondi in italiano.

Verifica:
1. Titolo, tipo e ambito di ogni diagramma sono chiari?
2. Ogni elemento ha nome, tipo, descrizione e, se è un container o un componente, una tecnologia?
3. Ogni relazione ha un'etichetta specifica, coerente con il verso della freccia (senza un generico "Usa"), e un protocollo quando collega processi diversi?
4. Il livello di dettaglio è coerente con il tipo di diagramma? Per esempio: classi in un diagramma dei container.
5. Ci sono elementi isolati, sigle non spiegate o responsabilità ripetute?
6. I diagrammi si contraddicono, con nomi o relazioni diversi per la stessa cosa?

Per ogni problema indica: diagramma, elemento o relazione, problema, correzione proposta e gravità (alta, media o bassa). Separa la certezza dal sospetto. Non inventare fatti sul sistema; se servono, chiedi.

Documentazione:
"""
[incolla il Markdown]
"""

5. Spiegare l’architettura a chi non è tecnico

Utile per validare il diagramma di contesto con responsabili e utenti.

Spiega l'architettura qui sotto a [pubblico, per esempio: direzione, assistenza clienti, revisori], senza gergo tecnico.

Consegna:
- In tre frasi: che cosa fa il sistema, chi lo usa e da quali altri sistemi dipende.
- Un elenco "che cosa succede quando...": per ogni sistema esterno e ogni database, l'effetto del suo essere fuori servizio.
- Un breve glossario per i termini che non si possono evitare.
- Cinque domande per verificare con quel pubblico se il disegno corrisponde a ciò che conosce.

Usa solo ciò che c'è nella documentazione. Se qualcosa è ambiguo, dillo.

Documentazione:
"""
[incolla il Markdown, senza le immagini]
"""

6. Affrontare i singoli punti di guasto

Porta il risultato della simulazione in una conversazione sulla resilienza.

Il C4 Studio ha analizzato il diagramma dei container qui sotto e ha segnalato i singoli punti di guasto elencati.
Nella simulazione, una relazione A → B significa "A dipende da B". Le dipendenze dello stesso tipo e della stessa tecnologia valgono come ridondanti, e le relazioni segnate come non bloccanti degradano soltanto l'origine.

Singoli punti di guasto:
[incolla l'elenco di Simular → Falhas → Encontrar pontos únicos de falha]

Diagramma:
"""
[incolla il Markdown della documentazione, senza le immagini]
"""

Per ogni singolo punto di guasto, proponi fino a due mitigazioni (ridondanza, coda, cache, modalità degradata, timeout con alternativa), con un costo relativo (basso, medio o alto) e che cosa cambia nel diagramma: nuovi elementi, nuove relazioni o relazioni che diventano non bloccanti.
Indica quali punti lasceresti come sono e perché. Non dare per scontati requisiti di disponibilità che non ho indicato: chiedi.

7. Registrare una decisione di architettura

Il testo ottenuto entra nel campo Notas para a documentação del diagramma e finisce nel documento generato.

Scrivi un breve architecture decision record (ADR) per questa decisione: [es.: mettere una coda tra l'API e l'invio degli avvisi].

Contesto del sistema: [incolla la descrizione del diagramma dei container o il Markdown senza immagini].

Formato:
- Titolo
- Stato: proposta
- Contesto: il problema e i vincoli, in massimo cinque frasi
- Decisione
- Conseguenze: positive, negative e rischi
- Alternative considerate, con il motivo per cui sono state scartate
- Impatto sui diagrammi C4: elementi e relazioni che entrano, escono o cambiano

Al massimo 300 parole. Segna con [CONFERMARE] ciò che hai supposto.

8. Scendere ai componenti partendo dal codice

Per quando un container merita il terzo livello. Poi chiedi al prompt 3 il JSON con "level": "component".

Voglio il diagramma dei componenti C4 del container [nome], scritto in [tecnologia]. Qui sotto ci sono la struttura delle cartelle e i file principali.

Ricorda: nel C4, un componente è un raggruppamento di funzionalità correlate dietro un'interfaccia ben definita, dentro un solo container, e non si rilascia separatamente.

Consegna:
1. Componenti: nome, tecnologia, responsabilità in una frase e i file o le cartelle che lo formano.
2. Relazioni tra componenti e con elementi fuori dal container (altri container, database, sistemi esterni): origine → destinazione, etichetta e protocollo se presente.
3. Parti del codice che non rientrano in nessun componente o sembrano appartenere a più di uno.

Preferisci da 5 a 12 componenti. Non elencare le classi una per una.

Struttura:
"""
[incolla l'albero delle cartelle e gli estratti rilevanti, senza segreti]
"""

Che cosa è stato provato in questi prompt

Il formato del prompt 3 è stato provato: un JSON scritto da Claude con queste regole, per una clinica veterinaria, è stato importato dal menu dell’app (2 diagrammi, con 5 e 9 elementi), ha simulato guasti ed esportato C4-PlantUML senza errori. In quella prova lo spazio tra gli elementi era 100 e alcune etichette di relazione si sovrapponevano; per questo il prompt chiede 140. Anche così, mettiti in conto qualche ritocco manuale al disegno. Gli altri prompt non sono stati eseguiti, e le risposte cambiano ogni volta e da un’IA all’altra.

Buone pratiche ed errori comuni

Ripasso veloce

Prova a rispondere prima di aprire.

Apri il C4 Studio →

Riferimenti

1. Simon Brown. The C4 model for visualising software architecture e Introduction. Fonte dell’analogia con le mappe, dell’indipendenza dalla notazione e della licenza Creative Commons Attribuzione 4.0.
2. Simon Brown. Abstractions, con le pagine su software system, container, component e code.
3. Simon Brown. Diagrams, con le pagine sui diagrammi di contesto, container, componenti, codice, panorama, dinamico e deployment. Fonte di ambito, pubblico e raccomandazione di ogni diagramma.
4. Simon Brown. Notation e Review checklist.
5. Simon Brown. FAQ. Fonte dell’autore, delle radici nel 2006–2009, dei nomi del 2010 e del nome “C4” nel 2011. Colloca il passaggio da “classes” a “code” nel 2015–2016, in disaccordo con la pagina sulla storia [6].
6. Simon Brown. History. Colloca il primo uso del nome “C4” alla QCon London 2011 e il passaggio definitivo da “Classes” a “Code” in un intervento di marzo 2018.
7. Simon Brown. The C4 Model for Software Architecture. InfoQ, 25 giugno 2018.
8. Wikipedia. C4 model. Colloca la creazione tra il 2006 e il 2011, un intervallo più ampio di quello delle FAQ [5], e attribuisce la diffusione al sito ufficiale e all’articolo del 2018.
9. Philippe Kruchten. Architectural Blueprints — The “4+1” View Model of Software Architecture. IEEE Software, 12(6), novembre 1995, pp. 42–50.
10. plantuml-stdlib. C4-PlantUML, con licenza MIT. Fonte delle macro usate nell’esportazione.
11. Simon Brown. Software Architecture for Developers. Leanpub. La pagina del libro presenta l’autore come creatore del modello C4 e fondatore di Structurizr.

Qué es el modelo C4

El modelo C4 es una forma de dibujar la arquitectura de un software en varios niveles de detalle. El sitio oficial lo describe como una manera de crear “mapas de tu código”, acercando y alejando la vista como en una app de mapas. ^[1] El nombre viene de los cuatro diagramas principales: Contexto, Contenedores, Componentes y Código. ^[7]

Resuelve un problema conocido: el diagrama de “cajas y flechas” que cada persona dibuja a su manera, sin decir qué es cada caja ni qué significa cada flecha. El C4 define un vocabulario pequeño (persona, sistema, contenedor, componente) y una jerarquía entre esos términos. Así todos saben en qué nivel de zoom están mirando.

Este tutorial explica la teoría y luego la lleva a la práctica en C4 Studio, una app en un único archivo HTML. Con ella dibujas los diagramas, simulas por dónde pasan las llamadas y qué cae cuando algo falla, y generas la documentación. No se envía nada a la red: el proyecto queda guardado en tu navegador.

Abrir C4 Studio →

Una breve historia

El C4 fue creado por el arquitecto de software Simon Brown, a partir de lo que veía al enseñar a los equipos a dibujar arquitectura. ^[5] La cronología muestra los hitos, con las fechas de las fuentes consultadas.

• 1995. Philippe Kruchten publica el modelo “4+1”: cuatro vistas de la arquitectura (lógica, de procesos, de desarrollo y física) ilustradas con escenarios, el “+1”. La idea de mirar el mismo sistema desde perspectivas distintas es una de las inspiraciones del C4. ^[9][5]
• De 2006 a 2009. Surgen las raíces del modelo, inspiradas en UML y en el 4+1. ^[5][8]
• 2010. Los tipos de diagrama reciben nombre: contexto, contenedores, componentes y clases. ^[5]
• 2011. El nombre “C4” aparece por primera vez, en una charla en la QCon London. La última C todavía era de “clases”. ^[6]
• De 2015 a 2018. “Clases” pasa a “Código”. Las FAQ del sitio dan 2015–2016, y la página de historia dice que el cambio solo se completó en marzo de 2018. ^[5][6]
• 2018. Un artículo de Simon Brown en InfoQ, junto con el sitio oficial bajo licencia Creative Commons, ayuda a popularizar la técnica. ^[7][8]

Brown también escribió el libro Software Architecture for Developers y fundó Structurizr, una herramienta que genera varios diagramas a partir de un único modelo. ^[11][8] El sitio y sus ejemplos están bajo la licencia Creative Commons Atribución 4.0. ^[1]

La teoría: las abstracciones

El C4 empieza por las abstracciones, no por los dibujos. Son cinco, y cada una está dentro de la anterior: un sistema tiene contenedores, un contenedor tiene componentes, un componente está hecho de código. ^[2]

Contenedor no es Docker. El propio sitio lo advierte: en el C4, un contenedor es una aplicación o un almacén de datos. ^[2] Una base de datos es un contenedor aunque corra en un servidor común, y dos contenedores Docker de la misma aplicación siguen siendo un solo contenedor C4.

Mitos comunes

• “Necesito los cuatro niveles”

  No. Contexto y contenedores bastan para la mayoría de los equipos. Usa los demás solo cuando aporten valor. ^[3]

• “El C4 es una notación”

  Es un conjunto de abstracciones y diagramas. El sitio dice que es independiente de la notación: formas y colores quedan a tu criterio, siempre que haya leyenda. ^[1][4]

• “El C4 reemplaza a UML”

  Nació inspirado en UML y convive con él. Los diagramas dinámico y de despliegue, por ejemplo, se basan en los de comunicación y de despliegue de UML. ^[3]

• “Un microservicio es un componente”

  Un microservicio que corre y se despliega solo es un contenedor (o un sistema, si tiene varios contenedores y otro equipo). Un componente no se despliega por separado. ^[2]

Los cuatro niveles y los diagramas adicionales

Cada diagrama principal hace zoom en el elemento destacado del anterior. Para cada nivel, el sitio indica el alcance, el público y si vale la pena dibujarlo. ^[3]

El público cambia con el zoom: el diagrama de contexto es para todos, incluso quien no es técnico; el de contenedores es para el equipo técnico, operaciones y soporte; el de componentes, para arquitectos y desarrolladores. ^[3]

Las reglas de notación

El C4 no impone formas ni colores, pero pide que cada diagrama se explique solo. ^[4] La figura muestra qué deben llevar cada elemento y cada relación.

• Un título con el tipo y el alcance del diagrama, como “Diagrama de contenedores del Sistema de la Biblioteca”.
• Una leyenda que explique formas, colores, líneas y flechas.
• Un tipo explícito en cada elemento (Persona, Sistema de Software, Contenedor, Componente) y una descripción breve de sus responsabilidades.
• Una tecnología en cada contenedor y componente.
• Relaciones en un solo sentido, cada una con una etiqueta coherente con la flecha. Evita palabras sueltas como “Usa”.
• Un protocolo en las relaciones entre contenedores, que suelen ser comunicación entre procesos.
• Siglas que todo el público entienda, o explicadas en la leyenda. Los colores, si se usan, significan lo mismo en todos los diagramas.

El sitio convierte estas reglas en una lista de comprobación de preguntas de sí o no, como “¿el diagrama tiene título?” y “¿cada flecha tiene una etiqueta que describe la intención de la relación?”. ^[4] C4 Studio ayuda con varias: la línea de tipo ([Contêiner: React]) aparece sola, la leyenda se arma con los tipos usados, y la documentación generada señala los elementos sin descripción y las relaciones sin tecnología.

Cómo modelar, paso a paso

Con las abstracciones y las reglas en mano, el trabajo sigue un orden sencillo, de fuera hacia dentro:

1. Elige el alcance. Un sistema de software, de preferencia el que mantiene un equipo. Si el tema es la empresa entera, empieza por el panorama.
2. Dibuja el contexto. Pon el sistema en el centro. Pregunta quién lo usa (personas y roles) y con qué sistemas intercambia datos, y en qué sentido. Por ahora ignora la tecnología.
3. Haz zoom en los contenedores. ¿Qué corre por separado dentro del sistema? Cada aplicación, base de datos, cola y tarea programada se convierte en un contenedor, con su tecnología. Cada flecha recibe un protocolo. Repite las personas y los sistemas externos del contexto que se conectan con esos contenedores.
4. Ve a los componentes solo donde haga falta. Un contenedor complejo o crítico puede merecer un diagrama de componentes. Para documentación de larga duración, genera este nivel a partir del código si puedes. ^[3]
5. Por lo general, sáltate el código. El IDE muestra las clases cuando alguien las necesita.
6. Añade los diagramas adicionales que respondan a una pregunta real: “¿dónde corre esto?” (despliegue), “¿qué pasa cuando el cliente compra?” (dinámico), “¿qué sistemas tiene la empresa?” (panorama).
7. Revisa con la lista de comprobación y mantén los nombres iguales en todos los diagramas. El mismo elemento debe llamarse igual en el contexto y en los contenedores.

La pantalla de la app

La primera vez, C4 Studio abre el ejemplo Loja Online (tienda en línea), con siete diagramas: panorama, contexto, contenedores, componentes, código, dinámico y despliegue. Vale la pena recorrer las pestañas antes de dibujar. Para volver a él más tarde, usa Arquivo → Carregar exemplo (Archivo → Cargar ejemplo).

Barra superior

Una pestaña por diagrama, con el nivel antes del título, y + para crear otro. A la derecha: deshacer y rehacer, ▶ Simular, Documentar, Arquivo ▾ (archivo) y Exportar ▾.

Paleta (Elementos)

Haz clic en un elemento para crearlo en el centro de la pantalla, o arrástralo hasta donde quieras. Debajo hay un resumen de los atajos.

Área de dibujo

Arrastra el fondo para mover la vista y usa la rueda del ratón para el zoom. En la esquina: −, el porcentaje (vuelve al 100%), + y Ajustar, que encuadra el diagrama.

Panel derecho

Cambia según la selección: Diagrama (nada seleccionado), Elemento, Fronteira (frontera), Relação (relación), varios elementos seleccionados o Simulação.

Elementos de la paleta

Cada elemento corresponde a una abstracción del C4 y a una macro de C4-PlantUML, usada en la exportación. ^[10]

El campo Nível C4 (nivel C4) de cada diagrama acepta Panorama do Sistema (panorama), Contexto do Sistema (contexto), Contêineres, Componentes, Código, Dinâmico, Implantação (despliegue) y Outro (otro). La app no impide mezclar niveles: la coherencia depende de ti.

Nombres de los botones

Tu primer diagrama de contexto

Vamos a modelar el sistema de una biblioteca municipal. Los lectores buscan y reservan libros, los bibliotecarios registran préstamos, y el sistema envía avisos por correo electrónico. Haz cada paso en la app. Las capturas muestran el mismo ejemplo con nombres en portugués.

1. Abre C4 Studio y elige Arquivo → Novo projeto (Archivo → Nuevo proyecto). Confirma. (Se puede deshacer con Ctrl+Z.)
2. Sin nada seleccionado, el panel muestra Diagrama. En Título escribe Biblioteca Municipal. Deja Nível C4 en Contexto do Sistema (contexto del sistema), escribe una Descrição (descripción) y marca Mostrar legenda (mostrar leyenda).
3. Haz clic en Pessoa (persona) en la paleta. El elemento aparece en el centro con el nombre ya seleccionado: escribe Lector. En Descrição escribe Persona que busca, reserva y toma prestados libros. Arrástralo arriba a la izquierda.
4. Crea otra Pessoa, Bibliotecario (Empleado que cataloga libros y registra préstamos.), y arrástrala arriba a la derecha.
5. Crea un Sistema de software, Sistema de la Biblioteca (Catálogo, reservas, préstamos y devoluciones.), en el centro, y un Sistema externo, Servicio de Correo (Envía correos transaccionales.), abajo.
6. Para conectar, haz clic en el Lector. A su derecha aparece un círculo naranja: arrástralo hasta el Sistema de la Biblioteca y suelta cuando el destino tenga el contorno verde.
7. La relación nace con la etiqueta Usa ya seleccionada. Cámbiala por Busca y reserva libros y, en Tecnologia / protocolo, escribe HTTPS.
8. Haz lo mismo del Bibliotecario al sistema (Registra préstamos y devoluciones, HTTPS) y del sistema al correo (Envía avisos de devolución, SMTP).
9. Haz clic en el fondo y luego en Ajustar.

Fíjate en lo que hizo la app por ti: la línea [Pessoa] o [Sistema de Software] en cada caja, las flechas discontinuas (el estilo C4 predeterminado de la app) y una leyenda solo con los tipos usados. Con doble clic en un elemento, el cursor va directo al nombre.

Bajar a los contenedores

Ahora el zoom en el Sistema de la Biblioteca: ¿qué corre dentro de él?

1. Haz clic en el + junto a las pestañas. El diagrama nuevo ya viene con el nivel siguiente, Contêineres (contenedores). Ponle el título Biblioteca — Contenedores y marca Mostrar legenda.
2. Vuelve a la pestaña del contexto, selecciona el Lector y haz clic en Copiar para outro diagrama (copiar a otro diagrama). El navegador pregunta el número del diagrama de destino: confirma 1. Haz lo mismo con el Servicio de Correo. La copia lleva el nombre y la descripción, así los dos diagramas usan los mismos nombres.
3. En la pestaña de contenedores, crea una Fronteira (frontera) llamada Sistema de la Biblioteca. En los diagramas de contenedores, el Tipo da fronteira (tipo de frontera) ya viene como Sistema de Software. Sube la Largura (ancho) a 800 y la Altura (alto) a 560. Para mover la frontera, arrastra su borde discontinuo.
4. Dentro de la frontera, crea un App web / mobile, Sitio de la Biblioteca (tecnología React); un Contêiner, API (Java / Spring Boot); y un Banco de dados (base de datos), Base de Datos (PostgreSQL). Pon al lector encima de la frontera y el correo a la derecha, por fuera.
5. Conecta: Lector → Sitio (Busca y reserva libros, HTTPS), Sitio → API (Llama a la API, JSON/HTTPS), API → Base de Datos (Lee y escribe, SQL/TCP) y API → Correo (Envía avisos de devolución, SMTP).
6. Haz clic en el fondo y en Ajustar. El panel debe mostrar 5 elementos · 4 relações (5 elementos · 4 relaciones): la frontera no cuenta como elemento.

Cuando mueves una frontera, todo lo que está completamente dentro de ella se mueve también. Por eso, coloca la frontera antes de poner los contenedores dentro. Si un elemento queda oculto detrás de otro, usa los botones de Sobreposição (orden de superposición) del panel o Ctrl+] y Ctrl+[.

Ordenar el diagrama

Los diagramas desordenados cuestan de leer. Selecciona varios elementos con Shift+clic, o mantén Shift y arrastra en el fondo para trazar un rectángulo de selección. El panel muestra entonces las herramientas de diseño.

• Alinhar (alinear): por los bordes o por el centro, en horizontal y en vertical.
• Distribuir: espacios iguales entre tres o más elementos.
• Espaçamento (espaciado): pone los elementos en fila a la distancia que elijas, en píxeles.
• Dimensionamento (tamaño): copia el ancho, el alto o el tamaño de la referencia, el último elemento en el que hiciste clic (contorno más marcado), o aplica una medida escrita.
• Ajustar altura ao texto (ajustar la altura al texto), Encaixar na grade (ajustar a la cuadrícula) y Remover sobreposições (quitar superposiciones), que separa los elementos encimados.

Atajos

Simular flujos y fallos

Un diagrama C4 es estático. C4 Studio añade una lectura dinámica de las relaciones: haz clic en ▶ Simular. Una franja verde avisa que el diagrama no se modifica, y la paleta queda desactivada. Esc o Sair da simulação (salir de la simulación) vuelven a la edición.

Flujo de llamadas

En la pestaña Fluxo de chamadas (flujo de llamadas), haz clic en un elemento. La app sigue las flechas a partir de él, en oleadas: el paso 1 son los destinos directos, el paso 2 los destinos de esos, y así sucesivamente. Las relaciones bidireccionales valen en ambos sentidos. El panel lista cada paso con la etiqueta y el protocolo y cuenta a quién se alcanzó. Velocidade (velocidad) controla la animación, y Repetir la vuelve a ejecutar.

En el diagrama de contenedores de la biblioteca, partiendo del lector, el resultado fue: 5 alcanzados, 0 fuera del camino, 3 pasos.

Los elementos fuera del camino merecen atención: o no participan en ese recorrido, lo cual es normal, o falta una relación en el diagrama.

Fallos

En la pestaña Falhas (fallos), cada clic deja un elemento caído (otro clic lo restaura). La regla de lectura es: una relación A → B significa “A depende de B”. Si B cae, A queda no disponible, y el fallo se propaga a quien depende de A. Tres ajustes cambian el resultado:

• Regra de propagação (regla de propagación). Com redundância (con redundancia, la predeterminada): las dependencias del mismo tipo y la misma tecnología cuentan como copias entre sí, y el origen solo cae si caen todas. Sem redundância (sin redundancia): cualquier dependencia caída tumba a quien depende de ella.
• Não bloqueante (no bloqueante). Marcada en el panel de la relación, hace que el fallo del destino solo degrade el origen, sin tumbarlo. Sirve para llamadas asíncronas u opcionales.
• Encontrar pontos únicos de falha (encontrar puntos únicos de fallo). Prueba cada elemento por separado, con la regla con redundancia, y lista los que tumban a otros, del peor al menor. Al hacer clic en un elemento de la lista se simula ese fallo.

Un experimento

En el diagrama de contenedores de la biblioteca, los puntos únicos de fallo listados fueron: el servicio de correo y la base de datos (cada uno tumba 3), la API (tumba 2) y el sitio (tumba 1). Después, la relación API → correo se marcó como no bloqueante, ya que un aviso puede esperar. Los contadores del panel en las tres situaciones:

El elemento que cae entra en la cuenta de no disponibles. Con la relación no bloqueante, solo el correo queda no disponible, y la API, el sitio y el lector pasan a degradados. Esto no mide la disponibilidad real: es una lectura de las dependencias que dibujaste tú. Si falta una flecha o apunta al revés, la simulación también se equivoca. Úsala para hacer preguntas al equipo, como “¿qué le pasa de verdad al sitio si se cae el servidor de correo?”.

En el ejemplo Loja Online, pestaña de contenedores, el peor punto único de fallo señalado es la Fila de Pedidos (cola de pedidos), que tumba 6 elementos.

Documentar, exportar y guardar

Documentar

El botón Documentar arma un documento de arquitectura a partir del diagrama actual o de todos los diagramas del proyecto. Para cada diagrama incluye el nivel, la descripción, las Notas para a documentação (notas para la documentación) del panel Diagrama, la imagen, la estructura de fronteras y tablas de elementos, relaciones y dependencias por elemento. Al final vienen los pontos de atenção (puntos de atención), generados automáticamente: puntos únicos de fallo, elementos sin descripción, relaciones sin tecnología y elementos sin ninguna relación. El texto del documento está en portugués.

Puedes copiar el Markdown, descargarlo en .md o HTML, o imprimirlo y guardarlo como PDF. Desmarca Incluir imagens (incluir imágenes) cuando vayas a pegar el Markdown en una herramienta de IA: las imágenes entran como texto codificado y ocupan mucho espacio.

Exportar

• Imagem SVG e Imagem PNG (a doble resolución), con el título y la descripción debajo del dibujo.
• Código C4-PlantUML, para versionar el diagrama como texto. Las posiciones no se exportan: PlantUML rehace el dibujo. El código incluye la biblioteca C4-PlantUML desde una dirección de GitHub, así que quien lo renderice necesita acceso a internet. ^[10]

Guardar, abrir e importar

• Salvar projeto (.json) (guardar proyecto) descarga todos los diagramas en un archivo .c4.json.
• Abrir projeto (.json)… (abrir proyecto) reemplaza el proyecto actual por el del archivo. Se puede deshacer.
• Importar diagramas em novas abas (.json)… (importar diagramas en pestañas nuevas) añade diagramas sin tocar los actuales. Una ventana permite elegir cuáles entran y renombrarlos. Arrastrar un .json al área de dibujo hace lo mismo. Es la forma de juntar el trabajo de los compañeros o traer diagramas generados por IA.

La app no tiene un campo para el nombre del proyecto, que se usa en el título de la documentación y en el nombre del archivo. Un proyecto nuevo se llama “Projeto”. Para cambiarlo, edita el campo "name" del .json guardado y vuelve a abrirlo.

Prompts de IA

Una IA ayuda a salir de la página en blanco, a extraer elementos de documentación dispersa y a revisar un diagrama según las reglas del C4. También se equivoca con seguridad: inventa sistemas, invierte flechas y confunde contenedores con componentes. Trata su respuesta como un borrador. Para escribir mejores prompts, consulta el tutorial de prompts.

Antes de pegar: los diagramas de arquitectura revelan nombres de servidores, proveedores y puntos débiles. Quita direcciones, contraseñas y nombres internos, y sigue la política de tu organización sobre el uso de IA. La app no envía nada a la red, pero el servicio de IA recibe todo lo que pegues.

Sustituye las partes entre corchetes y pega en la herramienta de IA que uses. Si la IA responde en español, los nombres generados también lo estarán; la app acepta cualquier idioma.

1. Entrevistar para armar el contexto

Hace que la IA pregunte en lugar de suponer. Es el mejor comienzo cuando el sistema solo existe en la cabeza de las personas.

Eres un arquitecto de software que usa el modelo C4 (c4model.com).
Quiero dibujar el diagrama de contexto de este sistema: [descríbelo en pocas frases].

Antes de proponer cualquier diagrama, entrevístame:
- Haz una pregunta a la vez y espera mi respuesta.
- Averigua quién usa el sistema (personas y roles) y para qué, con qué sistemas externos intercambia datos, en qué sentido y por qué medio, y quién es el dueño de cada sistema externo.
- Pregunta también qué pasa cuando cada sistema externo está caído.
- No inventes respuestas. Si no lo sé, regístralo como pendiente.

Al final, entrega:
1. Tabla de elementos: nombre, tipo C4 (Persona, Sistema de Software o Sistema externo) y descripción de una frase.
2. Tabla de relaciones: origen, destino, etiqueta con un verbo en el sentido de la flecha, tecnología o protocolo.
3. Lista de pendientes.

2. Extraer contenedores de material existente

Para README, wiki, archivos docker-compose o actas. Pide el origen de cada elemento, lo que facilita la comprobación.

A partir del material de abajo, extrae los elementos de un diagrama de contenedores C4 del sistema [nombre].

Reglas:
- En el C4, un contenedor es una aplicación o un almacén de datos que corre por separado. No es lo mismo que un contenedor Docker. Las bibliotecas y los módulos internos no son contenedores.
- Usa solo lo que está en el material. Para cada elemento, cita el fragmento de origen.
- Marca como [SUPOSICIÓN] todo lo que dedujiste.

Entrega:
1. Personas y sistemas externos.
2. Contenedores: nombre, clase (aplicación web, API, base de datos, cola, tarea programada...), tecnología y responsabilidad en una frase.
3. Relaciones: origen → destino, etiqueta y protocolo.
4. Contradicciones y lo que falta saber.

Material:
"""
[pega aquí, sin contraseñas, direcciones internas ni datos personales]
"""

3. Generar el JSON para C4 Studio

Produce un archivo que la app puede importar. Guarda la respuesta en un archivo de texto con la extensión .c4.json y usa Arquivo → Importar diagramas em novas abas (.json)…, o arrastra el archivo al área de dibujo. Después ordena el dibujo y ejecuta la simulación de fallos. Deja "Sistema de Software" escrito exactamente así, en portugués: la app usa ese texto para exportar la frontera como System_Boundary.

Genera un archivo JSON para C4 Studio con dos diagramas C4 de este sistema: uno de contexto y uno de contenedores.
Sistema: [describe el sistema o pega las tablas de los prompts 1 y 2].

Responde solo con el JSON, en este formato:
{
  "format": "c4studio",
  "version": 1,
  "name": "[nombre del proyecto]",
  "diagrams": [
    {
      "id": "d1", "title": "...", "level": "context",
      "desc": "...", "notes": "...", "legend": true,
      "nodes": [
        {"id": "n1", "type": "person", "name": "...", "tech": "", "desc": "...", "x": 0, "y": 0, "w": 200, "h": 190}
      ],
      "edges": [
        {"id": "r1", "from": "n1", "to": "n2", "label": "...", "tech": "...", "style": "dashed", "both": false, "soft": false}
      ]
    }
  ]
}

Reglas:
- level: context o container (otros valores aceptados: landscape, component, code, dynamic, deployment).
- type: person, person_ext, system, system_ext, container, database, queue, webapp, component, code o boundary.
- Tamaños (w × h): person 200×190; system y system_ext 240×150; container 240×150; database 240×160; queue 260×130; webapp 240×160; component 230×140.
- En el diagrama de contenedores, envuelve los contenedores del sistema con un nodo "boundary" con "tech": "Sistema de Software" y ponlo primero en la lista de nodos. Los contenedores quedan completamente dentro de él; las personas y los sistemas externos quedan fuera.
- x e y en múltiplos de 10, con al menos 140 de separación entre elementos. Personas arriba; sistemas externos abajo o a la derecha.
- ids únicos en cada diagrama; from y to siempre apuntan a nodos del mismo diagrama.
- Una relación A → B significa "A depende de B" o "A llama a B". Etiqueta específica, con verbo (evita "Usa"). En los contenedores, indica la tecnología o el protocolo en "tech".
- Todo contenedor tiene "tech", y toda descripción es una frase corta.
- "soft": true solo cuando el fallo del destino no impide que el origen funcione, como un envío asíncrono de correo.
- En "notes", lista las suposiciones que hiciste.

4. Revisar con la lista de comprobación del C4

Pega el Markdown de Documentar → Copiar Markdown, sin imágenes. La IA mira el sentido, que las comprobaciones automáticas no ven.

Revisa la documentación de arquitectura de abajo, generada por C4 Studio, con las reglas de notación y la lista de comprobación del modelo C4. La documentación puede estar en portugués; responde en español.

Comprueba:
1. ¿Están claros el título, el tipo y el alcance de cada diagrama?
2. ¿Cada elemento tiene nombre, tipo, descripción y, si es contenedor o componente, tecnología?
3. ¿Cada relación tiene una etiqueta específica, coherente con el sentido de la flecha (sin un "Usa" genérico), y un protocolo cuando une procesos distintos?
4. ¿El nivel de detalle corresponde al tipo de diagrama? Por ejemplo: clases en un diagrama de contenedores.
5. ¿Hay elementos aislados, siglas sin explicar o responsabilidades repetidas?
6. ¿Los diagramas se contradicen, con nombres o relaciones distintos para lo mismo?

Para cada problema, indica: diagrama, elemento o relación, problema, corrección sugerida y gravedad (alta, media o baja). Separa la certeza de la sospecha. No inventes datos sobre el sistema; si dependen de ellos, pregunta.

Documentación:
"""
[pega el Markdown]
"""

5. Explicar la arquitectura a quien no es técnico

Útil para validar el diagrama de contexto con responsables y usuarios.

Explica la arquitectura de abajo a [público, por ejemplo: dirección, atención al cliente, auditoría], sin jerga técnica.

Entrega:
- En tres frases: qué hace el sistema, quién lo usa y de qué otros sistemas depende.
- Una lista "qué pasa cuando...": para cada sistema externo y cada base de datos, el efecto de que esté caído.
- Un glosario breve para los términos que no se puedan evitar.
- Cinco preguntas para que yo compruebe con ese público si el dibujo corresponde a lo que conoce.

Usa solo lo que está en la documentación. Si algo es ambiguo, dilo.

Documentación:
"""
[pega el Markdown, sin las imágenes]
"""

6. Tratar los puntos únicos de fallo

Lleva el resultado de la simulación a una conversación sobre resiliencia.

C4 Studio analizó el diagrama de contenedores de abajo y señaló los puntos únicos de fallo listados.
En la simulación, una relación A → B significa "A depende de B". Las dependencias del mismo tipo y la misma tecnología cuentan como redundantes, y las relaciones marcadas como no bloqueantes solo degradan el origen.

Puntos únicos de fallo:
[pega la lista de Simular → Falhas → Encontrar pontos únicos de falha]

Diagrama:
"""
[pega el Markdown de la documentación, sin las imágenes]
"""

Para cada punto único de fallo, propone hasta dos mitigaciones (redundancia, cola, caché, modo degradado, tiempo de espera con alternativa), con un coste relativo (bajo, medio o alto) y lo que cambia en el diagrama: elementos nuevos, relaciones nuevas o relaciones que pasan a ser no bloqueantes.
Di qué puntos dejarías como están y por qué. No supongas requisitos de disponibilidad que no te he dado: pregunta.

7. Registrar una decisión de arquitectura

El texto resultante cabe en el campo Notas para a documentação del diagrama y entra en el documento generado.

Escribe un registro de decisión de arquitectura (ADR) breve para esta decisión: [p. ej.: poner una cola entre la API y el envío de avisos].

Contexto del sistema: [pega la descripción del diagrama de contenedores o el Markdown sin imágenes].

Formato:
- Título
- Estado: propuesta
- Contexto: el problema y las restricciones, en hasta cinco frases
- Decisión
- Consecuencias: positivas, negativas y riesgos
- Alternativas consideradas, con el motivo del rechazo
- Impacto en los diagramas C4: elementos y relaciones que entran, salen o cambian

Como máximo 300 palabras. Marca con [CONFIRMAR] lo que supusiste.

8. Bajar a los componentes a partir del código

Para cuando un contenedor merece el tercer nivel. Después, pide al prompt 3 el JSON con "level": "component".

Quiero el diagrama de componentes C4 del contenedor [nombre], hecho en [tecnología]. Abajo están la estructura de carpetas y los archivos principales.

Recuerda: en el C4, un componente es una agrupación de funcionalidades relacionadas detrás de una interfaz bien definida, dentro de un único contenedor, y no se despliega por separado.

Entrega:
1. Componentes: nombre, tecnología, responsabilidad en una frase y los archivos o carpetas que lo forman.
2. Relaciones entre componentes y con elementos de fuera del contenedor (otros contenedores, bases de datos, sistemas externos): origen → destino, etiqueta y protocolo cuando lo haya.
3. Partes del código que no encajan en ningún componente o que parecen pertenecer a más de uno.

Prefiere entre 5 y 12 componentes. No listes las clases una por una.

Estructura:
"""
[pega el árbol de carpetas y los fragmentos relevantes, sin secretos]
"""

Qué se probó en estos prompts

Se probó el formato del prompt 3: un JSON escrito por Claude con estas reglas, para una clínica veterinaria, se importó por el menú de la app (2 diagramas, con 5 y 9 elementos), simuló fallos y exportó C4-PlantUML sin errores. En esa prueba la separación entre elementos era de 100 y algunas etiquetas de relación quedaron superpuestas; por eso el prompt pide 140. Aun así, cuenta con retocar el dibujo a mano. Los demás prompts no se ejecutaron, y las respuestas cambian cada vez y de una IA a otra.

Buenas prácticas y errores comunes

Repaso rápido

Intenta responder antes de abrir.

Abrir C4 Studio →

Referencias

1. Simon Brown. The C4 model for visualising software architecture e Introduction. Fuente de la analogía con los mapas, de la independencia de notación y de la licencia Creative Commons Atribución 4.0.
2. Simon Brown. Abstractions, con las páginas de software system, container, component y code.
3. Simon Brown. Diagrams, con las páginas de los diagramas de contexto, contenedores, componentes, código, panorama, dinámico y despliegue. Fuente del alcance, el público y la recomendación de cada diagrama.
4. Simon Brown. Notation y Review checklist.
5. Simon Brown. FAQ. Fuente de la autoría, las raíces en 2006–2009, los nombres de 2010 y el nombre “C4” en 2011. Sitúa el cambio de “classes” a “code” en 2015–2016, lo que difiere de la página de historia [6].
6. Simon Brown. History. Sitúa el primer uso del nombre “C4” en la QCon London de 2011 y el cambio definitivo de “Classes” a “Code” en una charla de marzo de 2018.
7. Simon Brown. The C4 Model for Software Architecture. InfoQ, 25 de junio de 2018.
8. Wikipedia. C4 model. Sitúa la creación entre 2006 y 2011, un rango más amplio que el de las FAQ [5], y atribuye la popularización al sitio oficial y al artículo de 2018.
9. Philippe Kruchten. Architectural Blueprints — The “4+1” View Model of Software Architecture. IEEE Software, 12(6), noviembre de 1995, pp. 42–50.
10. plantuml-stdlib. C4-PlantUML, bajo licencia MIT. Fuente de las macros usadas en la exportación.
11. Simon Brown. Software Architecture for Developers. Leanpub. La página del libro presenta al autor como creador del modelo C4 y fundador de Structurizr.