Modelo C4 em YAML: o formato archyl.yaml e o fluxo com Git

Diagramas de arquitetura têm um problema de prazo de validade. Você os desenha depois de uma sessão de design, eles ficam ótimos por uma semana, e depois o código evolui enquanto os diagramas apodrecem. Seis meses depois, o recém-contratado encara um diagrama de Containers que mostra três serviços que foram fundidos no Q2 e não menciona os dois que foram criados no Q3.

No Archyl, somos obcecados por esse problema desde o primeiro dia. A descoberta por IA ajuda a manter tudo atualizado. O editor visual torna as atualizações indolores. Mas existe um tipo de equipe (as que tratam infraestrutura como código, políticas como código, tudo como código) que queria algo mais fundamental.

Elas queriam que a arquitetura vivesse no Git, ao lado do código que ela descreve. Hoje, é exatamente isso que estamos lançando.

Este post é a referência do arquivo em si: o que vai nele, como as referências são resolvidas e como ele sincroniza. Para os argumentos mais amplos a favor de architecture as code, e a comparação com formatos como a Structurizr DSL, leia o guia de architecture as code.

O que é o archyl.yaml?

É um único arquivo YAML que descreve de forma declarativa a sua arquitetura completa. Coloque-o na raiz do repositório e ele passa a ser a fonte da verdade do seu modelo C4 no Archyl.

Veja como fica um arquivo mínimo:

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

É só isso. O Archyl lê esse arquivo, monta o modelo C4 completo, renderiza os diagramas e mantém tudo sincronizado. Sem clicar em interfaces, sem sincronização manual, sem "esqueci de atualizar o diagrama".

Chaves de nível superior

No nível superior, só version é obrigatório. Todo o resto é opcional, então um arquivo pode começar com um sistema e crescer.

Tudo em um arquivo só

A DSL não é um subconjunto simplificado: ela cobre tudo o que o Archyl consegue modelar.

Os quatro níveis C4. Sistemas contêm containers, containers contêm componentes, componentes contêm elementos de código. O aninhamento do YAML espelha diretamente a hierarquia.

Relacionamentos com notação de ponto. Conecte quaisquer dois elementos com referências legíveis como Payment Service.API Gateway → Payment Service.Database. Sem UUIDs, sem identificadores enigmáticos. Fáceis de buscar com grep, bons para diff, legíveis por humanos.

Tecnologias, ambientes e releases. Defina seu catálogo de tecnologias, declare os ambientes de deployment (staging, produção) e acompanhe as releases, tudo no mesmo arquivo.

ADRs e documentação. Escreva seus Architecture Decision Records inline ou aponte para uma pasta no repositório. O mesmo vale para a documentação do projeto.

Contratos de API e canais de eventos. Declare suas especificações OpenAPI, definições gRPC, tópicos Kafka, e vincule-os aos componentes que os expõem ou consomem.

Overlays visuais. Agrupe elementos no diagrama com overlays nomeados, controlando cores e níveis.

Suporte a monorepo. Use include para dividir sua arquitetura em vários arquivos (um por serviço, equipe ou bounded context), e o Archyl os mescla automaticamente.

Por que YAML?

Consideramos criar uma sintaxe DSL própria (como a DSL do Structurizr ou o HCL do Terraform). Escolhemos YAML por razões práticas:

1. Curva de aprendizado zero. Todo desenvolvedor já conhece YAML. Nenhuma sintaxe nova para aprender, nenhum parser para instalar, nenhum plugin de editor necessário.

2. Suporte de IDE de graça. Publicamos um JSON Schema em /api/v1/dsl/schema. Aponte seu IDE para ele e você ganha autocompletar, validação e documentação inline sem nenhuma ferramenta específica do Archyl.

3. Bom para diff. Diffs de YAML são limpos e legíveis em pull requests. Quem revisa vê na hora "ah, adicionaram um novo container ao Payment Service e ligaram ao Redis".

4. Ecossistema de ferramentas. Linters, formatadores, motores de template (Helm, Kustomize): todos funcionam com YAML sem configuração.

O fluxo nativo do Git

É aqui que está a força de verdade. Como o archyl.yaml vive no seu repositório, as mudanças de arquitetura seguem o mesmo fluxo das mudanças de código:

1. Branch. Crie uma feature branch e edite o YAML.
2. Review. Abra um pull request. Sua equipe revisa a mudança de arquitetura junto com a mudança de código.
3. Merge. Depois de aprovado, faça o merge na main.
4. Sync. O Archyl recebe a mudança e atualiza os diagramas automaticamente.

Chega de "o diagrama diz X mas o código faz Y". Chega de mudanças de arquitetura que pulam a revisão. Chega de documentação que ninguém sabe que foi atualizada.

Integração com CI/CD

Construímos uma integração de primeira classe com pipelines de CI/CD. Para o GitHub, oferecemos uma GitHub Action oficial que cuida de tudo: lê o arquivo, chama a API e informa o que mudou.

GitHub Actions (action oficial):

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

É só isso. Três linhas de configuração e sua arquitetura fica sincronizada a cada push. A action suporta caminhos de arquivo personalizados (para monorepos), instâncias self-hosted do Archyl, e expõe saídas como summary, systems-created e relationships-created para os passos seguintes.

