Demander à une intelligence artificielle de dessiner une architecture système produit souvent le même résultat décevant : une grille uniforme, six rectangles alignés au cordeau et des flèches enchevêtrées qui ignorent la réalité du terrain.
Le problème fondamental ne réside pas dans la couleur des boîtes. Il réside dans la distribution spatiale de l’information.
Archify prend le contre-pied exact des moteurs de rendu usuels. Conçu comme une compétence (agent skill) pour Raven, Cursor, Claude Code, Codex CLI et OpenCode, cet outil transforme une description textuelle ou l’analyse d’un dépôt Git en une cartographie technique interactive, autonome et vérifiable, compilée dans un unique fichier HTML.
Pourquoi rejeter les moteurs de disposition automatique ?
Le projet — issu d’une réécriture de la branche v1 de Cocoon AI sous licence MIT — repose sur un constat tranché : confier le positionnement spatial à des bibliothèques comme Dagre ou ELK produit des schémas inertes. L’équipe a mené une expérience à l’aveugle sur cinq diagrammes réels :
- Version A : Rendu natif Mermaid avec Dagre et thème standard.
- Version B : Même disposition Dagre, mais habillée avec la palette sombre d’Archify, la police JetBrains Mono et un fond ardoise.
- Version C : Disposition manuelle où Claude attribue des classes sémantiques et définit les coordonnées exactes avant l’application du CSS.
Le résultat consigné dans le dépôt est sans appel : C est lisible et pertinent ; A et B échouent. Changer les couleurs sans toucher à la disposition spatiale ne comble aucun écart visuel. Une grille uniforme peinte avec de jolies teintes reste une grille uniforme.
L’esthétique d’un schéma d’architecture provient de son récit spatial, pas de ses couleurs. Quand S3 se trouve sous CloudFront plutôt qu’à côté, cela exprime une hiérarchie de cache, pas un rôle pair.
Archify applique le principe du jugement dans la boucle (Judgment-in-the-Loop). L’humain ou l’agent saisit la sémantique — par exemple, qu’un fournisseur d’identité externe flotte en dehors du périmètre AWS. Le moteur applique des contraintes strictes au lieu d’inventer une topologie arbitraire.
Installation et intégration aux agents
Vous pouvez découvrir et tester le projet via sa documentation interactive ou l’installer directement sur votre machine de développement.
Pour ajouter Archify globalement à vos outils CLI :
npx skills add tt-a1i/archify -gPour une installation explicite et non interactive sous Cursor :
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yesPour tester ponctuellement sans installation persistante :
npx skills use tt-a1i/archify@archify --agent codexL’intégration couvre plusieurs environnements cibles :
| Environnement | Emplacement / Méthode | Capacités actives |
|---|---|---|
| Raven | Extraction manuelle de archify.zip dans ~/.raven/workspace/skills/archify | Rendu complet et boucle de validation |
| Claude Code | ~/.claude/skills/ ou .claude/skills/ | Rendu complet et boucle de validation |
| Codex CLI | ~/.agents/skills/ ou .agents/skills/ | Rendu complet et boucle de validation |
| OpenCode | ~/.config/opencode/skills/ ou .opencode/skills/ | Rendu complet et boucle de validation |
| Claude.ai | Téléversement du ZIP dans Settings → Capabilities → Skills | Lié à l’accès Node.js du bac à sable |
| DeepSeek Harness (DSH) | dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0 | Intégration communautaire sans télémétrie |
Les cinq types de diagrammes
Chaque vue répond à un besoin d’analyse précis et s’appuie sur son propre schéma JSON typé.
| Type | Cas d’usage optimal | Éléments à fournir dans votre prompt |
|---|---|---|
| Architecture | Composants, services, stockage et frontières réseau | Périmètre, 8 à 12 composants clés, chemin primaire, dépendances |
| Workflow | Pipelines CI/CD, validations humaines, appels d’outils | Acteurs, couloirs (lanes), étapes séquentielles, branches de repli |
| Sequence | Appels API synchrones, échecs de cache, authentification | Émetteurs, récepteurs, retours de fonctions, chronologie |
| Data Flow | Pipelines de données, conformité PII, consommation d’événements | Sources de données, transformations, magasins, frontières de sensibilité |
| Lifecycle | Machines à états, boucles de réessai, abandons, états terminaux | États nommés, transitions déclenchées, conditions d’annulation |
Le flux d’exécution : validation atomique et auto-réparation
Le fonctionnement interne d’Archify suit un pipeline rigide en cinq temps :
- Génération : L’agent produit une représentation intermédiaire (IR) en JSON typé contenant impérativement
schema_version: 1. - Validation : Les règles de disposition vérifient les collisions de nœuds, les dépassements d’étiquettes et les croisements de couloirs. En cas d’erreur, le système renvoie un objet JSON structuré (contenant le chemin du champ, les entités en conflit et la mesure exacte) permettant à l’IA de corriger son code sans intervention humaine.
- Prévisualisation locale : Un serveur interne écoute sur
127.0.0.1via un port aléatoire, recharge la page uniquement si le JSON est valide, et conserve le dernier état sain en cas de syntaxe incomplète. - Livraison (Deliver) : Le fichier HTML final est écrit de manière atomique sur le disque.
- Itération : Vous ajustez la structure au fil des discussions dans le chat sans casser la stabilité visuelle des blocs adjacents.
# Vérification de l'environnement
node bin/archify.mjs doctor
# Obtenir une recommandation de structure selon votre besoin
node bin/archify.mjs guide "Show an API request with Redis cache miss"
# Valider un fichier avec sortie JSON exploitable par l'agent
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
# Lancer la prévisualisation réactive sur le poste de travail
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
# Livrer le fichier HTML final et l'ouvrir
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --jsonA lire — Claude Context : Intègrer tout votre Codebase dans Claude Code sans exploser le budget Tokens
Exemple d’application concrète : Cartographie de flux d’authentification
Voici comment demander une vue d’authentification complète à votre assistant :
Trace l’architecture d’authentification suivante : Navigateur -> Application Web -> Passerelle API -> Validation JWT -> Recherche de session Redis -> Repli sur base PostgreSQL. Fais ressortir le chemin nominal et place la recherche en base comme secondaire.
L’agent configure les métadonnées pour contrôler l’aspect visuel sans modifier le contenu sémantique :
{
"schema_version": 1,
"meta": {
"locale": "en",
"animation": "trace",
"visual_preset": "signal-flow"
},
"nodes": [
{ "id": "browser", "label": "Client Web", "kind": "client" },
{ "id": "api_gw", "label": "API Gateway", "kind": "gateway" },
{ "id": "redis", "label": "Redis Session Store", "kind": "cache" },
{ "id": "pg", "label": "PostgreSQL Primary", "kind": "database" }
]
}Navigation interactive et partage
Le document HTML généré n’est pas une image figée. Il intègre un moteur de navigation accessible au clavier :
| Touche / Commande | Effet dans la vue interactive |
|---|---|
| ? | Ouvre le guide factuel du diagramme |
| / | Active la recherche et sélectionne un composant |
| R ou PATH | Sonde le chemin direct le plus court entre deux composants |
| L ou LENS | Compare le trafic et les liens entre deux rôles sémantiques |
| M ou MAP | Affiche la carte radar de vue d’ensemble |
| P ou [ / ] | Lance ou fait défiler une histoire guidée par étapes |
| F | Bascule en mode présentation plein écran |
| S / T / E | Fait défiler les styles / Alterne mode sombre et clair / Ouvre le menu d’export |
| + / – / 0 | Contrôle le zoom ou réinitialise l’échelle |
L’état de votre exploration s’encode directement dans l’URL (#focus=<id>, #route=<source>~<target>, #lens=<kind>~<kind>). Vous transmettez ainsi une vue ciblée sans forcer votre interlocuteur à chercher le composant manuellement.
Le menu d’export génère des cartes de partage standardisées au format 1200×630 pixels adaptées aux aperçus GitHub et aux réseaux sociaux. L’image capture le chemin inspecté ou la portée amont/aval tout en conservant le reste de l’architecture en arrière-plan.
Analyse de changements avec Architecture Delta
Lors d’une revue de Pull Request, vous pouvez comparer deux états d’un système sans inférer de faux risques d’infrastructure :
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --jsonL’interface met en évidence les nœuds ajoutés, retirés, déplacés et les flux réorientés, accompagnés d’un reçu machine certifiant les différences constatées entre les deux instantanés.
Décisions de conception : ce qui a été délibérément écarté
La feuille de route d’Archify détaille les fonctions rejetées pour préserver la robustesse de l’outil :
| Fonctionnalité rejetée | Raison du refus |
|---|---|
| Moteur auto-layout Dagre / ELK | Les tests à l’aveugle prouvent qu’une disposition automatique dégrade la lecture architecturale. |
| Pipeline d’importation Mermaid | Le marché des thèmes Mermaid est déjà saturé et ne répond pas aux besoins d’organisation spatiale. |
Paramètre ?exportScale=N | Inutile car le moteur intègre une rastérisation native 4x sans perte de netteté. |
Liens compressés gzip + base64 | Ouvre des failles XSS et bute sur la taille maximale des URL. L’envoi direct du fichier HTML reste plus sain. |
| Palettes spécifiques pour le daltonisme | Le système de variables CSS permet aux équipes d’adapter les contrastes en une trentaine de lignes de code. |
| Bouton d’export PDF dédié | L’impression native du navigateur (Cmd + P) gère parfaitement la mise en page grâce aux feuilles de style dédiées. |
| Interface multi-langues lourde | L’interface reste minimaliste pour éviter les surcharges de maintenance. |
Limites et cas d’échec connus
Le choix d’Archify implique des contraintes opérationnelles bien précises :
- Topologies massives : Au-delà d’une trentaine de microservices ou de topologies multi-régions complexes, le modèle de langage perd sa vision d’ensemble et commence à placer les composants de manière erratique. Dans ce cas précis, une grille Dagre traditionnelle évite les erreurs grossières d’agencement.
- Prompts flous : Si vous demandez simplement « Fais-moi un schéma », l’outil ne saura pas quelles frontières d’isolation ou flux de données valoriser. Vous devez spécifier les rôles et les zones de confiance.
- Schémas sans portée spatiale : Pour un enchaînement basique de quatre actions sans hiérarchie technique, passer par le schéma JSON et les validateurs représente un coût disproportionné par rapport à un tracé rapide sur un tableau blanc virtuel.
Archify traite le diagramme d’architecture comme un document technique rigoureux. Chaque élément graphique y traduit une décision d’ingénierie explicite, vérifiée par des schémas stricts avant même la première ouverture dans votre navigateur.