Scoperta Potenziata dall'AI - Archyl Docs

Scopri come Archyl utilizza l'AI per scoprire e documentare automaticamente la tua architettura dal codebase

Scoperta Potenziata dall'AI

La funzionalità AI Discovery di Archyl analizza il tuo codebase per scoprire e documentare automaticamente l'architettura software. Questo risparmia ore di lavoro di documentazione manuale e garantisce che la documentazione architetturale rimanga sincronizzata con il codice reale.

Come Funziona

1. Collega il Tuo Repository

Per prima cosa, collega il tuo repository Git ad Archyl:

  1. Vai alle impostazioni del progetto
  2. Clicca su "Collega Repository"
  3. Scegli il tuo provider Git (GitHub, GitLab, Bitbucket, ecc.)
  4. Autorizza Archyl ad accedere al tuo repository

2. Avvia la Scoperta

Una volta collegato, avvia l'AI discovery:

  1. Clicca su "Avvia Scoperta" nel tuo progetto
  2. Seleziona quali branch o percorsi analizzare
  3. Configura le impostazioni di scoperta (opzionale)
  4. Clicca su "Esegui Scoperta"

3. Analisi AI

L'AI analizza il tuo codebase per identificare:

  • Struttura del progetto: Framework, linguaggi, sistemi di build
  • Servizi: Microservizi, API, worker in background
  • Data store: Database, cache, file storage
  • Integrazioni esterne: API di terze parti, servizi SaaS
  • Componenti: Moduli, package, classi chiave
  • Relazioni: Come comunicano i componenti

4. Revisiona e Approva

Le scoperte vengono messe in stato "In attesa" per la revisione:

  1. Revisiona ogni elemento scoperto
  2. Modifica nomi, descrizioni o relazioni
  3. Approva le scoperte accurate
  4. Rifiuta o modifica quelle incorrette

Tecnologie Supportate

L'AI Discovery funziona al meglio con:

Linguaggi

  • JavaScript/TypeScript
  • Python
  • Go
  • Java
  • C#
  • Ruby
  • PHP
  • Rust

Framework

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

Infrastruttura

  • Docker/Kubernetes
  • Terraform
  • AWS CDK
  • File di configurazione cloud

Scoperta incrementale

La scoperta incrementale mantiene il tuo modello C4 aggiornato analizzando solo i file modificati — non l'intero repository. E' piu veloce, meno costosa e puo essere eseguita automaticamente ad ogni push.

Come funziona

  1. Il codice viene pushato sul branch predefinito
  2. Archyl riceve l'evento push (tramite webhook o GitHub Action)
  3. I file modificati vengono estratti dai commit
  4. Solo i file sorgente vengono analizzati (i file eliminati vengono saltati)
  5. L'AI viene eseguita sul sottoinsieme di file
  6. I nuovi elementi vengono creati come scoperte in sospeso
  7. Gli elementi esistenti vengono automaticamente deduplicati

Attivare la scoperta incrementale

Ci sono due modi per attivare la scoperta incrementale:

  • Webhook GitHub — Abilita Discovery on Push nelle impostazioni webhook del progetto
  • GitHub Action (CI/CD) — Aggiungi l'action Archyl Incremental Discovery al tuo workflow. Vedi Integrazione GitHub Actions per le istruzioni complete.
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 }}

Scoperta completa vs incrementale

Scoperta completa Scoperta incrementale
Ambito Intero repository Solo file modificati
Trigger Manuale (UI/API) Automatico (webhook o GitHub Action)
Velocita Minuti (dipende dalla dimensione del repo) Secondi a minuti
Costo AI Maggiore (analizza tutti i file) Minore (analizza solo il diff)
Caso d'uso Setup iniziale, refactoring importanti Modifiche al codice quotidiane

Best Practice

Inizia in Piccolo

Per codebase grandi:

  1. Inizia con un singolo servizio o modulo
  2. Revisiona e affina i risultati
  3. Espandi gradualmente ad altre aree

Aggiornamenti Regolari

Mantieni la documentazione aggiornata:

  1. Esegui la scoperta dopo modifiche importanti
  2. Revisiona le nuove scoperte in attesa
  3. Aggiorna gli elementi esistenti se necessario

Combina con il Manuale

L'AI Discovery è un punto di partenza:

  1. Usa l'AI per il lavoro pesante
  2. Aggiungi il contesto di business manualmente
  3. Affina relazioni e descrizioni

Risoluzione Problemi

La Scoperta Richiede Troppo Tempo

  • Riduci le impostazioni di concorrenza
  • Escludi directory grandi (node_modules, vendor)
  • Concentrati su percorsi specifici

Risultati Imprecisi

  • Revisiona e correggi man mano
  • L'AI impara dalle tue correzioni
  • Più contesto nei commenti del codice aiuta