Arquitetura como Código

O Archyl permite definir toda a sua arquitetura C4 em um único arquivo YAML — archyl.yaml. Faça o commit dele no seu repositório, edite-o junto com o código e deixe o CI/CD manter seus diagramas sincronizados automaticamente.

Visão Geral

O arquivo archyl.yaml é uma descrição declarativa da sua arquitetura. Ele suporta:

• Os quatro níveis C4 (sistemas, contêineres, componentes, código)
• Relacionamentos entre quaisquer elementos
• Tecnologias, ambientes e releases
• ADRs, documentação, contratos de API e canais de eventos
• Overlays visuais para agrupar elementos no diagrama
• Suporte a monorepos via include

Você pode escrevê-lo à mão, exportá-lo de um projeto existente ou combinar os dois fluxos.

Formato do Arquivo

O Archyl procura o arquivo DSL na raiz do repositório, tentando estes nomes nesta ordem:

1. archyl.yaml
2. .archyl.yaml
3. archyl.yml
4. .archyl.yml

Referência do Schema

Estrutura Raiz

version: "1.0"

project:
  name: My Platform
  description: E-commerce platform serving 10M users
  tags: [e-commerce, saas]

technologies: [...]
environments: [...]
systems: [...]
relationships: [...]
overlays: [...]
events: [...]
api_contracts: [...]
adrs:
  folder: docs/adrs
  records: [...]
docs:
  folder: docs
  records: [...]
releases: [...]
include: [...]

Apenas version é obrigatório. Todas as outras seções são opcionais — inclua só o que você precisa.

Sistemas (Nível C4 1)

Os sistemas são os elementos de nível mais alto do modelo C4.

systems:
  - name: Payment Service
    description: Handles all payment processing
    type: software_system   # person | software_system | external_system
    external: false
    tags: [payments, critical]
    technologies: [Go, PostgreSQL]
    owners:
      teams: [backend-team]
      users: [vincent]
    containers: [...]

Contêineres (Nível C4 2)

Os contêineres ficam aninhados dentro do sistema pai.

systems:
  - name: Payment Service
    containers:
      - name: API Gateway
        description: REST API for payment operations
        type: api
        tags: [rest, public]
        technologies: [Go, Fiber]
        owners:
          teams: [backend-team]
        components: [...]

Tipos de contêiner disponíveis: web_app, mobile_app, desktop_app, api, database, file_storage, message_queue, cache, service, function, worker, consumer, infrastructure, gateway, library.

Ao usar include para arquivos de um monorepo, use parent_system para indicar a qual sistema este contêiner pertence:

# In services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Payment Service
    type: api

Componentes (Nível C4 3)

Os componentes ficam aninhados dentro do contêiner pai.

containers:
  - name: API Gateway
    components:
      - name: PaymentHandler
        description: HTTP handler for payment endpoints
        type: handler
        file: internal/handler/payment.go
        tags: [http]
        technologies: [Go]
        code: [...]

Tipos de componente disponíveis: controller, service, repository, handler, middleware, model, util, config, adapter, port, resource, module, job, bundle, plugin, workflow, activity, entity.

Elementos de Código (Nível C4 4)

Os elementos de código ficam aninhados dentro do componente pai.

components:
  - name: PaymentHandler
    code:
      - name: ProcessPayment
        description: Handles payment processing requests
        type: function
        language: go
        file: internal/handler/payment.go
        line_start: 42
        line_end: 87
        visibility: public
        signature: "func (h *PaymentHandler) ProcessPayment(c *fiber.Ctx) error"
        methods:
          - name: validate
            signature: "func validate(req PaymentRequest) error"
            return_type: error
            visibility: private
        properties:
          - name: maxRetries
            type: int
            visibility: private
            readonly: true

Tipos de elemento de código disponíveis: class, interface, struct, function, method, enum, constant, type.

Relacionamentos

Os relacionamentos conectam dois elementos quaisquer, usando notação de ponto para referências aninhadas.

relationships:
  - from: Payment Service.API Gateway
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL, PostgreSQL]
    tags: [data-access]
    style:
      color: "#6366f1"
      width: 2
      style: solid       # solid | dashed | dotted
      animated: false

Formato da notação de ponto: System.Container.Component.CodeElement. Use apenas quantos níveis forem necessários — Payment Service referencia o sistema, Payment Service.API Gateway referencia um contêiner.

