Découverte propulsée par l'IA

Connect a repository from the project settings to enable AI discovery

La fonctionnalité de découverte IA d'Archyl analyse votre code source pour découvrir et documenter automatiquement votre architecture logicielle. Vous économisez des heures de documentation manuelle, et votre documentation d'architecture reste synchronisée avec votre code réel.

Comment ça fonctionne

1. Connectez votre dépôt

Commencez par connecter votre dépôt Git à Archyl :

  1. Allez dans les paramètres de votre projet
  2. Cliquez sur "Connecter un dépôt"
  3. Choisissez votre fournisseur Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea ou des instances auto-hébergées)
  4. Autorisez Archyl à accéder à votre dépôt

2. Lancez la découverte

Une fois le dépôt connecté, lancez la découverte IA :

  1. Cliquez sur "Lancer la découverte" dans votre projet
  2. Sélectionnez la branche à analyser
  3. Cliquez sur "Exécuter la découverte"

3. Analyse IA

L'IA analyse votre code source en plusieurs phases :

  1. Analyse de structure — Identifie le nom du système, les conteneurs et les dépendances externes
  2. Découverte détaillée — Analyse les fichiers source par lots en parallèle pour trouver les composants, les éléments de code et les relations
  3. Affinage des relations — Croise les conteneurs pour trouver les dépendances entre services
  4. Post-analyse parallèle — Découvre les ADRs, la documentation, les contrats d'API et les dépendances de packages

Les éléments découverts comprennent :

  • Systèmes : les systèmes logiciels de haut niveau et les dépendances externes
  • Conteneurs : services, APIs, bases de données, applications web, workers
  • Composants : modules, packages, handlers, repositories, services
  • Éléments de code : classes, interfaces, fonctions, avec leurs chemins de fichiers
  • Relations : la façon dont les éléments communiquent (utilise, appelle, envoie à, lit depuis)

4. Révisez et approuvez

Les découvertes sont placées à l'état En attente pour être révisées :

  1. Révisez chaque élément découvert
  2. Modifiez les noms, descriptions ou relations
  3. Approuvez les découvertes exactes
  4. Rejetez ou modifiez celles qui sont incorrectes

Pour les nouveaux projets (sans élément C4 existant), les découvertes sont approuvées automatiquement pour vous permettre de démarrer rapidement.

Découverte incrémentale

La découverte incrémentale maintient votre modèle C4 à jour en analysant uniquement les fichiers modifiés — pas l'ensemble du dépôt. C'est plus rapide, moins coûteux, et cela peut s'exécuter automatiquement à chaque push.

Fonctionnement de la découverte incrémentale

  1. Du code est poussé sur la branche par défaut
  2. Archyl reçoit l'événement push (via webhook ou GitHub Action)
  3. Les fichiers modifiés sont extraits des commits du push
  4. Seuls les fichiers source sont analysés (les fichiers supprimés sont ignorés)
  5. L'IA s'exécute sur ce sous-ensemble de fichiers
  6. Les nouveaux éléments sont créés comme découvertes en attente de révision
  7. Les éléments existants sont automatiquement dédupliqués — aucun doublon

Activer la découverte incrémentale

Il existe deux façons d'activer la découverte incrémentale :

Option A : webhook GitHub (sans configuration)

  1. Ouvrez les paramètres Configuration du webhook de votre projet
  2. Activez Découverte au push
  3. Copiez l'URL du webhook et ajoutez-la dans les paramètres de votre dépôt GitHub
  4. Sélectionnez l'événement push

Chaque push sur la branche par défaut déclenchera automatiquement la découverte incrémentale.

Option B : GitHub Action (CI/CD)

Ajoutez l'action Archyl Incremental Discovery à votre workflow. Consultez Intégration GitHub Actions pour les instructions de configuration complètes.

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 }}

Découverte complète ou incrémentale

Découverte complète Découverte incrémentale
Périmètre Dépôt entier Fichiers modifiés uniquement
Déclencheur Manuel (UI/API) Automatique (webhook de push ou GitHub Action)
Vitesse Quelques minutes (selon la taille du dépôt) De quelques secondes à quelques minutes
Coût IA Plus élevé (analyse tous les fichiers) Plus faible (analyse uniquement le diff)
Cas d'usage Configuration initiale, refactorings majeurs Modifications de code quotidiennes
Déduplication Déduplication complète par rapport au modèle existant Même déduplication — aucun doublon

Combiner découverte complète et incrémentale

Le workflow recommandé :

  1. Lancez une découverte complète lorsque vous connectez un dépôt pour la première fois
  2. Activez la découverte incrémentale pour garder le modèle à jour
  3. Relancez une découverte complète après des refactorings ou des migrations majeurs

La découverte incrémentale crée des éléments en attente, exactement comme la découverte complète : vous les révisez toujours avant que les changements ne soient appliqués à votre modèle C4.

Technologies prises en charge

La découverte IA fonctionne avec plus de 15 langages et frameworks :

Langages

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

Systèmes de build et gestionnaires de packages

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

Infrastructure

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

Prise en charge des monorepos

Archyl détecte automatiquement les structures de monorepo :

  • Répertoires apps/, packages/, services/, libs/
  • Échantillonnage des fichiers proportionnel entre les services
  • Chaque service correspond à un conteneur distinct dans le modèle C4
  • Les relations entre services sont détectées

Bonnes pratiques

Commencez petit

Pour les grandes bases de code :

  1. Commencez par un seul service ou module
  2. Révisez et affinez les résultats
  3. Étendez progressivement aux autres zones

Mises à jour régulières

Gardez votre documentation à jour :

  1. Activez la découverte incrémentale pour des mises à jour automatiques
  2. Révisez régulièrement les découvertes en attente
  3. Lancez une découverte complète après des refactorings majeurs

Combinez avec le travail manuel

La découverte IA est un point de départ :

  1. Utilisez l'IA pour le gros du travail
  2. Ajoutez manuellement le contexte métier (descriptions, ADRs)
  3. Affinez les relations et les descriptions

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

Dépannage

La découverte prend trop de temps

  • Réduisez le nombre de fichiers analysés (ajustez le nombre maximal de fichiers dans la configuration)
  • Utilisez la découverte incrémentale pour les mises à jour régulières
  • Concentrez-vous sur des branches spécifiques

Résultats inexacts

  • Révisez et corrigez au fur et à mesure : le système de découvertes en attente vous permet d'approuver ou de rejeter chaque élément
  • Un code mieux structuré produit de meilleurs résultats
  • Ajoutez des descriptions aux éléments approuvés pour enrichir le contexte des prochaines découvertes

Aucun fichier analysé

  • Vérifiez que votre dépôt est connecté et que la branche existe
  • Assurez-vous que les fichiers source ont des extensions reconnues (.go, .ts, .py, .java, etc.)
  • Vérifiez que le jeton d'accès dispose des droits de lecture sur le dépôt