Engineering workflow

Architecture as code: keeping diagrams close to the system they describe

Text-based architecture artifacts can make review and version history easier. They work best when they stay connected to a visual model that engineers and stakeholders can actually read.

Architecture diagrams often start in a meeting and end up stranded in a folder. A screenshot may be clear on the day it is made, but it is hard to review alongside a code change, compare over time, or confidently edit without the original source. “Architecture as code” aims to bring those diagrams into the engineering workflow: store a structured representation with the project, review edits, and update it as the system evolves.

This does not mean every architecture conversation should begin with YAML. A visual canvas helps people reason spatially and quickly explore alternatives. A text representation helps with repeatable changes, version control, and tooling. The useful approach is to make the two complement one another, and to decide which details are important enough to maintain.

What “as code” changes

When a diagram has a source file, its changes can be committed and discussed with other project changes. A reviewer can see that an API was added or a service relationship changed, and ask whether the code and architecture description agree. The representation is also easier to copy, search, or generate than a screenshot.

These benefits are not automatic. Text diffs can be noisy if a tool rewrites unrelated formatting. A successful parse does not prove that a diagram is accurate. Teams still need an owner, a reason to update the model, and a useful scope. Keep the architecture model focused on boundaries, responsibilities, and important flows rather than mirroring every source file.

Use a loop, not a one-time export

1. Choose a bounded subject. Start with one service, product area, or workflow that people need to understand.
2. Record the important structure. Name the elements, boundaries, and connections that explain the subject.
3. Review the model with code context. Ask whether a proposed change alters ownership, dependencies, data stores, or external interactions.
4. Update the diagram with the implementation. Keep the model change in the same review when it is useful, or explain the delay when it is not.
5. Render and inspect it. A valid source file can still produce an unreadable picture; check the view at the scale its audience will use.

Where tld fits

The open-source tld project describes a diagramming workflow with a visual interface and CLI. Its README documents syncing local YAML files with a self-hosted web UI and the tlDiagram cloud version, plus commands for listing and updating diagram elements, connectors, and views. That gives teams both a graphical way to inspect the architecture and a command-line path for structured edits. Exact commands and options can change, so use tld --help and the current CLI reference for your installed version.

The repository also documents Markdown notes and Mermaid integration. Mermaid blocks can be synchronized with diagrams and rendered as portable text in Markdown viewers. This can help when a repository’s documentation already uses Markdown, while the diagram editor offers a more interactive way to navigate or edit the architecture. Decide which artifact is the source for a given view and avoid editing two copies independently without a synchronization process.

For automation, the README describes CLI use in CI/CD and source-grounded codebase mapping through tld index. Treat generated maps as a starting point: source indexing can surface candidates and relationships, but a human still needs to validate names, boundaries, and architectural intent. A tool can find code structure; it cannot reliably infer every ownership decision or design rationale.

Keep review practical

A lightweight architecture check can be part of the normal pull request conversation. Ask whether the change crosses a system boundary or adds a dependency that matters beyond the code diff. If yes, update the relevant view. Then check that the new labels are understandable to someone outside the implementation detail and that the diagram still fits its purpose.

Avoid requiring a diagram edit for every code change. Refactoring a private helper may not affect the architecture model. Conversely, a small configuration change that routes traffic through a new external service could deserve an update. The standard should be semantic impact, not the size of the patch.

Start with one maintained view

Pick a diagram that repeatedly comes up in onboarding, incident review, or design discussion. Put its structured source where its owners can find it, agree on how edits are made, and add a short review prompt for changes that affect its boundaries. After a few iterations, assess whether the workflow saves time and whether the model remains accurate.

Architecture as code is valuable when it makes change visible and ownership clear. Pair structured files with a useful visual representation, keep the model deliberately selective, and let the workflow serve the people who need to understand the system.

See the tld repository and CLI documentation for current capabilities and command details.