Aprenda como o Archyl usa IA para descobrir e documentar automaticamente sua arquitetura a partir do código-fonte

Descoberta com IA

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:

Vá para as configurações do seu projeto
Clique em "Conectar Repositório"
Escolha seu provedor Git (GitHub, GitLab, Bitbucket, etc.)
Autorize o Archyl a acessar seu repositório

2. Inicie a Descoberta

Uma vez conectado, inicie a descoberta com IA:

Clique em "Iniciar Descoberta" no seu projeto
Selecione quais branches ou caminhos analisar
Configure as opções de descoberta (opcional)
Clique em "Executar Descoberta"

3. Análise da IA

A IA analisa seu código-fonte para identificar:

Estrutura do projeto: Frameworks, linguagens, sistemas de build
Serviços: Microsserviços, APIs, workers em background
Armazenamentos de dados: Bancos de dados, caches, armazenamento de arquivos
Integrações externas: APIs de terceiros, serviços SaaS
Componentes: Módulos, pacotes, classes principais
Relacionamentos: Como os componentes se comunicam

4. Revise e Aprove

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

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

Tecnologias Suportadas

A Descoberta com IA funciona melhor com:

Linguagens

JavaScript/TypeScript
Python
Go
Java
C#
Ruby
PHP
Rust

Frameworks

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

Infraestrutura

Docker/Kubernetes
Terraform
AWS CDK
Arquivos de configuração de nuvem

Descoberta incremental

A descoberta incremental mantem seu modelo C4 atualizado analisando apenas os arquivos que mudaram — nao o repositorio inteiro. E mais rapida, mais economica e pode ser executada automaticamente a cada push.

Como funciona

Codigo e enviado para a branch padrao
O Archyl recebe o evento push (via webhook ou GitHub Action)
Arquivos alterados sao extraidos dos commits
Apenas arquivos fonte sao analisados (arquivos removidos sao ignorados)
A IA e executada no subconjunto de arquivos
Novos elementos sao criados como descobertas pendentes
Elementos existentes sao automaticamente deduplicados

Ativar descoberta incremental

Ha duas formas de ativar a descoberta incremental:

Webhook GitHub — Ative Discovery on Push nas configuracoes de webhook do projeto
GitHub Action (CI/CD) — Adicione a action Archyl Incremental Discovery ao seu workflow. Veja Integracao com GitHub Actions para instrucoes completas.

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	Repositorio inteiro	Apenas arquivos alterados
Gatilho	Manual (UI/API)	Automatico (webhook ou GitHub Action)
Velocidade	Minutos (depende do tamanho do repo)	Segundos a minutos
Custo IA	Maior (analisa todos os arquivos)	Menor (analisa apenas o diff)
Caso de uso	Configuracao inicial, refatoracoes maiores	Alteracoes de codigo diarias

Boas Praticas

Comece Pequeno

Para grandes bases de código:

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

Atualizações Regulares

Mantenha sua documentação atualizada:

Execute a descoberta após grandes mudanças
Revise novas descobertas pendentes
Atualize elementos existentes conforme necessário

Combine com Manual

A Descoberta com IA é um ponto de partida:

Use a IA para o trabalho pesado
Adicione contexto de negócio manualmente
Refine relacionamentos e descrições

Resolução de Problemas

A Descoberta Está Demorando Demais

Reduza as configurações de concorrência
Exclua diretórios grandes (node_modules, vendor)
Foque em caminhos específicos

Resultados Imprecisos

Revise e corrija conforme avança
A IA aprende com suas correções
Mais contexto nos comentários do código ajuda

Descoberta com IA - Archyl Docs