Tipos de relacionamento disponíveis: uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from.

Tecnologias

Defina um catálogo das tecnologias usadas em toda a sua arquitetura.

technologies:
  - name: Go
    description: Primary backend language
    category: programming_language
    icon: go
  - name: PostgreSQL
    description: Main relational database
    category: database
    icon: postgresql

Categorias disponíveis: programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.

Ambientes

Defina os ambientes de implantação das suas releases.

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"
  - name: Development
    color: "#6366f1"

Releases

Acompanhe implantações versionadas entre ambientes e elementos.

releases:
  - version: "2.4.0"
    status: deployed          # planned | in_progress | deployed | rolled_back | failed
    changelog: "Added payment retry logic and improved error handling"
    environment: Production
    container: Payment Service.API Gateway
    released_at: "2026-03-10T14:00:00Z"
    source: github_action
    source_url: "https://github.com/org/repo/actions/runs/12345"

Canais de Eventos

Defina a comunicação assíncrona entre serviços.

events:
  - name: PaymentCompleted
    description: Fired when a payment is successfully processed
    direction: produce         # produce | consume
    broker: kafka              # kafka | nats | sqs | rabbitmq | redis | pulsar | custom
    topic: payments.completed
    schema_format: json_schema # json_schema | avro | protobuf | text
    schema: |
      { "type": "object", "properties": { "paymentId": { "type": "string" } } }
    links:
      - Payment Service.API Gateway

Contratos de API

Anexe especificações de API à sua arquitetura.

api_contracts:
  - name: Payment API
    description: REST API for payment operations
    type: http                 # http | grpc | graphql | async
    version: "2.0"
    endpoint: /api/v2/payments
    file: docs/openapi.yaml    # path to spec file in repo
    links:
      - Payment Service.API Gateway

Use file para referenciar um arquivo de especificação no repositório, ou content para incluir a especificação diretamente no YAML.

Architecture Decision Records (ADRs)

adrs:
  folder: docs/adrs            # optional: path to ADR folder in repo
  records:
    - title: Use event-driven architecture for payments
      number: 7
      status: accepted         # proposed | accepted | deprecated | superseded
      date: "2026-02-15"
      context: We need to decouple payment processing from order management
      decision: Use Kafka events for async communication between services
      consequences: Added complexity but improved resilience and scalability
      tags: [architecture, messaging]
      links:
        - Payment Service

Documentação

docs:
  folder: docs                 # optional: path to docs folder in repo
  records:
    - title: Payment Processing Guide
      file: docs/payments.md   # path to markdown file in repo
      tags: [payments, guide]
      links:
        - Payment Service.API Gateway

Use file para referenciar um arquivo markdown no repositório, ou content para incluir o conteúdo diretamente no YAML.

Overlays

Agrupamentos visuais que aparecem no diagrama.

overlays:
  - name: Payment Domain
    description: All payment-related services
    color: "#6366f1"
    level: 2                   # C4 level (1=system, 2=container, 3=component, 4=code)
    elements:
      - Payment Service.API Gateway
      - Payment Service.Database
      - Payment Service.Worker

Include (Suporte a Monorepos)

Em monorepos, divida sua arquitetura em vários arquivos e combine-os:

include:
  - services/payments/archyl.yaml
  - services/orders/archyl.yaml
  - services/users/archyl.yaml

Cada arquivo incluído segue o mesmo schema. Use parent_system nos contêineres para indicar a qual sistema eles pertencem quando são definidos em um arquivo separado.

Exemplo Completo

version: "1.0"

project:
  name: E-Commerce Platform
  description: Online marketplace with payment processing
  tags: [e-commerce, saas, marketplace]

technologies:
  - name: Go
    category: programming_language
  - name: React
    category: framework
  - name: PostgreSQL
    category: database
  - name: Kafka
    category: message_broker
  - name: Redis
    category: cache

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"

