Architecture as code traz o mesmo rigor que infrastructure-as-code trouxe para operacoes. Este guia cobre o que e AaC, por que supera abordagens apenas visuais, exemplos reais em YAML e DSL, workflows de controle de versao, integracao com CI/CD e como o Archyl torna isso pratico.

Architecture as Code: Defina Seu Design de Sistema Programaticamente

Existe um padrao em engenharia de software que se repete a cada poucos anos. Uma pratica que era manual e visual se torna codificada, versionada e automatizada -- e tudo melhora.

Aconteceu com infraestrutura. Saimos de clicar em consoles de cloud para escrever arquivos Terraform. Aconteceu com configuracao. Saimos de editar arquivos de config em servidores para declarar estado desejado em manifestos Kubernetes. Aconteceu com schemas de banco de dados. Saimos de executar scripts SQL manualmente para escrever arquivos de migracao.

Agora esta acontecendo com documentacao de arquitetura. Architecture as code e a pratica de definir seu design de sistema programaticamente -- em arquivos de texto estruturados que podem ser versionados, revisados, testados e deployados pelos mesmos pipelines do seu codigo de aplicacao.

Este guia cobre tudo que voce precisa saber sobre architecture as code: o que e, por que importa, como se compara a abordagens apenas visuais e como implementar na pratica.

O Que e Architecture as Code?

Architecture as code (AaC) e a pratica de definir sua arquitetura de software em arquivos de texto legiveis por maquina e escriveis por humanos. Em vez de desenhar caixas e setas em uma ferramenta visual, voce descreve seus systems, containers, components e seus relationships em um formato estruturado como YAML, JSON ou uma DSL dedicada.

Aqui esta um exemplo simples de uma arquitetura definida em YAML:

version: "1.0"

project:
  name: "Payment Platform"
  description: "Lida com todo o processamento de pagamentos da organizacao"

systems:
  - name: Payment Platform
    type: software_system
    description: "Sistema principal de processamento de pagamentos"
    containers:
      - name: Payment API
        type: api
        description: "REST API para operacoes de pagamento"
        technologies: [Go, gRPC, OpenAPI]
      - name: Payment Processor
        type: service
        description: "Processa transacoes de pagamento"
        technologies: [Go]
      - name: Transaction Database
        type: database
        description: "Armazena registros de transacoes"
        technologies: [PostgreSQL]
      - name: Payment Queue
        type: queue
        description: "Fila de processamento assincrono de pagamentos"
        technologies: [Kafka]

  - name: Stripe
    type: external_system
    description: "Gateway de pagamento de terceiros"

relationships:
  - from: Payment API
    to: Payment Processor
    label: "Encaminha requisicoes de pagamento"
    type: uses
  - from: Payment Processor
    to: Transaction Database
    label: "Persiste transacoes"
    type: writes_to
  - from: Payment Processor
    to: Payment Queue
    label: "Publica eventos de pagamento"
    type: publishes_to
  - from: Payment Processor
    to: Stripe
    label: "Cobra cartoes via"
    type: uses

Este arquivo e a fonte completa de verdade para a arquitetura. Uma ferramenta como o Archyl o le, constroi o modelo C4, renderiza diagramas interativos e mantem tudo sincronizado. O arquivo vive no seu repositorio Git, ao lado do codigo que ele descreve.

Por Que Abordagens Apenas Visuais Ficam Aquem

Antes do architecture as code, equipes tipicamente documentavam sua arquitetura usando ferramentas visuais -- Lucidchart, draw.io, Miro ou Figma. Essas ferramentas sao excelentes para brainstorming e sessoes iniciais de design, mas tem limitacoes fundamentais como documentacao de longo prazo:

Sem Controle de Versao

Diagramas visuais sao armazenados como arquivos binarios ou proprietarios que nao podem ter diff significativo. Quando alguem muda um diagrama, voce pode ver que mudou, mas nao pode ver o que mudou. Nao existe equivalente a git diff para um arquivo draw.io. Voce nao pode revisar uma mudanca de diagrama em um pull request da mesma forma que revisa uma mudanca de codigo.

Com architecture as code, toda mudanca e um diff de texto. Adicionar um novo servico sao algumas linhas de YAML. Renomear um componente e uma mudanca de uma unica linha. Revisores podem ver exatamente o que mudou, por que mudou (pela mensagem de commit) e aprovar ou solicitar modificacoes.

Sem Automacao

Diagramas visuais existem isoladamente. Eles nao podem disparar acoes, validar regras ou integrar com pipelines de CI/CD. Se seu diagrama diz que voce tem 10 servicos mas seu cluster Kubernetes roda 12, nada detecta a discrepancia.

