Scoperta potenziata dall'IA

Connect a repository from the project settings to enable AI discovery

La funzionalità di Scoperta IA di Archyl analizza il tuo codebase per scoprire e documentare automaticamente l'architettura software. Questo ti risparmia ore di documentazione manuale e garantisce che la documentazione architetturale resti 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, Azure DevOps, Gitea o istanze self-hosted)
  4. Autorizza Archyl ad accedere al tuo repository

2. Avvia la scoperta

Una volta collegato il repository, avvia la scoperta IA:

  1. Clicca su "Avvia Scoperta" nel tuo progetto
  2. Seleziona il branch da analizzare
  3. Clicca su "Esegui Scoperta"

3. Analisi IA

L'IA analizza il tuo codebase in più fasi:

  1. Analisi della struttura — Identifica il nome del sistema, i container e le dipendenze esterne
  2. Scoperta dettagliata — Analizza i file sorgente in blocchi paralleli per trovare componenti, elementi di codice e relazioni
  3. Rifinitura delle relazioni — Incrocia i container per individuare le dipendenze tra servizi
  4. Post-analisi parallela — Scopre ADR, documentazione, contratti API e dipendenze dei pacchetti

Gli elementi scoperti includono:

  • Sistemi: sistemi software di primo livello e dipendenze esterne
  • Container: servizi, API, database, applicazioni web, worker
  • Componenti: moduli, package, handler, repository, servizi
  • Elementi di codice: classi, interfacce, funzioni con i relativi percorsi dei file
  • Relazioni: come comunicano gli elementi (usa, chiama, invia a, legge da)

4. Revisiona e approva

Le scoperte vengono messe nello 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 errate

Per i nuovi progetti (senza elementi C4 esistenti), le scoperte vengono approvate automaticamente per farti partire più in fretta.

Scoperta incrementale

La scoperta incrementale mantiene aggiornato il tuo modello C4 analizzando solo i file modificati, non l'intero repository. È più veloce, costa meno e può essere eseguita automaticamente a ogni push.

Come funziona la scoperta incrementale

  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 del push
  4. Vengono analizzati solo i file sorgente (i file eliminati vengono saltati)
  5. L'IA viene eseguita sull'insieme ridotto di file
  6. I nuovi elementi vengono creati come scoperte in attesa di revisione
  7. Gli elementi esistenti vengono deduplicati automaticamente, senza duplicati

Attivare la scoperta incrementale

Ci sono due modi per attivare la scoperta incrementale:

Opzione A: webhook GitHub (zero configurazione)

  1. Vai alle impostazioni Configurazione webhook del progetto
  2. Abilita Discovery on Push
  3. Copia l'URL del webhook e aggiungilo alle impostazioni del tuo repository GitHub
  4. Seleziona l'evento push

Ogni push sul branch predefinito attiverà automaticamente la scoperta incrementale.

Opzione B: 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 i file modificati
Trigger Manuale (UI/API) Automatico (webhook di push o GitHub Action)
Velocità Minuti (dipende dalle dimensioni del repo) Da secondi a minuti
Costo IA Maggiore (analizza tutti i file) Minore (analizza solo il diff)
Caso d'uso Configurazione iniziale, refactoring importanti Modifiche quotidiane al codice
Deduplicazione Deduplicazione completa rispetto al modello esistente Stessa deduplicazione, nessun duplicato

Combinare completa e incrementale

Il flusso di lavoro consigliato:

  1. Esegui la scoperta completa quando colleghi un repository per la prima volta
  2. Abilita la scoperta incrementale per mantenere il modello aggiornato
  3. Riesegui la scoperta completa dopo refactoring o migrazioni importanti

La scoperta incrementale crea elementi in attesa proprio come la scoperta completa: rivedi sempre le modifiche prima che vengano applicate al tuo modello C4.

Tecnologie supportate

La Scoperta IA funziona con oltre 15 linguaggi e framework:

Linguaggi

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

Sistemi di build e gestori di pacchetti

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

Framework

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

Infrastruttura

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

Supporto monorepo

Archyl rileva automaticamente le strutture monorepo:

  • Directory apps/, packages/, services/, libs/
  • Campionamento dei file proporzionale tra i servizi
  • Ogni servizio corrisponde a un container distinto nel modello C4
  • Vengono rilevate le relazioni tra servizi

Best practice

Inizia in piccolo

Per codebase di grandi dimensioni:

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

Aggiornamenti regolari

Mantieni aggiornata la documentazione:

  1. Abilita la scoperta incrementale per gli aggiornamenti automatici
  2. Revisiona regolarmente le scoperte in attesa
  3. Esegui la scoperta completa dopo refactoring importanti

Combina con il lavoro manuale

La Scoperta IA è un punto di partenza:

  1. Usa l'IA per il lavoro pesante
  2. Aggiungi manualmente il contesto di business (descrizioni, ADR)
  3. Affina relazioni e descrizioni

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

Risoluzione dei problemi

La scoperta richiede troppo tempo

  • Riduci il numero di file analizzati (regola il numero massimo di file nella configurazione)
  • Usa la scoperta incrementale per gli aggiornamenti regolari
  • Concentrati su branch specifici

Risultati imprecisi

  • Revisiona e correggi man mano: il sistema delle scoperte in attesa ti permette di approvare o rifiutare ogni elemento
  • Un codice più strutturato produce risultati migliori
  • Aggiungi descrizioni agli elementi approvati per migliorare il contesto delle scoperte future

Nessun file analizzato

  • Verifica che il repository sia collegato e che il branch esista
  • Assicurati che i file sorgente abbiano estensioni riconosciute (.go, .ts, .py, .java, ecc.)
  • Verifica che il token di accesso abbia i permessi di lettura sul repository