Architecture as Code: Defina Seu Design de Sistema Programaticamente

Existe um padrão 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. Saímos de clicar em consoles de cloud para escrever arquivos Terraform. Aconteceu com configuração. Saímos de editar arquivos de config em servidores para declarar estado desejado em manifestos Kubernetes. Aconteceu com schemas de banco de dados. Saímos de executar scripts SQL manualmente para escrever arquivos de migração.

Agora está acontecendo com documentação de arquitetura. Architecture as code é 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 código de aplicação.

Este guia cobre tudo que você 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) é a pratica de definir sua arquitetura de software em arquivos de texto legíveis por maquina e escriveis por humanos. Em vez de desenhar caixas e setas em uma ferramenta visual, você 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 é a fonte completa de verdade para a arquitetura. Uma ferramenta como o Archyl o lê, constrói o modelo C4, renderiza diagramas interativos e mantém tudo sincronizado. O arquivo vive no seu repositório Git, ao lado do código que ele descreve.

Por Que Abordagens Apenas Visuais Ficam Aquém

Antes do architecture as code, equipes tipicamente documentavam sua arquitetura usando ferramentas visuais -- Lucidchart, draw.io, Miro ou Figma. Essas ferramentas são excelentes para brainstorming e sessões iniciais de design, mas tem limitações fundamentais como documentação de longo prazo:

Sem Controle de Versão

Diagramas visuais são armazenados como arquivos binários ou proprietários que não podem ter diff significativo. Quando alguém muda um diagrama, você pode ver que mudou, mas não pode ver o que mudou. Não existe equivalente a git diff para um arquivo draw.io. Você não pode revisar uma mudança de diagrama em um pull request da mesma forma que revisa uma mudança de código.

Com architecture as code, toda mudança é um diff de texto. Adicionar um novo serviço são algumas linhas de YAML. Renomear um componente é uma mudança de uma única linha. Revisores podem ver exatamente o que mudou, por que mudou (pela mensagem de commit) e aprovar ou solicitar modificações.

Sem Automação

Diagramas visuais existem isoladamente. Eles não podem disparar acoes, validar regras ou integrar com pipelines de CI/CD. Se seu diagrama diz que você tem 10 serviços mas seu cluster Kubernetes roda 12, nada detecta a discrepância.

Architecture as code habilita automação. Você pode escrever regras de validação que verificam sua definição de arquitetura contra sua infraestrutura real. Você pode gerar documentação a partir do arquivo de arquitetura. Você pode disparar alertas quando o arquivo de arquitetura diverge da realidade.

Sem Colaboração em Escala

Quando duas pessoas editam o mesmo diagrama visual simultaneamente, conflitos são geralmente resolvidos pelas mudanças de uma pessoa sobrescrevendo as da outra. Não há estrategia de merge para arquivos visuais.

Com architecture as code, workflows padrão 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, são resolvidos da mesma forma que conflitos de código -- através de discussão e resolução intencional.

Sem Garantias de Consistência

Um diagrama visual pode conter qualquer coisa. Caixas podem ser rotuladas inconsistentemente. Setas podem significar coisas diferentes em partes diferentes do mesmo diagrama. Não há schema, validação ou aplicação de convenções de nomenclatura.

Arquivos architecture as code têm um schema. A ferramenta valida o arquivo a cada mudança. Se você referencia um container que não existe, a validação captura. Se você usa um tipo de relationship invalido, e sinalizado antes da mudança ser mergeada.

Lock-in e Portabilidade

Diagramas visuais são 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 é uma conversão de formato -- automatizada e repetível.

Os Benefícios do Architecture as Code

Fonte Única de Verdade

Quando sua arquitetura é definida em um único arquivo (ou conjunto de arquivos), há exatamente um lugar para consultar. Não há duvida sobre qual diagrama é o atual, qual pagina do Confluence tem a versão mais recente ou se o PDF que alguém enviou por email no mes passado ainda está preciso.

Code Review para Mudanças de Arquitetura

Este e talvez o beneficio mais transformador. Quando mudanças de arquitetura passam por pull requests, recebem o mesmo escrutínio que mudanças de código. Um arquiteto senior pode revisar uma proposta de divisão de serviço antes de acontecer. A equipe pode discutir as implicações de uma nova dependência 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: alguém está adicionando um Notification Service e conectando-o ao Order Service. Revisores podem fazer perguntas, sugerir tecnologias alternativas ou propor limites de serviço diferentes -- tudo antes de uma única linha de código de aplicação ser escrita.

Histórico do Git e Histórico da Arquitetura

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

  • Quando o Search Service foi adicionado?
  • Quem aprovou a migração de MySQL para PostgreSQL?
  • Como era a arquitetura seis meses atrás?
  • Como o numero de serviços cresceu ao longo do tempo?

Esse histórico é inestimável para entender a evolução do seu sistema e para o onboarding de novos membros da equipe.

Integração com CI/CD

Architecture as code se integra naturalmente em pipelines de integração e deploy contínuos. Em cada pull request, você pode:

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

Isso torna a documentação de arquitetura um artefato vivo em vez de um documento estático que decai.

Refatoração e Automação

Como definições de arquitetura são dados estruturados, você pode escrever scripts para manipula-los. Precisa renomear um serviço em todos os relationships? Um simples find-and-replace em um arquivo YAML. Precisa gerar um relatório de todos os serviços usando PostgreSQL? Parse o YAML e filtre por tecnologia. Precisa aplicar uma convenção de nomenclatura? Escreva um linter.