systems:
  - name: Storefront
    description: Customer-facing web application
    type: software_system
    technologies: [React]
    containers:
      - name: Web App
        type: web_app
        technologies: [React]
      - name: BFF
        description: Backend for frontend
        type: api
        technologies: [Go]

  - name: Payment Service
    description: Handles payment processing
    type: software_system
    technologies: [Go, PostgreSQL]
    containers:
      - name: API
        type: api
        technologies: [Go]
        components:
          - name: PaymentHandler
            type: handler
          - name: PaymentService
            type: service
          - name: PaymentRepository
            type: repository
      - name: Database
        type: database
        technologies: [PostgreSQL]
      - name: Worker
        type: worker
        technologies: [Go]

  - name: Stripe
    description: Third-party payment processor
    type: external_system
    external: true

relationships:
  - from: Storefront.Web App
    to: Storefront.BFF
    label: API calls
    type: uses
    technologies: [HTTPS]
  - from: Storefront.BFF
    to: Payment Service.API
    label: Process payments
    type: calls
    technologies: [gRPC]
  - from: Payment Service.API
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL]
  - from: Payment Service.API
    to: Stripe
    label: Process charges
    type: calls
    technologies: [HTTPS]
  - from: Payment Service.Worker
    to: Payment Service.Database
    label: Polls for pending payments
    type: reads_from

events:
  - name: PaymentCompleted
    broker: kafka
    topic: payments.completed
    direction: produce
    links:
      - Payment Service.API

overlays:
  - name: Payment Domain
    level: 2
    color: "#6366f1"
    elements:
      - Payment Service.API
      - Payment Service.Database
      - Payment Service.Worker

releases:
  - version: "1.2.0"
    status: deployed
    environment: Production
    container: Payment Service.API
    changelog: Added retry logic for failed charges
    released_at: "2026-03-01T10:00:00Z"

Sincronizando a partir de um Repositório

Se o seu repositório contém um archyl.yaml, você pode sincronizá-lo diretamente pela interface do Archyl:

1. Vá em Configurações do Projeto > Arquitetura como Código
2. Clique em Sincronizar agora

O Archyl busca o arquivo na branch padrão do repositório (ou na branch configurada nas configurações da DSL) e o importa. Elementos que já existem são atualizados; novos elementos são criados.

Integração com CI/CD

GitHub Action (Oficial)

A GitHub Action oficial archyl-com/actions/sync é a forma mais simples de manter sua arquitetura sincronizada. Ela lê o seu archyl.yaml, envia-o para a API do Archyl e informa o que foi criado ou atualizado.

Configuração mínima:

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'

Com saída de resumo:

- uses: archyl-com/actions/sync@v1
  id: sync
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
- run: echo "${{ steps.sync.outputs.summary }}"

Caminho de arquivo personalizado (monorepo):

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
    file: 'services/payments/archyl.yaml'

Archyl auto-hospedado:

- uses: archyl-com/actions/sync@v1
  with:
    api-url: 'https://archyl.your-company.com'
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'

Entradas da Action

Saídas da Action

GitLab CI/CD

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

API REST

Você pode enviar conteúdo DSL a partir de qualquer sistema de CI/CD ou script:

curl -X POST https://your-instance.com/api/v1/projects/{projectId}/dsl/ingest \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"

O endpoint de ingestão retorna um resumo do que foi criado:

{
  "source": "api",
  "import": {
    "systemsCreated": 2,
    "containersCreated": 5,
    "componentsCreated": 12,
    "codeElementsCreated": 0,
    "relationshipsCreated": 8,
    "overlaysCreated": 1,
    "technologiesCreated": 4,
    "adrsCreated": 0,
    "docsCreated": 0,
    "eventsCreated": 1,
    "apiContractsCreated": 0,
    "environmentsCreated": 2,
    "releasesCreated": 1
  }
}

Exportando para YAML

Você pode exportar qualquer projeto existente como um arquivo archyl.yaml:

1. Abra o seu projeto
2. Clique em Exportar na barra de ferramentas
3. Selecione YAML (Arquitetura como Código)

Isso gera um archyl.yaml completo, pronto para ser versionado no seu repositório. É uma ótima forma de criar o arquivo a partir de um projeto existente ou de uma arquitetura descoberta pela IA.

Você também pode exportar via API:

curl -H "X-API-Key: your-api-key" \
  https://your-instance.com/api/v1/projects/{projectId}/dsl/export \
  -o archyl.yaml

JSON Schema para Suporte na IDE

O Archyl disponibiliza um JSON Schema para arquivos archyl.yaml, para que o seu editor ofereça autocompletar e validação. O schema está disponível em:

https://your-instance.com/api/v1/dsl/schema