Architecture as code habilita automacao. Voce pode escrever regras de validacao que verificam sua definicao de arquitetura contra sua infraestrutura real. Voce pode gerar documentacao a partir do arquivo de arquitetura. Voce pode disparar alertas quando o arquivo de arquitetura diverge da realidade.

Sem Colaboracao em Escala

Quando duas pessoas editam o mesmo diagrama visual simultaneamente, conflitos sao geralmente resolvidos pelas mudancas de uma pessoa sobrescrevendo as da outra. Nao ha estrategia de merge para arquivos visuais.

Com architecture as code, workflows padrao de merge do Git se aplicam. Duas equipes podem modificar partes diferentes do arquivo de arquitetura, e o Git faz o merge limpo. Quando conflitos ocorrem, sao resolvidos da mesma forma que conflitos de codigo -- atraves de discussao e resolucao intencional.

Sem Garantias de Consistencia

Um diagrama visual pode conter qualquer coisa. Caixas podem ser rotuladas inconsistentemente. Setas podem significar coisas diferentes em partes diferentes do mesmo diagrama. Nao ha schema, validacao ou aplicacao de convencoes de nomenclatura.

Arquivos architecture as code tem um schema. A ferramenta valida o arquivo a cada mudanca. Se voce referencia um container que nao existe, a validacao captura. Se voce usa um tipo de relationship invalido, e sinalizado antes da mudanca ser mergeada.

Lock-in e Portabilidade

Diagramas visuais sao frequentemente vinculados a ferramenta que os criou. Migrar do Lucidchart para draw.io significa recriar manualmente cada diagrama. Migrar de uma ferramenta architecture-as-code para outra e uma conversao de formato -- automatizada e repetivel.

Os Beneficios do Architecture as Code

Fonte Unica de Verdade

Quando sua arquitetura e definida em um unico arquivo (ou conjunto de arquivos), ha exatamente um lugar para consultar. Nao ha duvida sobre qual diagrama e o atual, qual pagina do Confluence tem a versao mais recente ou se o PDF que alguem enviou por email no mes passado ainda esta preciso.

Code Review para Mudancas de Arquitetura

Este e talvez o beneficio mais transformador. Quando mudancas de arquitetura passam por pull requests, recebem o mesmo escrutinio que mudancas de codigo. Um arquiteto senior pode revisar uma proposta de divisao de servico antes de acontecer. A equipe pode discutir as implicacoes de uma nova dependencia antes de ser introduzida.

+ - name: Notification Service
+   type: service
+   description: "Lida com notificacoes por email, SMS e push"
+   technologies: [Python, Celery, Redis]
+
+ - from: Order Service
+   to: Notification Service
+   label: "Dispara notificacoes de pedidos"
+   type: uses

Esse diff conta uma historia clara: alguem esta adicionando um Notification Service e conectando-o ao Order Service. Revisores podem fazer perguntas, sugerir tecnologias alternativas ou propor limites de servico diferentes -- tudo antes de uma unica linha de codigo de aplicacao ser escrita.

Historico do Git e Historico da Arquitetura

Cada commit no seu arquivo de arquitetura cria um registro permanente de como a arquitetura evoluiu. Voce pode responder perguntas como:

Quando o Search Service foi adicionado?
Quem aprovou a migracao de MySQL para PostgreSQL?
Como era a arquitetura seis meses atras?
Como o numero de servicos cresceu ao longo do tempo?

Esse historico e inestimavel para entender a evolucao do seu sistema e para o onboarding de novos membros da equipe.

Integracao com CI/CD

Architecture as code se integra naturalmente em pipelines de integracao e deploy continuos. Em cada pull request, voce pode:

Validar o arquivo de arquitetura contra seu schema
Verificar regras de conformidade (ex.: todo servico deve ter um owner documentado)
Gerar diagramas atualizados
Detectar drift entre a arquitetura documentada e o sistema em execucao
Publicar a arquitetura na sua plataforma de documentacao

Isso torna a documentacao de arquitetura um artefato vivo em vez de um documento estatico que decai.

Refatoracao e Automacao

Como definicoes de arquitetura sao dados estruturados, voce pode escrever scripts para manipula-los. Precisa renomear um servico em todos os relationships? Um simples find-and-replace em um arquivo YAML. Precisa gerar um relatorio de todos os servicos usando PostgreSQL? Parse o YAML e filtre por tecnologia. Precisa aplicar uma convencao de nomenclatura? Escreva um linter.

Formatos e DSLs de Architecture as Code

Varios formatos e DSLs existem para definir architecture as code. Aqui esta uma visao geral das abordagens mais comuns.

Structurizr DSL

Criada por Simon Brown (o criador do modelo C4), a Structurizr DSL e um dos primeiros formatos de architecture-as-code. Ela usa uma sintaxe DSL customizada:

