L'architecture as code apporte la même rigueur que l'infrastructure as code a apportée aux opérations. Ce guide couvre ce qu'est l'AaC, pourquoi elle surpasse les approches purement visuelles, des exemples concrets en YAML et DSL, les workflows de versionnement, l'intégration CI/CD, et comment Archyl rend tout cela pratique.

Architecture as Code : définissez la conception de votre système de manière programmatique

Il y a un pattern en ingénierie logicielle qui se répète tous les quelques années. Une pratique manuelle et visuelle se codifie, se versionne et s'automatise -- et tout s'améliore.

C'est arrivé avec l'infrastructure. On est passé des clics dans les consoles cloud à l'écriture de fichiers Terraform. C'est arrivé avec la configuration. On est passé de l'édition de fichiers de config sur les serveurs à la déclaration de l'état désiré dans les manifestes Kubernetes. C'est arrivé avec les schémas de base de données. On est passé de l'exécution manuelle de scripts SQL à l'écriture de fichiers de migration.

Maintenant c'est au tour de la documentation d'architecture. L'architecture as code est la pratique de définir la conception de votre système de manière programmatique -- dans des fichiers texte structurés qui peuvent être versionnés, revus, testés et déployés à travers les mêmes pipelines que votre code applicatif.

Ce guide couvre tout ce que vous devez savoir sur l'architecture as code : ce que c'est, pourquoi c'est important, comment ça se compare aux approches purement visuelles, et comment l'implémenter en pratique.

Qu'est-ce que l'Architecture as Code ?

L'architecture as code (AaC) est la pratique de définir votre architecture logicielle dans des fichiers texte lisibles par la machine et écrivables par l'humain. Au lieu de dessiner des boîtes et des flèches dans un outil visuel, vous décrivez vos systèmes, containers, components et leurs relations dans un format structuré comme YAML, JSON ou un DSL dédié.

Voici un exemple simple d'architecture définie en YAML :

version: "1.0"

project:
  name: "Payment Platform"
  description: "Gère tout le traitement des paiements pour l'organisation"

systems:
  - name: Payment Platform
    type: software_system
    description: "Système principal de traitement des paiements"
    containers:
      - name: Payment API
        type: api
        description: "API REST pour les opérations de paiement"
        technologies: [Go, gRPC, OpenAPI]
      - name: Payment Processor
        type: service
        description: "Traite les transactions de paiement"
        technologies: [Go]
      - name: Transaction Database
        type: database
        description: "Stocke les enregistrements de transactions"
        technologies: [PostgreSQL]
      - name: Payment Queue
        type: queue
        description: "Queue de traitement asynchrone des paiements"
        technologies: [Kafka]

  - name: Stripe
    type: external_system
    description: "Passerelle de paiement tierce"

relationships:
  - from: Payment API
    to: Payment Processor
    label: "Transmet les requêtes de paiement"
    type: uses
  - from: Payment Processor
    to: Transaction Database
    label: "Persiste les transactions"
    type: writes_to
  - from: Payment Processor
    to: Payment Queue
    label: "Publie les événements de paiement"
    type: publishes_to
  - from: Payment Processor
    to: Stripe
    label: "Effectue les charges via"
    type: uses

Ce fichier est la source de vérité complète pour l'architecture. Un outil comme Archyl le lit, construit le modèle C4, génère des diagrammes interactifs, et garde tout synchronisé. Le fichier vit dans votre dépôt Git, juste à côté du code qu'il décrit.

Pourquoi les approches purement visuelles sont insuffisantes

Avant l'architecture as code, les équipes documentaient typiquement leur architecture avec des outils visuels -- Lucidchart, draw.io, Miro ou Figma. Ces outils sont excellents pour le brainstorming et les sessions de conception initiales, mais ils ont des limitations fondamentales comme documentation à long terme :

Pas de contrôle de version

Les diagrammes visuels sont stockés comme des fichiers binaires ou propriétaires qui ne peuvent pas être diffés de manière significative. Quand quelqu'un change un diagramme, vous pouvez voir qu'il a changé, mais vous ne pouvez pas voir ce qui a changé. Il n'y a pas d'équivalent de git diff pour un fichier draw.io. Vous ne pouvez pas revoir un changement de diagramme dans une pull request comme vous revoyez un changement de code.

Avec l'architecture as code, chaque changement est un diff textuel. Ajouter un nouveau service fait quelques lignes de YAML. Renommer un component est un changement d'une seule ligne. Les reviewers peuvent voir exactement ce qui a changé, pourquoi ça a changé (via le message de commit), et approuver ou demander des modifications.

Pas d'automatisation

Les diagrammes visuels existent en isolation. Ils ne peuvent pas déclencher d'actions, valider des règles ni s'intégrer aux pipelines CI/CD. Si votre diagramme dit que vous avez 10 services mais que votre cluster Kubernetes en fait tourner 12, rien ne détecte la divergence.

