Acabamos de lançar a funcionalidade que transforma a documentação de arquitetura em um cidadão de primeira classe do seu codebase. Conheça o archyl.yaml — uma DSL declarativa que descreve seu modelo C4 completo, vive no Git, passa por code review e sincroniza automaticamente via CI/CD.

Architecture as Code: Defina seu modelo C4 completo em um arquivo YAML

Diagramas de arquitetura têm um problema de validade. Você os desenha após uma sessão de design, ficam ótimos por uma semana, e então o código evolui enquanto os diagramas apodrecem. Seis meses depois, o novo funcionário fica olhando para um diagrama de Containers que mostra três serviços que foram mesclados no Q2 e não menciona os dois que foram construídos no Q3.

Estamos obcecados com esse problema desde o primeiro dia na Archyl. A descoberta por IA ajuda a manter as coisas atualizadas. O editor visual torna as atualizações indolores. Mas existe uma categoria de equipes — aquelas que tratam infraestrutura como código, políticas como código, tudo como código — que queriam algo mais fundamental.

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

O que é o `archyl.yaml`?

É um único arquivo YAML que descreve declarativamente toda a sua arquitetura. Coloque-o na raiz do seu repositório e ele se torna a fonte de verdade do seu modelo C4 no Archyl.

Veja como um arquivo mínimo se parece:

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ê este arquivo, constrói 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".

Tudo em um único arquivo

A DSL não é um subconjunto simplificado — ela cobre todo o escopo do que o Archyl pode modelar:

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

Relacionamentos com notação de pontos. Conecte quaisquer dois elementos usando referências legíveis como Payment Service.API Gateway → Payment Service.Database. Sem UUIDs, sem identificadores crípticos. Compatível com grep, compatível com diffs, legível por humanos.

Tecnologias, ambientes e releases. Defina seu catálogo tecnológico, declare ambientes de deploy (staging, produção) e rastreie releases — tudo no mesmo arquivo.

ADRs e documentação. Inclua seus Architecture Decision Records inline ou aponte para uma pasta no seu repositório. O mesmo para 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 múltiplos arquivos — um por serviço, equipe ou bounded context — e o Archyl os mescla automaticamente.

Por que YAML?

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

Zero curva de aprendizado. Todo desenvolvedor já conhece YAML. Nenhuma nova sintaxe para aprender, nenhum parser para instalar, nenhum plugin de editor necessário.
Suporte IDE grátis. Publicamos um JSON Schema em /api/v1/dsl/schema. Aponte seu IDE e você obtém autocompletar, validação e documentação inline sem ferramentas específicas do Archyl.
Compatível com diffs. Diffs de YAML são limpos e legíveis em pull requests. Revisores veem imediatamente "ah, eles adicionaram um novo container ao Payment Service e conectaram ao Redis".
Ecossistema de ferramentas. Linters, formatadores, engines de template (Helm, Kustomize), tudo funciona com YAML nativamente.

O workflow Git-nativo

Aqui é onde reside o verdadeiro poder. Porque o archyl.yaml vive no seu repositório, mudanças de arquitetura seguem o mesmo workflow que mudanças de código:

Branch. Crie uma branch feature, edite o YAML.
Review. Abra um pull request. Sua equipe revisa a mudança de arquitetura junto com a mudança de código.
Merge. Uma vez aprovado, faça merge para main.
Sync. O Archyl detecta a mudança e atualiza os diagramas automaticamente.

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

Integração CI/CD

Construímos integração de primeira classe com pipelines CI/CD. Para o GitHub, oferecemos uma GitHub Action oficial que cuida de tudo — leitura do arquivo, chamada à API e relatório do 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 Archyl auto-hospedadas e expõe outputs como summary, systems-created e relationships-created para etapas posteriores.

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 retorna um resumo detalhado do que mudou.

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

Bidirecional: Export e Import

O workflow não é unidirecional. 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 faz o parse de um archyl.yaml e cria ou atualiza todos os elementos no seu projeto. É idempotente: importar o mesmo arquivo duas vezes não cria duplicatas. Elementos são identificados por nome e atualizados.
Import as Project cria um projeto completamente novo a partir de um arquivo YAML. Coloque um archyl.yaml e obtenha um projeto totalmente preenchido com um clique.

Isso significa que você pode começar na UI, exportar para YAML, commitar no Git e mudar para o workflow code-first — ou ir no sentido contrário. Sem lock-in em nenhuma das abordagens.

Resolução inteligente de referências

Uma das partes mais complicadas da DSL é resolver referências de elementos em relacionamentos, overlays, eventos e contratos de API. Construímos um resolver que lida com isso naturalmente:

Nomes curtos quando não há ambiguidade: API Gateway resolve diretamente se apenas um elemento tem esse nome.
Notação de pontos para desambiguar: Payment Service.API Gateway vs Analytics.API Gateway.
Qualquer profundidade funciona: System.Container.Component.CodeElement para referências profundamente aninhadas.

O resolver indexa cada elemento em cada profundidade de caminho possível, então você sempre usa a referência não ambígua mais curta. Os exports 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 seu YAML é válido? O endpoint /validate (e o botão "Validar" no modal de import) faz o parse e verifica seu arquivo sem tocar no banco de dados:

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

Erros retornam com caminhos precisos (systems[2].containers[1].name) e mensagens claras. Integre em um hook pre-commit ou check de CI e detecte problemas antes que cheguem ao 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 seu próprio archyl.yaml definindo 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 Bootstrapper

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

A trilha de auditoria

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

O gerador de documentação

Exporte sua arquitetura para YAML e passe por qualquer engine de template para gerar docs Markdown, páginas Confluence ou wikis internas. O formato estruturado torna a automação trivial.

O que vem a seguir

Esta é a versão 1.0 do formato DSL. Aqui está no que estamos trabalhando:

Detecção de drift. Comparar o YAML no seu repositório com o modelo em produção e destacar diferenças — elementos adicionados na UI mas não no arquivo, ou vice-versa.

Comentários de preview em PRs. Quando um PR modifica o archyl.yaml, um bot comenta com um diff visual do que mudou na arquitetura.

Evolução do schema. À medida que adicionamos novos recursos ao Archyl, a DSL crescerá. Manteremos compatibilidade retroativa e forneceremos 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:

Vá para a página Architecture as Code no seu projeto
Clique em Export para gerar seu archyl.yaml
Faça commit no seu repositório
Adicione a GitHub Action oficial ao seu workflow e pronto

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

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

Novo no C4? Comece com nossa Introdução ao modelo C4. Quer que a IA gere a arquitetura inicial? Veja Descoberta de arquitetura com IA. Já usa assistentes de IA? Conecte-os através do nosso Servidor MCP.

Architecture as Code: Defina seu modelo C4 completo em um arquivo YAML - Archyl Blog