LLI Wiki — My Digital Knowledge Base

Garder les modèles d'architecture synchronisés avec le code : Archi, Freeplane et Mermaid

Quel modèle mettre à jour selon le changement (nouvelle application, ressource, pipeline ou simple renommage), sauvegarde avant édition du XML, export et revue.

Un modèle d'architecture qui n'est plus à jour est pire que pas de modèle : on lui fait confiance à tort. Sur ma plateforme de scripts DBA, j'entretiens trois artefacts complémentaires, et j'ai fixé des règles simples sur quand mettre à jour lequel.

Les trois artefacts

Artefact Outil Rôle Où il vit
Modèle formel .archimate + image exportée Archi Vue d'architecture en trois couches, relations typées Dossier docs/architecture/ du dépôt
Carte mentale .mm Freeplane Inventaire navigable ; chaque feuille porte un lien vers le fichier du workspace Même dossier
Vues Mermaid .mmd Éditeur de texte Miroir lisible dans le dépôt, diffable en revue À côté du code

Le .archimate est un fichier XML : on peut l'éditer à la main ou par script, et il se versionne. L'image exportée (JPG ou PNG) permet de lire le modèle sans installer Archi. Dans la carte Freeplane, les liens sont relatifs au dossier de la carte : Ctrl+clic ouvre le script ou le dossier concerné.

Quand mettre à jour quoi

La règle de base : la granularité du changement décide du modèle touché.

Changement Modèle formel Carte mentale Miroirs Mermaid
Nouvelle application ou nouveau module Oui (composant, relations, vue) Oui (nouvelle feuille avec lien) Oui
Nouvelle ressource Azure utilisée Oui (nœud, relation de service) Oui Si la vue la montre
Nouveau pipeline ou nouveau déclencheur Oui (vue d'exécution) Oui Oui
Fonction renommée Non, trop fin Oui, si la feuille la nomme Non
Changement de schéma de configuration Non Éventuellement Non

Le modèle formel reste volontairement grossier ; la carte mentale, elle, descend jusqu'aux fonctions.

Le workflow de synchronisation

flowchart TD
    A["Changement de code"] --> B{"Structurel ?"}
    B -->|"Non (renommage, config)"| C["Mettre à jour la feuille de la carte mentale"]
    B -->|"Oui (app, ressource, pipeline)"| D["Sauvegarde .bak du .archimate"]
    D --> E["Éditer le modèle dans Archi ou en XML"]
    E --> F["Charger le modèle en ligne de commande"]
    F --> G["Exporter les images"]
    G --> H["Mettre à jour la carte mentale"]
    H --> I["Régénérer les miroirs Mermaid"]
    C --> J["Revue du diff"]
    I --> J
    J --> K["Commit avec le code"]

Sauvegarde avant d'éditer le XML

Éditer le XML à la main est rapide, mais une balise cassée rend le modèle illisible. Je copie toujours le fichier avant :

$model = 'docs/architecture/platform.archimate'
Copy-Item -Path $model -Destination "$model.bak" -Force

# Après édition : contrôler que c'est toujours du XML bien formé
[xml]$xml = Get-Content -Path $model -Raw
$xml.model.name

Pour vérifier qu'Archi charge vraiment le modèle, sa ligne de commande génère un rapport ; un code retour 0 et un message de chargement suffisent comme contrôle. La même commande peut servir à exporter les images, ce qui évite de passer par l'interface graphique.

Exemple de relation ajoutée à la main (identifiants fictifs) :

<element xsi:type="archimate:ServingRelationship"
         id="r-module-newapp"
         source="am-module"
         target="am-newapp"/>

Piège : une relation doit aussi apparaître dans les connexions de ses extrémités sur la vue, sinon Archi la dessine au mauvais endroit. Je vérifie cela dans le script d'export.

Revue

Le modèle suit le même chemin que le code : le diff XML (et celui de la carte) est relu dans la même demande de fusion que le script. Je demande à l'assistant IA de comparer le modèle au code, mais je tranche : un modèle qui contredit le code est une anomalie à signaler, pas une vérité. Les images exportées sont regardées à l'œil avant le commit.

Retour d'expérience

Mastodon LLIMastodon SocialFosstodon