Keeping architecture models in sync with the code: Archi, Freeplane and Mermaid
Which model to update for which change (new app, resource, pipeline or a simple rename), backups before editing XML, export and review.
An architecture model that is out of date is worse than no model: people trust it wrongly. On my DBA scripts platform I maintain three complementary artefacts, with simple rules about which one to update and when.
The three artefacts
| Artefact | Tool | Role | Where it lives |
|---|---|---|---|
Formal .archimate model + exported image |
Archi | Three-layer architecture view, typed relationships | docs/architecture/ folder of the repository |
Mind map .mm |
Freeplane | Browsable inventory; each leaf links to a file in the workspace | Same folder |
Mermaid views .mmd |
Text editor | Readable mirror in the repository, diffable in review | Next to the code |
The .archimate file is XML: it can be edited by hand or by script, and it versions well. The exported image (JPG or PNG) lets people read the model without installing Archi. In the Freeplane map, links are relative to the map folder: Ctrl+click opens the script or folder concerned.
When to update which
The basic rule: the granularity of the change decides which model is touched.
| Change | Formal model | Mind map | Mermaid mirrors |
|---|---|---|---|
| New application or module | Yes (component, relationships, view) | Yes (new leaf with link) | Yes |
| New Azure resource in use | Yes (node, serving relationship) | Yes | If the view shows it |
| New pipeline or trigger | Yes (execution view) | Yes | Yes |
| Function renamed | No, too fine-grained | Yes, if the leaf names it | No |
| Configuration schema change | No | Maybe | No |
The formal model stays deliberately coarse; the mind map goes down to function level.
The sync workflow
flowchart TD
A["Code change"] --> B{"Structural?"}
B -->|"No (rename, config)"| C["Update the mind map leaf"]
B -->|"Yes (app, resource, pipeline)"| D["Back up the .archimate as .bak"]
D --> E["Edit the model in Archi or in XML"]
E --> F["Load the model from the command line"]
F --> G["Export the images"]
G --> H["Update the mind map"]
H --> I["Regenerate the Mermaid mirrors"]
C --> J["Review the diff"]
I --> J
J --> K["Commit with the code"]
Backup before editing the XML
Editing XML by hand is quick, but one broken tag makes the model unreadable. I always copy the file first:
$model = 'docs/architecture/platform.archimate'
Copy-Item -Path $model -Destination "$model.bak" -Force
# After editing: check it is still well-formed XML
[xml]$xml = Get-Content -Path $model -Raw
$xml.model.name
To check that Archi really loads the model, its command line generates a report; exit code 0 and a load message are enough as a check. The same command line can export the images, so the graphical interface is not needed.
Example of a relationship added by hand (fictional ids):
<element xsi:type="archimate:ServingRelationship"
id="r-module-newapp"
source="am-module"
target="am-newapp"/>
Pitfall: a relationship must also be listed in the connections of its ends in the view, otherwise Archi draws it in the wrong place. I check this in the export script.
Review
The model follows the same path as the code: the XML diff (and the map's) is reviewed in the same pull request as the script. I ask the AI assistant to compare the model with the code, but I decide: a model that disagrees with the code is a defect to report, not a truth. Exported images are looked at by eye before the commit.
Lessons learned
- A written rule beats goodwill. I put it in the repository instructions: every new application, resource or pipeline implies updating the models.
- Do not model everything. Hand-run utilities stay out of the formal model; they are in the repository index.
- Export by script. A hand-made image always ends up forgotten.
- Date the alignment. A sentence like "aligned with the repository on dd/mm" tells the reader how far to trust the model.