GitLab CI:

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

O endpoint /ingest aceita autenticação por API key, então nenhum fluxo OAuth é necessário no CI. Ele importa o modelo completo, cria ou atualiza cada elemento e devolve um resumo detalhado do que mudou.

Você também pode sincronizar direto pela interface do Archyl. Se o seu projeto tem um repositório Git conectado, clique em "Sync Now" nas configurações de Architecture as Code e o Archyl busca o arquivo diretamente do seu repositório.

Bidirecional: exportar e importar

O fluxo não é de mão única. Já tem um projeto modelado no editor visual do Archyl? Exporte-o:

• Export gera um archyl.yaml completo a partir do seu modelo atual. Cada sistema, container, componente, relacionamento, overlay, ADR, contrato de API, canal de eventos, release: tudo serializado em YAML limpo.
• Import lê um archyl.yaml e cria ou atualiza todos os elementos do seu projeto. É idempotente: importar o mesmo arquivo duas vezes não cria duplicatas. Os elementos são casados pelo nome e criados ou atualizados.
• Import as Project cria um projeto novo a partir de um arquivo YAML. Envie um archyl.yaml e ganhe um projeto totalmente preenchido com um clique.

Isso significa que você pode começar pela interface, exportar para YAML, fazer commit no Git e mudar para o fluxo code-first, ou fazer o caminho inverso. Não há lock-in em nenhuma das abordagens.

Resolução inteligente de referências

Uma das partes mais delicadas da DSL é resolver as referências a elementos em relacionamentos, overlays, eventos e contratos de API. Construímos um resolvedor que faz isso de forma natural:

• Nomes curtos funcionam quando não há ambiguidade: API Gateway é resolvido diretamente se só um elemento tem esse nome.
• A notação de ponto desfaz ambiguidades: Payment Service.API Gateway vs Analytics.API Gateway.
• Qualquer profundidade funciona: System.Container.Component.CodeElement para referências profundamente aninhadas.

O resolvedor indexa cada elemento em cada profundidade de caminho possível, então você sempre usa a referência mais curta sem ambiguidade. As exportações usam a mesma lógica ao contrário, produzindo as referências mais legíveis possíveis.

Validação sem efeitos colaterais

Não tem certeza se o seu YAML é válido? O endpoint /validate (e o botão "Validate" no modal de importação) lê e verifica o arquivo sem tocar no banco de dados:

• Verificação da versão do schema
• Validação dos campos obrigatórios
• Detecção de nomes duplicados
• Validação de valores enumerados (tipos de container, tipos de relacionamento etc.)
• Resolução de referências cruzadas

Os erros voltam com caminhos precisos (systems[2].containers[1].name) e mensagens claras. Ligue isso a um hook de pre-commit ou a uma verificação no CI e pegue os problemas antes que cheguem à main.

Padrões do mundo real

O monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

Cada serviço mantém o seu próprio archyl.yaml com seus containers e componentes. O arquivo raiz os mescla, e os relacionamentos entre serviços são definidos no nível raiz. Tecnologias e ambientes são deduplicados automaticamente.

O ponto de partida

Começando um projeto novo? Crie um archyl.yaml antes de escrever qualquer código. Defina os sistemas e containers que você pretende construir. Use o "Import as Project" do Archyl para gerar a arquitetura na hora. Conforme você constrói, o YAML evolui com o código.

A trilha de auditoria

Como o YAML está no Git, você ganha o histórico completo de graça. git log archyl.yaml mostra cada mudança de arquitetura, quem fez, quando, e o PR em que ela foi discutida. Tente conseguir isso de uma ferramenta de diagramas.

O gerador de documentação

Exporte sua arquitetura para YAML e passe por qualquer motor de template para gerar documentação em Markdown, páginas do Confluence ou wikis internos. O formato estruturado torna a automação trivial.

O que vem a seguir

Esta é a versão 1.0 do formato da DSL. Veja no que estamos trabalhando:

Detecção de drift. Comparar o YAML do seu repositório com o modelo ao vivo e destacar as diferenças: elementos adicionados na interface mas não no arquivo, ou o contrário.

Comentários de pré-visualização em PRs. Quando um PR altera o archyl.yaml, um bot comenta com um diff visual do que mudou na arquitetura.

Evolução do schema. À medida que adicionarmos recursos ao Archyl, a DSL vai crescer. Vamos manter a retrocompatibilidade e oferecer ferramentas de migração.

Experimente agora

Architecture as Code está disponível hoje em todos os planos do Archyl. Se você já tem um projeto:

1. Vá até a página Architecture as Code do seu projeto
2. Clique em Export para gerar o seu archyl.yaml
3. Faça commit dele no seu repositório
4. Adicione a GitHub Action oficial ao seu workflow e pronto

Se você está começando do zero, crie um archyl.yaml, use Import as Project e em segundos terá uma arquitetura C4 totalmente renderizada.

Sua arquitetura merece o mesmo rigor que o seu código. Versione, revise, automatize.

Novo no C4? Comece pelo nosso guia do modelo C4. Quer que a IA gere a arquitetura inicial? Veja Descoberta de arquitetura com IA. Já usa assistentes de IA? Conecte-os pelo nosso servidor MCP.