L'architecture as code permet l'automatisation. Vous pouvez écrire des règles de validation qui vérifient votre définition d'architecture par rapport à votre infrastructure réelle. Vous pouvez générer de la documentation à partir du fichier d'architecture. Vous pouvez déclencher des alertes quand le fichier d'architecture diverge de la réalité.

Pas de collaboration à l'échelle

Quand deux personnes éditent le même diagramme visuel simultanément, les conflits sont généralement résolus par les changements d'une personne écrasant ceux de l'autre. Il n'y a pas de stratégie de merge pour les fichiers visuels.

Avec l'architecture as code, les workflows Git standard s'appliquent. Deux équipes peuvent modifier différentes parties du fichier d'architecture, et Git les merge proprement. Quand des conflits surviennent, ils sont résolus de la même façon que les conflits de code -- par discussion et résolution intentionnelle.

Pas de garanties de cohérence

Un diagramme visuel peut contenir n'importe quoi. Les boîtes peuvent être étiquetées de manière incohérente. Les flèches peuvent signifier des choses différentes dans différentes parties du même diagramme. Il n'y a pas de schéma, pas de validation, pas d'application de conventions de nommage.

Les fichiers d'architecture as code ont un schéma. L'outillage valide le fichier à chaque changement. Si vous référencez un container qui n'existe pas, la validation le capte. Si vous utilisez un type de relation invalide, c'est signalé avant que le changement ne soit mergé.

Vendor lock-in et portabilité

Les diagrammes visuels sont souvent verrouillés dans l'outil qui les a créés. Migrer de Lucidchart à draw.io signifie recréer manuellement chaque diagramme. Migrer d'un outil d'architecture as code à un autre est une conversion de format -- automatisée et répétable.

Les bénéfices de l'architecture as code

Source unique de vérité

Quand votre architecture est définie dans un seul fichier (ou un ensemble de fichiers), il y a exactement un endroit où chercher. Pas de question sur quel diagramme est à jour, quelle page Confluence a la dernière version, ou si le PDF envoyé par email le mois dernier est encore précis.

Revue de code pour les changements d'architecture

C'est peut-être le bénéfice le plus transformateur. Quand les changements d'architecture passent par des pull requests, ils reçoivent le même examen que les changements de code. Un architecte senior peut revoir un découpage de service proposé avant qu'il ne se produise. L'équipe peut discuter des implications d'une nouvelle dépendance avant qu'elle ne soit introduite.

+ - name: Notification Service
+   type: service
+   description: "Gère les notifications email, SMS et push"
+   technologies: [Python, Celery, Redis]
+
+ - from: Order Service
+   to: Notification Service
+   label: "Déclenche les notifications de commande"
+   type: uses

Ce diff raconte une histoire claire : quelqu'un ajoute un Service de Notification et le connecte au Service de Commandes. Les reviewers peuvent poser des questions, suggérer des technologies alternatives, ou proposer des frontières de services différentes -- tout cela avant qu'une seule ligne de code applicatif ne soit écrite.

L'historique Git est l'historique de l'architecture

Chaque commit sur votre fichier d'architecture crée un enregistrement permanent de l'évolution de l'architecture. Vous pouvez répondre à des questions comme :

Quand le Service de Recherche a-t-il été ajouté ?
Qui a approuvé la migration de MySQL à PostgreSQL ?
À quoi ressemblait l'architecture il y a six mois ?
Comment le nombre de services a-t-il évolué dans le temps ?

Cet historique est inestimable pour comprendre l'évolution de votre système et pour l'onboarding des nouveaux membres de l'équipe.

Intégration CI/CD

L'architecture as code s'intègre naturellement dans les pipelines d'intégration et de déploiement continus. À chaque pull request, vous pouvez :

Valider le fichier d'architecture contre son schéma
Vérifier les règles de conformité (ex. : chaque service doit avoir un propriétaire documenté)
Générer des diagrammes mis à jour
Détecter le drift entre l'architecture documentée et le système en fonctionnement
Publier l'architecture sur votre plateforme de documentation

Cela fait de la documentation d'architecture un artefact vivant plutôt qu'un document statique qui se dégrade.

Refactoring et automatisation

Parce que les définitions d'architecture sont des données structurées, vous pouvez écrire des scripts pour les manipuler. Besoin de renommer un service à travers toutes les relations ? Un simple find-and-replace dans un fichier YAML. Besoin de générer un rapport de tous les services utilisant PostgreSQL ? Parsez le YAML et filtrez par technologie. Besoin d'appliquer une convention de nommage ? Écrivez un linter.

Formats et DSL d'architecture as code

Plusieurs formats et DSL existent pour définir l'architecture as code. Voici un aperçu des approches les plus courantes.

Structurizr DSL