workspace {
    model {
        user = person "User"
        softwareSystem = softwareSystem "My Software System" {
            webapp = container "Web Application" "Delivers content" "Java"
            database = container "Database" "Stores data" "PostgreSQL"
        }
        user -> webapp "Uses"
        webapp -> database "Reads from and writes to"
    }
    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }
    }
}

A Structurizr foi pioneira no conceito de architecture as code para modelos C4. No entanto, sua sintaxe DSL customizada tem uma curva de aprendizado, e requer ferramentas especificas da Structurizr para renderizar.

Abordagens Baseadas em YAML

YAML se tornou o padrao de fato para configuracao declarativa em DevOps (Kubernetes, Docker Compose, GitHub Actions, Terraform HCL a parte). Usar YAML para definicoes de arquitetura tem a vantagem da familiaridade -- a maioria dos desenvolvedores ja sabe ler e escrever YAML.

O formato archyl.yaml do Archyl adota essa abordagem:

version: "1.0"

systems:
  - name: E-Commerce Platform
    type: software_system
    containers:
      - name: Web Frontend
        type: webapp
        technologies: [React, TypeScript, Next.js]
      - name: API Service
        type: api
        technologies: [Go, gRPC]
        components:
          - name: Auth Handler
            type: handler
            technologies: [JWT, OAuth2]
          - name: Product Handler
            type: handler
            technologies: [REST]
      - name: Product Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: Web Frontend
    to: API Service
    label: "Faz chamadas de API para"
  - from: API Service
    to: Product Database
    label: "Le/escreve dados de produtos"

O aninhamento espelha diretamente a hierarquia C4: systems contem containers, containers contem components. Relationships usam nomes legiveis com notacao de ponto para desambiguacao. O formato e pesquisavel via grep, permite diff e nao requer ferramentas especializadas para leitura.

JSON e Outros Formatos

Algumas ferramentas usam JSON, TOML ou outros formatos estruturados. O formato especifico importa menos do que os principios: a definicao de arquitetura deve ser baseada em texto, versionavel e parseavel por maquina.

Implementando Architecture as Code: Um Workflow Pratico

Aqui esta um workflow passo a passo para adotar architecture as code na sua equipe.

Passo 1: Comece com o Que Existe

Nao tente documentar toda a sua arquitetura no primeiro dia. Comece com o diagrama de Container -- o panorama de servicos. Liste todo servico deployavel, sua stack tecnologica e os principais relationships entre servicos.

Se voce esta usando o Archyl, pode criar o modelo visualmente na UI e depois exportar como archyl.yaml, ou escrever o arquivo YAML do zero. Ambos os caminhos levam ao mesmo resultado.

Passo 2: Commite no Seu Repositorio

Coloque o arquivo de arquitetura na raiz do seu repositorio principal (ou em um repositorio de arquitetura dedicado se seu codebase esta dividido em muitos repos). A localizacao importa menos do que o principio: o arquivo deve viver no Git e passar por code review.

my-platform/
  archyl.yaml        # Definicao de arquitetura
  src/
  docker-compose.yml
  .github/
    workflows/
      architecture.yml  # Pipeline de CI para arquitetura

Passo 3: Configure a Sincronizacao via CI/CD

Configure seu pipeline de CI/CD para sincronizar o arquivo de arquitetura com o Archyl a cada merge na branch principal. Isso garante que os diagramas visuais e a documentacao interativa no Archyl sempre reflitam a arquitetura commitada mais recente.

Um workflow de GitHub Actions pode ser assim:

name: Sync Architecture

on:
  push:
    branches: [main]
    paths: [archyl.yaml]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to Archyl
        run: |
          curl -X POST https://api.archyl.com/v1/sync \
            -H "Authorization: Bearer ${{ secrets.ARCHYL_TOKEN }}" \
            -H "Content-Type: application/yaml" \
            --data-binary @archyl.yaml

Passo 4: Faca Mudancas de Arquitetura Atraves de Pull Requests

A partir deste ponto, mudancas de arquitetura seguem o mesmo workflow que mudancas de codigo:

Crie uma branch
Modifique o arquivo archyl.yaml
Abra um pull request
Obtenha revisao da equipe
Faca merge na main
CI/CD sincroniza a mudanca para o Archyl

Isso da as mudancas de arquitetura a mesma visibilidade, responsabilidade e rastreabilidade que mudancas de codigo.

Passo 5: Adicione Regras de Conformidade

Conforme sua pratica de architecture-as-code amadurece, adicione regras de conformidade que validam a definicao de arquitetura automaticamente. Exemplos:

Todo container deve ter pelo menos uma tecnologia especificada
Todo external system deve ter uma descricao
Sem containers orfaos (todo container deve ter pelo menos um relationship)
Convencoes de nomenclatura sao seguidas (ex.: servicos terminam com "Service")