Formatos e DSLs de Architecture as Code

Vários formatos e DSLs existem para definir architecture as code. Aqui está uma visão geral das abordagens mais comuns.

Structurizr DSL

Criada por Simon Brown (o criador do modelo C4), a Structurizr DSL é 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 padrão de fato para configuração declarativa em DevOps (Kubernetes, Docker Compose, GitHub Actions, Terraform HCL a parte). Usar YAML para definições de arquitetura tem a vantagem da familiaridade -- a maioria dos desenvolvedores já 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 legíveis com notação de ponto para desambiguação. O formato é pesquisavel via grep, permite diff e não 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 princípios: a definição 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

Não tente documentar toda a sua arquitetura no primeiro dia. Comece com o diagrama de Container -- o panorama de serviços. Liste todo serviço deployavel, sua stack tecnológica e os principais relationships entre serviços.

Se você está 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 Repositório

Coloque o arquivo de arquitetura na raiz do seu repositório principal (ou em um repositório de arquitetura dedicado se seu codebase está dividido em muitos repos). A localização 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 Sincronização 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 documentação 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 Mudanças de Arquitetura Através de Pull Requests

A partir deste ponto, mudanças de arquitetura seguem o mesmo workflow que mudanças de código:

  1. Crie uma branch
  2. Modifique o arquivo archyl.yaml
  3. Abra um pull request
  4. Obtenha revisão da equipe
  5. Faca merge na main
  6. CI/CD sincroniza a mudança para o Archyl

Isso dá as mudanças de arquitetura a mesma visibilidade, responsabilidade e rastreabilidade que mudanças de código.

Passo 5: Adicione Regras de Conformidade

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

  • Todo container deve ter pelo menos uma tecnologia especificada
  • Todo external system deve ter uma descrição
  • Sem containers órfãos (todo container deve ter pelo menos um relationship)
  • Convenções de nomenclatura são seguidas (ex.: serviços terminam com "Service")

O motor de regras de conformidade do Archyl pode avaliar essas regras automaticamente e reportar violações no pipeline de CI ou no dashboard do Archyl.

Passo 6: Evolua a Definição ao Longo do Tempo

Comece com systems e containers. Adicione components quando serviços específicos se tornarem complexos o suficiente para justificar documentação interna. Adicione ADRs conforme toma decisões arquiteturais importantes. Adicione contratos de API conforme formaliza limites de serviço.

O arquivo de arquitetura cresce organicamente com seu sistema. Não há necessidade de antecipar todos os detalhes.

Architecture as Code vs. Infrastructure as Code

Architecture as code e infrastructure as code (IaC) são 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 tecnológicas e limites de serviço.

A configuração 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 serviço mas o arquivo de arquitetura não o menciona, a detecção de drift captura a discrepância.

Architecture as Code com Assistentes de IA

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

  • Responder perguntas sobre sua arquitetura consultando o arquivo YAML
  • Sugerir mudanças de arquitetura baseadas no estado atual
  • Gerar código que respeita a arquitetura documentada (ex.: usando o banco de dados certo para o serviço certo)
  • Detectar inconsistências entre o código e a definição de arquitetura

O Archyl leva isso adiante com seu servidor MCP. Assistentes de IA não apenas leem o arquivo de arquitetura -- eles podem consultar o modelo de arquitetura ao vivo, percorrer relationships e ate propor modificações. A arquitetura se torna uma fonte de dados programável e consultável em vez de um documento estático.

Armadilhas Comuns

Excesso de Engenharia no Formato

Não projete uma DSL customizada quando YAML ou um formato existente funciona. O objetivo e adoção, e adoção é mais fácil quando o formato e familiar. A maioria dos desenvolvedores já conhece YAML do Docker Compose, Kubernetes e configurações 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 são usadas. Não tente embutir detalhes operacionais (como politicas de escalabilidade), configurações de runtime (como variáveis de ambiente) ou especificações comportamentais (como formatos de resposta de API) no arquivo de arquitetura.

Não Aplicar o Workflow

Architecture as code só funciona se mudanças passarem pelo workflow definido. Se pessoas contornam o arquivo de arquitetura e fazem mudanças diretamente na ferramenta visual, o arquivo fica obsoleto. Estabeleça convenções claras sobre qual direção é autoritativa.

Ignorar a Saída Visual

Architecture as code não é um substituto para diagramas visuais -- é uma forma melhor de produzi-los. O arquivo de texto é a fonte de verdade, mas os diagramas renderizados são o que as pessoas realmente olham no dia a dia. Certifique-se de que a saída visual é acessível, atualizada e fácil de navegar.

Começando com o Archyl

O Archyl é 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
  • Sincronização bidirecional -- modele visualmente na UI e exporte para YAML, ou escreva YAML e sincronize para a UI
  • Integração com CI/CD para sincronização automatizada a cada commit
  • Regras de conformidade que validam a definição de arquitetura contra seus padrões
  • Servidor MCP que torna a arquitetura consultável por assistentes de IA
  • Recursos de colaboração com code review, comentários e ownership de equipe

Esteja você começando 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 documentação de arquitetura que você já traz para sua infraestrutura e código de aplicação.