Créé par Simon Brown (le créateur du modèle C4), le DSL Structurizr est l'un des premiers formats d'architecture as code. Il utilise une syntaxe DSL personnalisée :

workspace {
    model {
        user = person "User"
        softwareSystem = softwareSystem "My Software System" {
            webapp = container "Web Application" "Delivers content" "Java"
            database = container "Database" "Stores data" "PostgreSQL"
        }
        user -> webapp "Uses"
        webapp -> database "Reads from and writes to"
    }
    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }
    }
}

Structurizr a été le pionnier du concept d'architecture as code pour les modèles C4. Cependant, sa syntaxe DSL personnalisée a une courbe d'apprentissage, et elle nécessite un outillage spécifique à Structurizr pour le rendu.

Approches basées sur YAML

YAML est devenu le standard de facto pour la configuration déclarative en DevOps (Kubernetes, Docker Compose, GitHub Actions, HCL de Terraform mis à part). Utiliser YAML pour les définitions d'architecture a l'avantage de la familiarité -- la plupart des développeurs savent déjà lire et écrire du YAML.

Le format archyl.yaml d'Archyl adopte cette approche :

version: "1.0"

systems:
  - name: E-Commerce Platform
    type: software_system
    containers:
      - name: Web Frontend
        type: webapp
        technologies: [React, TypeScript, Next.js]
      - name: API Service
        type: api
        technologies: [Go, gRPC]
        components:
          - name: Auth Handler
            type: handler
            technologies: [JWT, OAuth2]
          - name: Product Handler
            type: handler
            technologies: [REST]
      - name: Product Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: Web Frontend
    to: API Service
    label: "Effectue des appels API vers"
  - from: API Service
    to: Product Database
    label: "Lit/écrit les données produits"

L'imbrication reflète directement la hiérarchie C4 : les systèmes contiennent des containers, les containers contiennent des components. Les relations utilisent des noms lisibles par l'humain. Le format est greppable, diffable, et ne nécessite pas d'outillage spécialisé pour être lu.

JSON et autres formats

Certains outils utilisent JSON, TOML ou d'autres formats structurés. Le format spécifique importe moins que les principes : la définition d'architecture doit être textuelle, versionnable et parseable par une machine.

Implémenter l'architecture as code : un workflow pratique

Voici un workflow étape par étape pour adopter l'architecture as code dans votre équipe.

Étape 1 : Partir de l'existant

N'essayez pas de documenter l'intégralité de votre architecture le premier jour. Commencez avec le diagramme de Containers -- le paysage de services. Listez chaque service déployable, sa stack technologique et les relations clés entre services.

Si vous utilisez Archyl, vous pouvez soit créer le modèle visuellement dans l'interface puis l'exporter en archyl.yaml, soit écrire le fichier YAML de zéro. Les deux chemins mènent au même résultat.

Étape 2 : Committer dans votre dépôt

Placez le fichier d'architecture à la racine de votre dépôt principal (ou dans un dépôt d'architecture dédié si votre codebase est répartie sur plusieurs repos). L'emplacement importe moins que le principe : le fichier doit vivre dans Git et passer par la revue de code.

my-platform/
  archyl.yaml        # Définition d'architecture
  src/
  docker-compose.yml
  .github/
    workflows/
      architecture.yml  # Pipeline CI pour l'architecture

Étape 3 : Mettre en place la synchronisation CI/CD

Configurez votre pipeline CI/CD pour synchroniser le fichier d'architecture avec Archyl à chaque merge sur la branche principale. Cela garantit que les diagrammes visuels et la documentation interactive dans Archyl reflètent toujours la dernière architecture committée.

Un workflow GitHub Actions pourrait ressembler à :

name: Sync Architecture

on:
  push:
    branches: [main]
    paths: [archyl.yaml]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to Archyl
        run: |
          curl -X POST https://api.archyl.com/v1/sync \
            -H "Authorization: Bearer ${{ secrets.ARCHYL_TOKEN }}" \
            -H "Content-Type: application/yaml" \
            --data-binary @archyl.yaml

Étape 4 : Faire les changements d'architecture via des pull requests

À partir de ce point, les changements d'architecture suivent le même workflow que les changements de code :

Créer une branche
Modifier le fichier archyl.yaml
Ouvrir une pull request
Faire revoir par l'équipe
Merger sur main
La CI/CD synchronise le changement vers Archyl

Cela donne aux changements d'architecture la même visibilité, responsabilité et traçabilité que les changements de code.

Étape 5 : Ajouter des règles de conformité

À mesure que votre pratique d'architecture as code mûrit, ajoutez des règles de conformité qui valident automatiquement la définition d'architecture. Exemples :

Chaque container doit avoir au moins une technologie spécifiée
Chaque système externe doit avoir une description
Pas de containers orphelins (chaque container doit avoir au moins une relation)
Les conventions de nommage sont respectées (ex. : les services se terminent par "Service")

