Descoberta com IA

Connect a repository from the project settings to enable AI discovery

A funcionalidade de Descoberta com IA do Archyl analisa seu código-fonte para descobrir e documentar automaticamente a arquitetura do seu software. Isso economiza horas de trabalho de documentação manual e garante que sua documentação de arquitetura permaneça sincronizada com o código real.

Como Funciona

1. Conecte Seu Repositório

Primeiro, conecte seu repositório Git ao Archyl:

  1. Vá para as configurações do seu projeto
  2. Clique em "Conectar Repositório"
  3. Escolha seu provedor Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea ou instâncias self-hosted)
  4. Autorize o Archyl a acessar seu repositório

2. Inicie a Descoberta

Uma vez conectado, inicie a descoberta com IA:

  1. Clique em "Iniciar Descoberta" no seu projeto
  2. Selecione qual branch analisar
  3. Clique em "Executar Descoberta"

3. Análise da IA

A IA analisa seu código-fonte em várias fases:

  1. Análise de estrutura — Identifica o nome do sistema, os contêineres e as dependências externas
  2. Descoberta detalhada — Analisa os arquivos-fonte em blocos paralelos para encontrar componentes, elementos de código e relacionamentos
  3. Refinamento de relacionamentos — Cruza os contêineres entre si para encontrar dependências entre serviços
  4. Pós-análise paralela — Descobre ADRs, documentação, contratos de API e dependências de pacotes

Os elementos descobertos incluem:

  • Sistemas: Sistemas de software de nível mais alto e dependências externas
  • Contêineres: Serviços, APIs, bancos de dados, aplicações web, workers
  • Componentes: Módulos, pacotes, handlers, repositórios, serviços
  • Elementos de código: Classes, interfaces, funções com seus caminhos de arquivo
  • Relacionamentos: Como os elementos se comunicam (usa, chama, envia para, lê de)

4. Revise e Aprove

As descobertas são colocadas em um estado Pendente para revisão:

  1. Revise cada elemento descoberto
  2. Edite nomes, descrições ou relacionamentos
  3. Aprove descobertas corretas
  4. Rejeite ou modifique as incorretas

Para novos projetos (sem elementos C4 existentes), as descobertas são aprovadas automaticamente para você começar rapidamente.

Descoberta Incremental

A descoberta incremental mantém seu modelo C4 atualizado analisando apenas os arquivos que mudaram — não o repositório inteiro. É mais rápida, mais econômica e pode ser executada automaticamente a cada push.

Como Funciona a Descoberta Incremental

  1. O código é enviado para a branch padrão
  2. O Archyl recebe o evento de push (via webhook ou GitHub Action)
  3. Os arquivos alterados são extraídos dos commits do push
  4. Apenas os arquivos-fonte são analisados (arquivos removidos são ignorados)
  5. A IA é executada sobre o conjunto menor de arquivos
  6. Novos elementos são criados como descobertas pendentes para revisão
  7. Elementos existentes são deduplicados automaticamente — sem duplicatas

Ativando a Descoberta Incremental

Há duas formas de ativar a descoberta incremental:

Opção A: Webhook do GitHub (Zero Configuração)

  1. Vá até as configurações de Configuração de webhook do seu projeto
  2. Ative Descoberta no push
  3. Copie a URL do webhook e adicione-a às configurações do seu repositório no GitHub
  4. Selecione o evento push

Cada push para a branch padrão vai disparar a descoberta incremental automaticamente.

Opção B: GitHub Action (CI/CD)

Adicione a action Archyl Incremental Discovery ao seu workflow. Veja Integração com GitHub Actions para as instruções completas de configuração.

name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Descoberta Completa vs. Incremental

Descoberta completa Descoberta incremental
Escopo Repositório inteiro Apenas arquivos alterados
Gatilho Manual (UI/API) Automático (webhook de push ou GitHub Action)
Velocidade Minutos (depende do tamanho do repositório) Segundos a minutos
Custo de IA Maior (analisa todos os arquivos) Menor (analisa apenas o diff)
Caso de uso Configuração inicial, grandes refatorações Alterações de código do dia a dia
Deduplicação Deduplicação completa contra o modelo existente Mesma deduplicação — sem duplicatas

Combinando Completa + Incremental

O fluxo de trabalho recomendado:

  1. Execute a descoberta completa quando conectar um repositório pela primeira vez
  2. Ative a descoberta incremental para manter o modelo atualizado
  3. Execute novamente a descoberta completa após grandes refatorações ou migrações

A descoberta incremental cria elementos pendentes assim como a descoberta completa — você sempre revisa antes que as alterações sejam aplicadas ao seu modelo C4.

Tecnologias Suportadas

A Descoberta com IA funciona com mais de 15 linguagens e frameworks:

Linguagens

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, Scala

Sistemas de build e gerenciadores de pacotes

npm, Go modules, pip/Poetry, Maven, Gradle, Cargo, Composer, RubyGems, NuGet, CMake (find_package, FetchContent, CPM), Conan, vcpkg

Frameworks

React, Next.js, Vue, Angular, Express, Fastify, NestJS, Django, Flask, FastAPI, Spring Boot, ASP.NET Core, Ruby on Rails, Gin, Fiber

Infraestrutura

Docker, Kubernetes, Terraform, Helm, Ansible, GitHub Actions, AWS CDK, Pulumi

Suporte a Monorepos

O Archyl detecta automaticamente estruturas de monorepo:

  • Diretórios apps/, packages/, services/, libs/
  • Amostragem proporcional de arquivos entre os serviços
  • Cada serviço corresponde a um contêiner separado no modelo C4
  • Os relacionamentos entre serviços são detectados

Boas Práticas

Comece Pequeno

Para grandes bases de código:

  1. Comece com um único serviço ou módulo
  2. Revise e refine os resultados
  3. Expanda gradualmente para outras áreas

Atualizações Regulares

Mantenha sua documentação atualizada:

  1. Ative a descoberta incremental para atualizações automáticas
  2. Revise as descobertas pendentes regularmente
  3. Execute a descoberta completa após grandes refatorações

Combine com Manual

A Descoberta com IA é um ponto de partida:

  1. Use a IA para o trabalho pesado
  2. Adicione contexto de negócio manualmente (descrições, ADRs)
  3. Refine relacionamentos e descrições

API REST

POST   /api/v1/discovery/start                            # Start full discovery
GET    /api/v1/discovery/jobs/:jobId                       # Get job status
POST   /api/v1/projects/:id/discovery/incremental          # Trigger incremental discovery

Resolução de Problemas

A Descoberta Está Demorando Demais

  • Reduza o número de arquivos analisados (ajuste o máximo de arquivos na configuração)
  • Use a descoberta incremental para as atualizações regulares
  • Foque em branches específicas

Resultados Imprecisos

  • Revise e corrija conforme avança — o sistema de pendências permite aprovar ou rejeitar cada elemento
  • Código mais estruturado produz melhores resultados
  • Adicione descrições aos elementos aprovados para melhorar o contexto das próximas descobertas

Nenhum Arquivo Analisado

  • Verifique se o seu repositório está conectado e se a branch existe
  • Garanta que os arquivos-fonte tenham extensões reconhecidas (.go, .ts, .py, .java etc.)
  • Confirme que o token de acesso tem permissão de leitura no repositório