VS Code

Adicione isto ao seu archyl.yaml para ativar a validação pelo schema:

# yaml-language-server: $schema=https://your-instance.com/api/v1/dsl/schema
version: "1.0"

Ou configure-o globalmente nas configurações do VS Code:

{
  "yaml.schemas": {
    "https://your-instance.com/api/v1/dsl/schema": ["archyl.yaml", ".archyl.yaml"]
  }
}

Exportação de Imagem e PDF

O Archyl também permite exportar seus diagramas como imagens para apresentações e documentos.

Formatos Disponíveis

Como Exportar

1. Navegue até o nível C4 que deseja exportar
2. Clique em Exportar na barra de ferramentas
3. Selecione seu formato (PNG, SVG ou PDF)
4. Configure as opções (fundo, qualidade, viewport)
5. Clique em Exportar

Marque Exportar todos os níveis para gerar arquivos separados para cada nível C4.

Opções de Exportação

• Fundo: Incluir o fundo escuro do canvas ou usar fundo transparente
• Qualidade (apenas PNG): Resolução Padrão, Alta ou para Impressão
• Viewport: Ajustar ao conteúdo, incluir margem ou exportar a visualização atual

Importando Projetos

Você pode criar um novo projeto importando de múltiplos formatos. O Archyl suporta cinco fontes de importação:

Como Importar

1. Na sua lista de projetos, clique em Importar Projeto
2. Selecione a aba do formato de origem (Archyl YAML, Structurizr DSL, LikeC4, IcePanel ou Backstage)
3. Faça upload do arquivo ou cole seu conteúdo
4. Clique em Validar para visualizar o que será criado
5. Clique em Criar Projeto

O processo inteiro leva menos de um minuto. Todos os sistemas, contêineres, componentes, relacionamentos, tecnologias e tags são importados automaticamente.

Nome e Descrição do Projeto

Criar um projeto exige um nome, e cada formato o carrega em um lugar diferente. A ausência de nome é a causa mais comum de uma importação rejeitada.

Apenas Archyl YAML e Structurizr DSL podem falhar nessa verificação. Os outros formatos sempre recorrem a um nome gerado que você pode alterar após a importação.

No Structurizr, o nome e a descrição são as duas strings opcionais no cabeçalho workspace:

workspace "My Platform" "Microservices architecture" {
    model {
        user = person "User"
        platform = softwareSystem "My Platform" {
            api = container "API" "REST API" "Go"
        }
        user -> api "Uses"
    }
}

Um workspace { ... } sem nome é analisado corretamente, mas não pode criar um projeto — o Archyl o rejeita e pede que você nomeie o workspace. Importar para um projeto existente não tem esse requisito: ali o nome do workspace é ignorado, porque o projeto já tem um.

Importação de Structurizr DSL

O Archyl analisa os arquivos de workspace .dsl do Structurizr e extrai o modelo C4 completo:

• Elementos person, softwareSystem, container e component
• Todos os relacionamentos ->, com descrições e tecnologias
• Detecção de sistemas externos a partir das tags
• Extração de tecnologias a partir dos argumentos posicionais
• Grupos mapeados para tags

Views, estilos, temas e nós de implantação são ignorados (o Archyl tem sua própria camada visual).

O nome e a descrição do workspace tornam-se o nome e a descrição do projeto — veja a seção Nome e Descrição do Projeto acima. Um workspace sem nome pode ser importado para um projeto existente, mas não pode criar um.

Workspaces em vários arquivos (!include)

Um workspace dividido em vários arquivos — !include systems/payments.dsl e afins — não pode ser importado como arquivo único, porque os arquivos incluídos não estão lá para serem resolvidos. Envie o workspace inteiro como um .zip, na aba Structurizr DSL: os arquivos do pacote são extraídos e cada !include é resolvido contra eles.

