LLI Wiki — My Digital Knowledge Base

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

Mastodon LLIMastodon SocialFosstodon