Architecture as Code : Définissez votre modèle C4 complet dans un fichier YAML

Les diagrammes d'architecture ont un problème de durée de vie. Vous les dessinez après une session de conception, ils sont superbes pendant une semaine, puis le code évolue tandis que les diagrammes pourrissent. Six mois plus tard, le nouveau venu fixe un diagramme de Containers qui montre trois services fusionnés au T2 et ne mentionne pas les deux construits au T3.

Ce problème nous obsède depuis le premier jour chez Archyl. La découverte par IA aide à garder les choses à jour. L'éditeur visuel rend les mises à jour indolores. Mais il y a une catégorie d'équipes — celles qui traitent l'infrastructure as code, les politiques as code, tout as code — qui voulaient quelque chose de plus fondamental.

Elles voulaient que leur architecture vive dans Git, à côté du code qu'elle décrit. Aujourd'hui, c'est exactement ce que nous livrons.

Qu'est-ce que archyl.yaml ?

C'est un fichier YAML unique qui décrit de manière déclarative votre architecture complète. Déposez-le à la racine de votre dépôt, et il devient la source de vérité pour votre modèle C4 dans Archyl.

Voici à quoi ressemble un fichier minimal :

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

C'est tout. Archyl lit ce fichier, construit le modèle C4 complet, génère les diagrammes et garde tout synchronisé. Plus de clics dans des interfaces, plus de synchronisation manuelle, plus de « j'ai oublié de mettre à jour le diagramme ».

Tout dans un seul fichier

Le DSL n'est pas un sous-ensemble simplifié — il couvre l'intégralité de ce qu'Archyl peut modéliser :

Les quatre niveaux C4. Les systèmes contiennent des containers, les containers contiennent des composants, les composants contiennent des éléments de code. L'imbrication YAML reflète directement la hiérarchie.

Relations avec notation par points. Connectez deux éléments quelconques en utilisant des références lisibles comme Payment Service.API Gateway → Payment Service.Database. Pas d'UUID, pas d'identifiants cryptiques. Cherchable avec grep, compatible avec les diffs, lisible par un humain.

Technologies, environnements et releases. Définissez votre catalogue technologique, déclarez vos environnements de déploiement (staging, production) et suivez les releases — le tout depuis le même fichier.

ADR et documentation. Intégrez vos Architecture Decision Records ou pointez vers un dossier dans votre dépôt. Idem pour la documentation du projet.

Contrats d'API et canaux d'événements. Déclarez vos spécifications OpenAPI, définitions gRPC, topics Kafka, et liez-les aux composants qui les exposent ou les consomment.

Overlays visuels. Regroupez des éléments sur le diagramme avec des overlays nommés, en contrôlant les couleurs et les niveaux.

Support monorepo. Utilisez include pour répartir votre architecture sur plusieurs fichiers — un par service, équipe ou contexte borné — et Archyl les fusionne automatiquement.

Pourquoi YAML ?

Nous avons envisagé de créer une syntaxe DSL personnalisée (comme le DSL de Structurizr ou le HCL de Terraform). Nous avons choisi YAML pour des raisons pratiques :

1. Aucune courbe d'apprentissage. Chaque développeur connaît déjà YAML. Pas de nouvelle syntaxe à apprendre, pas de parser à installer, pas de plugin d'éditeur requis.

2. Support IDE gratuit. Nous publions un JSON Schema sur /api/v1/dsl/schema. Pointez votre IDE dessus et vous obtenez l'autocomplétion, la validation et la documentation inline sans outillage spécifique à Archyl.

3. Compatible avec les diffs. Les diffs YAML sont propres et lisibles dans les pull requests. Les relecteurs voient immédiatement « ah, ils ont ajouté un nouveau container au Payment Service et l'ont connecté à Redis ».

4. Écosystème d'outils. Linters, formateurs, moteurs de templating (Helm, Kustomize), tout fonctionne avec YAML nativement.

Le workflow Git-natif

C'est là que réside la vraie puissance. Parce que archyl.yaml vit dans votre dépôt, les changements d'architecture suivent le même workflow que les changements de code :

1. Branch. Créez une branche feature, modifiez le YAML.
2. Review. Ouvrez une pull request. Votre équipe revoit le changement d'architecture en même temps que le changement de code.
3. Merge. Une fois approuvé, mergez dans main.
4. Sync. Archyl détecte le changement et met à jour les diagrammes automatiquement.

Plus de « le diagramme dit X mais le code fait Y ». Plus de changements d'architecture qui contournent la revue. Plus de documentation que personne ne sait avoir été mise à jour.

Intégration CI/CD

Nous avons construit une intégration de premier ordre avec les pipelines CI/CD. Pour GitHub, nous fournissons une GitHub Action officielle qui gère tout — lecture du fichier, appel de l'API et rapport des changements.

GitHub Actions (action officielle) :

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

C'est tout. Trois lignes de config et votre architecture reste synchronisée à chaque push. L'action supporte les chemins de fichiers personnalisés (pour les monorepos), les instances Archyl auto-hébergées, et expose des outputs comme summary, systems-created et relationships-created pour les étapes suivantes.

GitLab CI :

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

L'endpoint /ingest accepte l'authentification par clé API, donc aucun flux OAuth n'est nécessaire en CI. Il importe le modèle complet, crée ou met à jour chaque élément, et retourne un résumé détaillé de ce qui a changé.

