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
- Une règle écrite vaut mieux qu'une bonne volonté. Je l'ai mise dans les instructions du dépôt : toute nouvelle application, ressource ou pipeline implique la mise à jour des modèles.
- Ne pas tout modéliser. Les utilitaires lancés à la main restent hors du modèle formel ; ils sont dans l'index du dépôt.
- Exporter par script. Une image générée à la main finit toujours par être oubliée.
- Dater l'alignement. Une phrase « aligné avec le dépôt le jj/mm » dans le README dit au lecteur à quel point faire confiance au modèle.