Escolha como começar

Um projeto Archyl contém um modelo C4 do seu software: sistemas, containers, componentes e código, e os relacionamentos entre eles. Há quatro formas de preenchê-lo. Elas podem ser combinadas, e nenhuma prende você.

Seja qual for a escolha, os próximos passos são os mesmos: conectar seus agentes de programação e manter o modelo em sincronia com o código.

Desenhar no aplicativo

Crie um projeto a partir do painel e adicione sistemas, containers e relacionamentos no canvas. O Guia de Início Rápido mostra isso passo a passo.

Desenhar é o começo certo para um sistema que ainda não existe, ou para esboçar o contexto antes de qualquer código. Você pode passar para código depois: archyl dsl pull grava o que você desenhou em archyl.yaml.

Descobrir com IA

A Descoberta com IA lê um repositório conectado e propõe sistemas, containers, componentes, relacionamentos e tecnologias. Nada entra no modelo até você aprovar.

A partir do aplicativo: conecte o repositório em Configurações do Projeto › Integração Git (veja Integração Git), inicie uma descoberta e revise o que ela encontrou.

A partir do terminal, na raiz do repositório:

archyl login
archyl init --new

init --new cria o projeto, conecta o repositório a partir do seu remote git, executa a descoberta enquanto você acompanha, abre a revisão, desenha o resultado e oferece conectar seus agentes de programação. Flags úteis: --name, --team, --branch, --provider para um remote auto-hospedado (github_enterprise, gitlab_private, gitea) e --yes para aceitar todos os padrões. Veja o guia da CLI.

A descoberta lida com monorepos: reconhece apps/, packages/, services/ e libs/, e mapeia cada serviço para um container.

Escrever como código

Descreva a arquitetura em um archyl.yaml na raiz do repositório e faça o push. O formato do arquivo está em Arquitetura como Código.

archyl login
archyl init --new --no-discover   # create the project and link this repository, no AI
$EDITOR archyl.yaml               # describe the architecture
archyl dsl diff                   # what a push would create or change
archyl dsl push                   # import it
archyl diagram                    # look at the result

Um arquivo mínimo:

version: "1.0"
systems:
  - name: Shop
    containers:
      - name: Storefront
        type: web_app
        technologies: [React]
      - name: Orders API
        type: api
        technologies: [Go]
      - name: Orders DB
        type: database
        technologies: [PostgreSQL]
  - name: Stripe
    external: true
relationships:
  - from: Storefront
    to: Orders API
    label: Places orders
    type: calls
  - from: Orders API
    to: Orders DB
    type: reads_from
  - from: Orders API
    to: Stripe
    label: Charges cards
    type: calls

Os elementos são correspondidos pelo nome. Um push cria o que é novo e atualiza o que mudou, e nunca exclui: um elemento que só o Archyl tem permanece, e archyl dsl diff o lista como "only in Archyl".

Seu agente de programação pode escrever a primeira versão: execute archyl setup e peça a ele que descreva o repositório em archyl.yaml seguindo o schema. O arquivo continua sendo seu para revisar.

Para manter o arquivo e o modelo em sincronia, faça commit do archyl.yaml e faça o push dele pela CI com a GitHub Action, ou use Sincronizar agora em Configurações do Projeto › Arquitetura como Código. archyl dsl diff --exit-code faz um job de CI falhar quando eles diferem.

Importar de outra ferramenta

Na lista de projetos, clique em Importar Projeto e escolha o formato: Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON ou Backstage JSON. Um workspace Structurizr dividido em arquivos !include pode ser enviado como zip. Os detalhes, e onde cada formato guarda o nome do projeto, estão em Importando Projetos.

Passo a passo para monorepos

Este é o caminho por código de ponta a ponta para um monorepo, sem descoberta com IA:

shop/
├── apps/
│   ├── storefront/
│   └── admin/
├── services/
│   ├── orders/
│   └── payments/
└── packages/
    └── ui/

1. Crie o projeto e vincule o repositório. Na raiz do monorepo:

archyl init --new --no-discover --name "Shop" --team platform

Isso grava .archyl.json, que vincula o repositório ao projeto. Faça commit do arquivo: ele não contém nenhum segredo.

2. Modele um sistema com um container por unidade implantável. Apps e serviços viram containers. Um pacote compartilhado como packages/ui em geral não é um container próprio: descreva-o como um componente dos containers que o usam, ou deixe-o de fora.

3. Dê a cada container o nome da sua pasta. É isso que permite a archyl brief, where, check, impact e ao hook Guard saber a qual elemento um arquivo alterado pertence: um arquivo pertence a um elemento quando uma das pastas do seu caminho tem o nome do elemento. A comparação ignora maiúsculas, espaços e pontuação, e uma palavra final como API, Service ou Worker, então Orders Service corresponde a services/orders/… e Payments API corresponde a services/payments/….

4. Escolha um arquivo ou vários. Um único archyl.yaml na raiz é o mais simples. Em um monorepo grande, dê a cada serviço seu próprio arquivo ao lado do código e inclua-os a partir da raiz, para que cada equipe edite sua parte:

# archyl.yaml
version: "1.0"
include:
  - apps/storefront/archyl.yaml
  - services/orders/archyl.yaml
  - services/payments/archyl.yaml
systems:
  - name: Shop
    description: The online shop
  - name: Stripe
    external: true

# services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Shop
    type: api
    technologies: [Go]
relationships:
  - from: Payments API
    to: Stripe
    label: Charges cards
    type: calls

Os caminhos de include são relativos ao arquivo que os declara, e os relacionamentos podem apontar para elementos em qualquer um dos arquivos. As regras estão em Include.

5. Faça o push e verifique.

archyl dsl diff
archyl dsl push
archyl where services/payments/internal/charge.go   # should name Payments API
archyl diagram "Payments API"                       # the container and its neighbours

Se where informar que um arquivo não tem correspondência, renomeie o container conforme sua pasta e faça o push de novo.

6. Mantenha tudo atualizado. Faça commit de archyl.yaml e dos arquivos incluídos. Faça o push pela CI quando houver mudanças, ou use Sincronizar agora, que também busca os arquivos incluídos no repositório.

Depois, coloque para trabalhar

Quando o modelo existir:

• Conecte seus agentes de programação com archyl setup (Claude Code, Cursor, VS Code, Codex) ou pelo painel. Eles passam então a chamar plan, brief e o harness antes de alterar o código.
• Verifique as mudanças com base nele com archyl check e archyl review na CI. Veja o guia da CLI.
• Integre pessoas e agentes com archyl tour: um percurso guiado pelas partes a conhecer primeiro, com os arquivos a ler. archyl tour --markdown > ONBOARDING.md grava esse percurso em um arquivo.
• Explore-o com archyl map, archyl diagram <element> ou o canvas no aplicativo.

Combinar caminhos

• Descobrir e depois gerenciar como código: execute uma descoberta, aprove-a, depois execute archyl dsl pull e faça commit do archyl.yaml a partir daí.
• Escrever como código e depois descobrir: uma descoberta propõe apenas o que o modelo ainda não tem, então pode preencher componentes sob os containers que você escreveu. Revise-a como qualquer outra descoberta.
• Desenhar no aplicativo e fazer push a partir do código: ambos editam o mesmo modelo. Um push atualiza o que o arquivo descreve e deixa o resto intacto.