Vous pouvez également synchroniser directement depuis l'UI d'Archyl. Si votre projet a un dépôt Git connecté, cliquez sur « Synchroniser maintenant » dans les paramètres Architecture as Code et Archyl récupère le fichier directement depuis votre dépôt.

Bidirectionnel : Export et Import

Le workflow n'est pas unidirectionnel. Vous avez déjà un projet modélisé dans l'éditeur visuel d'Archyl ? Exportez-le :

• Export génère un archyl.yaml complet à partir de votre modèle actuel. Chaque système, container, composant, relation, overlay, ADR, contrat d'API, canal d'événements, release — tout est sérialisé en YAML propre.
• Import parse un archyl.yaml et crée ou met à jour tous les éléments de votre projet. C'est idempotent : importer le même fichier deux fois ne crée pas de doublons. Les éléments sont identifiés par nom et upsertés.
• Import as Project crée un tout nouveau projet à partir d'un fichier YAML. Déposez un archyl.yaml et obtenez un projet entièrement peuplé en un clic.

Cela signifie que vous pouvez commencer dans l'UI, exporter en YAML, commiter dans Git et basculer vers le workflow code-first — ou faire l'inverse. Aucun verrouillage sur l'une ou l'autre approche.

Résolution intelligente des références

L'une des parties les plus délicates du DSL est la résolution des références d'éléments dans les relations, overlays, événements et contrats d'API. Nous avons construit un résolveur qui gère cela naturellement :

• Noms courts quand c'est non ambigu : API Gateway résout directement s'il n'y a qu'un seul élément portant ce nom.
• Notation par points pour désambiguïser : Payment Service.API Gateway vs Analytics.API Gateway.
• Toute profondeur fonctionne : System.Container.Component.CodeElement pour les références profondément imbriquées.

Le résolveur indexe chaque élément à chaque profondeur de chemin possible, vous utilisez donc toujours la référence non ambiguë la plus courte. Les exports utilisent la même logique en sens inverse — produisant les références les plus lisibles possibles.

Validation sans effets de bord

Pas sûr que votre YAML soit valide ? L'endpoint /validate (et le bouton « Valider » dans la modale d'import) parse et vérifie votre fichier sans toucher à la base de données :

• Vérification de la version du schéma
• Validation des champs obligatoires
• Détection des noms en double
• Validation des types énumérés (types de containers, types de relations, etc.)
• Résolution des références croisées

Les erreurs reviennent avec des chemins précis (systems[2].containers[1].name) et des messages clairs. Intégrez-le dans un hook pre-commit ou un check CI et détectez les problèmes avant qu'ils n'atteignent main.

Patterns du monde réel

Le Monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

Chaque service maintient son propre archyl.yaml définissant ses containers et composants. Le fichier racine les fusionne, et les relations inter-services sont définies au niveau racine. Les technologies et environnements sont dédupliqués automatiquement.

Le Bootstrapper

Vous démarrez un nouveau projet ? Créez un archyl.yaml avant d'écrire la moindre ligne de code. Définissez les systèmes et containers que vous prévoyez de construire. Utilisez « Import as Project » d'Archyl pour générer l'architecture instantanément. Au fur et à mesure que vous développez, le YAML évolue avec le code.

La piste d'audit

Parce que le YAML est dans Git, vous obtenez l'historique complet gratuitement. git log archyl.yaml montre chaque changement d'architecture, qui l'a fait, quand, et la PR où il a été discuté. Essayez d'obtenir ça avec un outil de diagrammes.

Le générateur de documentation

Exportez votre architecture en YAML, puis passez-la dans n'importe quel moteur de templates pour générer des docs Markdown, des pages Confluence ou des wikis internes. Le format structuré rend l'automatisation triviale.

Et ensuite

C'est la version 1.0 du format DSL. Voici ce sur quoi nous travaillons ensuite :

Détection de dérive. Comparer le YAML dans votre dépôt avec le modèle en production et mettre en évidence les différences — éléments ajoutés dans l'UI mais pas dans le fichier, ou vice versa.

Commentaires de prévisualisation sur les PR. Quand une PR modifie archyl.yaml, un bot commente avec un diff visuel de ce qui a changé dans l'architecture.

Évolution du schéma. À mesure que nous ajoutons de nouvelles fonctionnalités à Archyl, le DSL grandira. Nous maintiendrons la compatibilité ascendante et fournirons des outils de migration.

Essayez-le maintenant

Architecture as Code est disponible dès aujourd'hui sur tous les plans Archyl. Si vous avez déjà un projet :

1. Allez sur la page Architecture as Code de votre projet
2. Cliquez sur Export pour générer votre archyl.yaml
3. Commitez-le dans votre dépôt
4. Ajoutez la GitHub Action officielle à votre workflow et c'est terminé

Si vous partez de zéro, créez un archyl.yaml, utilisez Import as Project, et vous aurez une architecture C4 entièrement rendue en quelques secondes.

Votre architecture mérite la même rigueur que votre code. Versionnez-la, révisez-la, automatisez-la.

Nouveau avec le C4 ? Commencez par notre Introduction au modèle C4. Vous voulez que l'IA génère l'architecture initiale ? Voir Découverte d'architecture par IA. Vous utilisez déjà des assistants IA ? Connectez-les via notre Serveur MCP.