ArchiMate tool alternative: keep the model, generate the layer that rots

Archi implements ArchiMate 3.2, the current version of the Open Group standard, in a desktop application built on the Eclipse platform and available for Windows, macOS, and Linux. It is free and open source, which is a large part of why ArchiMate practice spread beyond the organizations that could afford a modelling suite.

The tooling around the modelling is practical rather than showy: a hints view that explains elements and relationships while you work, a visualiser that shows an element and its connections as a radial tree, a sketch view for stickies before the model exists, a canvas toolkit for custom canvasses, user-defined properties, and a plug-in ecosystem for model collaboration and scripting.

For business capability maps, application landscapes, and the governance work an EA practice exists to do, none of that is replaceable by a diagram generator, and this page is not proposing it should be.

ArchiMate layers age at different speeds. A business capability map is stable for years. An application landscape shifts a few times a year. The technology layer, the nodes, the system software, the artefacts, the technology services, changes every time a team merges a Terraform module or adds a Helm chart, which is roughly every week.

Nothing in a modelling tool observes that. Elements are entered by a person, so the technology layer is as current as the last modelling workshop, and the interval between workshops is measured in quarters. The result is an EA repository whose upper layers are trusted and whose lower layer is quietly known to be wrong, which is worse than having no lower layer.

That matters most at exactly the moments the model is supposed to earn its keep: an audit, a cloud migration assessment, a security review, an incident where somebody needs to know what actually depends on what.

Datadef connects to a repository on GitHub, GitLab, or Azure DevOps read-only, tracks a branch or tag, and generates a diagram plus an architecture.md from the files that declare the technology: infrastructure as code, containers and orchestration, database schemas and dbt models, API specs, CI pipelines, and manifests. A daily sync regenerates both when the code moves.

The mapping onto technology-layer concepts is direct enough to be worth stating. Nodes and system software come from Dockerfiles, compose files, and Kubernetes or Helm manifests. Technology services and the artefacts behind them come from infrastructure as code, where a managed database, a queue, or a network is declared rather than remembered. Deployment paths come from the CI workflows. For a Terraform repository the generated document also carries a module reference table, one row per module with its source, its resource count, and its multiplicity, composed from the parse rather than written by a model, which is the inventory an architect otherwise rebuilds by hand before every review.

It is not an ArchiMate tool. There is no notation conformance, no model repository, no capability maps, no formal derivation between layers. It draws zones, nodes with real icons, and labelled edges from what the repository declares, exports as PNG or JPEG, and embeds as a live image in a wiki page or a review pack.

The pattern that works is subordination rather than replacement: the EA practice keeps the model, and the generated diagram sits under the technology layer as evidence, refreshed automatically, so the architects are reviewing something true instead of reconstructing it from memory before every board.

Model by hand what humans decide: capabilities, value streams, the target application landscape, the principles. Generate what machines already know: what infrastructure exists, which services are deployed, what the pipelines build, which datastores are declared.

The test for any element in your technology layer is simple. If it could be read from a repository, maintaining it by hand is a recurring cost with no upside, and the hours are better spent on the layers where judgment is the actual work.

• Keep architecture docs in sync with code
• Why documentation goes stale
• Datadef compared with Visio
• Repo to diagram: repository sync