• O ponto de entrada é workspace.dsl quando o pacote tem um, senão o .dsl menos profundo. O Archyl informa qual arquivo usou.
• Os caminhos são resolvidos em relação ao arquivo que inclui, então includes aninhados funcionam.
• Incluir um diretório traz todos os .dsl diretamente dentro dele, em ordem de nome.
• Ciclos de inclusão são interrompidos e relatados, em vez de falhar a importação.
• Alvos remotos (!include https://…) são recusados e caminhos que saem do pacote são ignorados.

Tudo o que não puder ser resolvido vira um aviso no resultado da importação — o restante do workspace é importado mesmo assim.

Limites do arquivo compactado:

Apenas arquivos .dsl, .md, .json, .yaml, .yml e .txt são mantidos; todo o resto do pacote é ignorado.

Pela API, envie o pacote como multipart form data em um campo file, com um campo opcional entry indicando o ponto de entrada: POST /api/v1/dsl/validate-archive o valida, POST /api/v1/projects/{id}/dsl/import-archive o importa para um projeto e POST /api/v1/dsl/import-project-archive cria um projeto a partir dele. A ferramenta MCP import_dsl e a sincronização do repositório leem um único arquivo e não resolvem !include.

Importação de LikeC4

O Archyl é a primeira ferramenta a importar arquivos LikeC4. O importador lida com os recursos específicos do LikeC4:

• Tipos de elemento personalizados dos blocos specification mapeados para níveis C4
• Hierarquias de elementos aninhados resolvidas em sistemas, contêineres e componentes
• Propriedades technology: e description: (com ou sem a sintaxe de dois-pontos)
• Tags #hashtag convertidas em tags padrão
• Detecção da tag #external para classificar o que está fora da fronteira
• Múltiplos blocos model mesclados automaticamente
• Suporte a strings entre aspas simples e entre aspas triplas

Importação de IcePanel JSON

O formato de exportação JSON do IcePanel é totalmente suportado:

• Tipos de objeto system, actor, app, store e component mapeados para elementos C4
• Campo external: true para classificar sistemas externos
• modelConnections mapeados para relacionamentos
• tagIds resolvidos para nomes de tags a partir do array tags
• Objetos domain usados como nome do projeto

Importação de Backstage

O Archyl importa o JSON do Software Catalog retornado pelo endpoint /api/catalog/entities do Backstage:

• Entidades System mapeadas para Sistemas do Archyl (colisões entre namespaces são desambiguadas automaticamente)
• Entidades Component e Resource agrupadas como Contêineres sob o Sistema ao qual pertencem (via spec.system ou a relação partOf)
• Components/Resources sem um System pai agrupados sob um sistema sintético Uncategorized
• Tipos de Resource mapeados para tipos de contêiner do Archyl: s3-bucket → file_storage; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database; kafka-topic, sqs-queue → message_queue; repository → library; todo o resto → infrastructure
• Tipos de Component mapeados: service → service, cronworkflow → worker, website → web_app, library → library
• Entidades API importadas como Contratos de API, com o spec.definition inline (OpenAPI / gRPC / GraphQL / AsyncAPI) preservado como conteúdo e vinculado aos componentes provedores/consumidores
• dependsOn, consumesApi, producesTo, consumesFrom, versionedIn (e seus inversos) traduzidos em relacionamentos do Archyl
• metadata.namespace, spec.lifecycle e spec.type expostos como tags
• Entidades User e Group ignoradas — o grafo de pessoas/equipes do Backstage não é um conceito C4

Para exportar o seu catálogo:

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

Depois, solte o entities.json na aba Backstage da caixa de diálogo de importação. As listas de recursos de catálogos grandes podem gerar milhares de contêineres — revise o resultado e exclua o que não precisar.

Importação via MCP (Agentes de IA)

A mesma capacidade de importação está disponível através da ferramenta MCP import_dsl:

Use the import_dsl tool with:
- projectId: your project UUID
- content: the DSL/JSON content
- format: "archyl", "structurizr", "likec4", "icepanel", or "backstage"

Isso permite que agentes de código com IA (Claude Code, Cursor, Windsurf) importem arquivos de arquitetura de forma programática.

Importar em Projetos Existentes

Você também pode importar em um projeto existente (e não apenas criar novos):

1. Abra o seu projeto
2. Vá em Arquitetura como Código
3. Clique em Importar
4. Selecione o formato e faça o upload

Elementos que já existem são atualizados; novos elementos são criados.

Próximos Passos

• Visão Geral da API — Referência completa da API para os endpoints de DSL
• Compartilhamento e Incorporação — Compartilhe diagramas ao vivo
• Gerenciamento de Releases — Acompanhe implantações no seu YAML
• Notificações por Webhook — Seja notificado quando a arquitetura mudar