O motor de regras de conformidade do Archyl pode avaliar essas regras automaticamente e reportar violacoes no pipeline de CI ou no dashboard do Archyl.

Passo 6: Evolua a Definicao ao Longo do Tempo

Comece com systems e containers. Adicione components quando servicos especificos se tornarem complexos o suficiente para justificar documentacao interna. Adicione ADRs conforme toma decisoes arquiteturais importantes. Adicione contratos de API conforme formaliza limites de servico.

O arquivo de arquitetura cresce organicamente com seu sistema. Nao ha necessidade de antecipar todos os detalhes.

Architecture as Code vs. Infrastructure as Code

Architecture as code e infrastructure as code (IaC) sao praticas complementares mas distintas.

Infrastructure as code (Terraform, Pulumi, CloudFormation) define o que deployar e como configurar. E operacional: provisiona servidores, configura redes e gerencia recursos de cloud.

Architecture as code define como o sistema se parece e como suas partes se relacionam. E descritivo: documenta a estrutura conceitual, escolhas tecnologicas e limites de servico.

A configuracao ideal combina ambos:

Seus arquivos Terraform definem a infraestrutura
Seu archyl.yaml define a arquitetura
Regras de conformidade verificam que os dois permanecem alinhados

Quando seu Terraform adiciona um novo servico mas o arquivo de arquitetura nao o menciona, a deteccao de drift captura a discrepancia.

Architecture as Code com Assistentes de IA

Uma das vantagens mais atraentes do architecture as code e que assistentes de IA podem le-lo e raciocinar sobre ele. Quando sua arquitetura e definida em texto estruturado, ferramentas como Claude Code e Cursor podem:

Responder perguntas sobre sua arquitetura consultando o arquivo YAML
Sugerir mudancas de arquitetura baseadas no estado atual
Gerar codigo que respeita a arquitetura documentada (ex.: usando o banco de dados certo para o servico certo)
Detectar inconsistencias entre o codigo e a definicao de arquitetura

O Archyl leva isso adiante com seu servidor MCP. Assistentes de IA nao apenas leem o arquivo de arquitetura -- eles podem consultar o modelo de arquitetura ao vivo, percorrer relationships e ate propor modificacoes. A arquitetura se torna uma fonte de dados programavel e consultavel em vez de um documento estatico.

Armadilhas Comuns

Excesso de Engenharia no Formato

Nao projete uma DSL customizada quando YAML ou um formato existente funciona. O objetivo e adocao, e adocao e mais facil quando o formato e familiar. A maioria dos desenvolvedores ja conhece YAML do Docker Compose, Kubernetes e configuracoes de CI/CD.

Tentar Capturar Tudo

Architecture as code deve capturar os aspectos estruturais do seu sistema: o que existe, como as coisas se conectam e quais tecnologias sao usadas. Nao tente embutir detalhes operacionais (como politicas de escalabilidade), configuracoes de runtime (como variaveis de ambiente) ou especificacoes comportamentais (como formatos de resposta de API) no arquivo de arquitetura.

Nao Aplicar o Workflow

Architecture as code so funciona se mudancas passarem pelo workflow definido. Se pessoas contornam o arquivo de arquitetura e fazem mudancas diretamente na ferramenta visual, o arquivo fica obsoleto. Estabeleca convencoes claras sobre qual direcao e autoritativa.

Ignorar a Saida Visual

Architecture as code nao e um substituto para diagramas visuais -- e uma forma melhor de produzi-los. O arquivo de texto e a fonte de verdade, mas os diagramas renderizados sao o que as pessoas realmente olham no dia a dia. Certifique-se de que a saida visual e acessivel, atualizada e facil de navegar.

Comecando com o Archyl

O Archyl e projetado desde o inicio para suportar architecture as code. A plataforma fornece:

DSL baseada em YAML que cobre o modelo C4 completo com systems, containers, components, relationships e technologies
Sincronizacao bidirecional -- modele visualmente na UI e exporte para YAML, ou escreva YAML e sincronize para a UI
Integracao com CI/CD para sincronizacao automatizada a cada commit
Regras de conformidade que validam a definicao de arquitetura contra seus padroes
Servidor MCP que torna a arquitetura consultavel por assistentes de IA
Recursos de colaboracao com code review, comentarios e ownership de equipe

Esteja voce comecando do zero ou migrando de diagramas visuais, o Archyl torna architecture as code pratico para equipes de qualquer tamanho.

Comece com architecture as code e traga o mesmo rigor para sua documentacao de arquitetura que voce ja traz para sua infraestrutura e codigo de aplicacao.

Architecture as Code: Defina Seu Design de Sistema Programaticamente - Archyl Blog