Le moteur de règles de conformité d'Archyl peut évaluer ces règles automatiquement et rapporter les violations dans le pipeline CI ou dans le dashboard Archyl.

Étape 6 : Faire évoluer la définition dans le temps

Commencez avec les systèmes et containers. Ajoutez des components quand des services spécifiques deviennent assez complexes pour justifier une documentation interne. Ajoutez des ADR à mesure que vous prenez des décisions architecturales importantes. Ajoutez des contrats d'API à mesure que vous formalisez les frontières de services.

Le fichier d'architecture grandit organiquement avec votre système. Pas besoin de tout charger en avance.

Architecture as Code vs. Infrastructure as Code

L'architecture as code et l'infrastructure as code (IaC) sont des pratiques complémentaires mais distinctes.

L'infrastructure as code (Terraform, Pulumi, CloudFormation) définit quoi déployer et comment le configurer. C'est opérationnel : elle provisionne des serveurs, configure des réseaux et gère des ressources cloud.

L'architecture as code définit à quoi ressemble le système et comment ses parties sont reliées. C'est descriptif : elle documente la structure conceptuelle, les choix technologiques et les frontières de services.

La configuration idéale combine les deux :

Vos fichiers Terraform définissent l'infrastructure
Votre archyl.yaml définit l'architecture
Les règles de conformité vérifient que les deux restent alignés

Quand votre Terraform ajoute un nouveau service mais que le fichier d'architecture ne le mentionne pas, la détection de drift capte la divergence.

Architecture as Code avec les assistants IA

Un des avantages les plus convaincants de l'architecture as code est que les assistants IA peuvent la lire et raisonner dessus. Quand votre architecture est définie en texte structuré, des outils comme Claude Code et Cursor peuvent :

Répondre aux questions sur votre architecture en interrogeant le fichier YAML
Suggérer des changements d'architecture basés sur l'état actuel
Générer du code qui respecte l'architecture documentée (ex. : utiliser la bonne base de données pour le bon service)
Détecter des incohérences entre le code et la définition d'architecture

Archyl va plus loin avec son serveur MCP. Les assistants IA ne se contentent pas de lire le fichier d'architecture -- ils peuvent interroger le modèle d'architecture en direct, parcourir les relations, et même proposer des modifications. L'architecture devient une source de données programmable et interrogeable plutôt qu'un document statique.

Pièges courants

Sur-ingénierer le format

Ne concevez pas un DSL personnalisé quand YAML ou un format existant fonctionne. L'objectif est l'adoption, et l'adoption est plus facile quand le format est familier. La plupart des développeurs connaissent déjà YAML grâce à Docker Compose, Kubernetes et les configurations CI/CD.

Essayer de tout capturer

L'architecture as code devrait capturer les aspects structurels de votre système : ce qui existe, comment les choses se connectent, et quelles technologies sont utilisées. N'essayez pas d'intégrer les détails opérationnels (comme les politiques de scaling), les configurations runtime (comme les variables d'environnement), ou les spécifications comportementales (comme les formats de réponse API) dans le fichier d'architecture.

Ne pas appliquer le workflow

L'architecture as code ne fonctionne que si les changements passent par le workflow défini. Si les gens contournent le fichier d'architecture et font des changements directement dans l'outil visuel, le fichier devient obsolète. Établissez des conventions claires sur quelle direction fait autorité.

Ignorer le rendu visuel

L'architecture as code n'est pas un remplacement des diagrammes visuels -- c'est une meilleure façon de les produire. Le fichier texte est la source de vérité, mais les diagrammes rendus sont ce que les gens regardent réellement au quotidien. Assurez-vous que le rendu visuel est accessible, à jour et facile à naviguer.

Démarrer avec Archyl

Archyl est conçu de A à Z pour supporter l'architecture as code. La plateforme fournit :

DSL basé sur YAML qui couvre le modèle C4 complet avec systèmes, containers, components, relations et technologies
Synchronisation bidirectionnelle -- modélisez visuellement dans l'interface et exportez en YAML, ou écrivez du YAML et synchronisez vers l'interface
Intégration CI/CD pour la synchronisation automatisée à chaque commit
Règles de conformité qui valident la définition d'architecture contre vos standards
Serveur MCP qui rend l'architecture interrogeable par les assistants IA
Fonctionnalités de collaboration avec revue de code, commentaires et propriété par équipe

Que vous partiez de zéro ou que vous migriez depuis des diagrammes visuels, Archyl rend l'architecture as code pratique pour les équipes de toute taille.

Démarrez avec l'architecture as code et apportez la même rigueur à votre documentation d'architecture que vous apportez déjà à votre infrastructure et votre code applicatif.

Architecture as Code : définissez la conception de votre système de manière programmatique - Archyl Blog