Architecture practice

Diagramming as Code in Git: Make Architecture Changes Reviewable

Architecture shifts whenever code shifts. Keeping diagrams near the code gives a team a practical way to explain that change, discuss its impact, and leave behind a model that can evolve with the system.

Many teams have architecture diagrams, but few have a reliable answer to a simple question: when did this picture last match the system? The problem is often not a lack of drawing skill. It is that the diagram lives in a separate tool, has no clear owner, and is updated on a different schedule from the code it describes.

Diagramming as code changes the workflow. The architecture model becomes a set of files that can live in a repository, be reviewed with ordinary commits, and be changed deliberately. This does not make diagrams accurate by magic. It makes the work of maintaining them visible and repeatable.

Why put architecture in version control?

A diagram is a model: it selects important elements and relationships while leaving implementation detail out. Keeping that model with a service or product repository provides useful context. A pull request can show both the implementation change and the architectural explanation. Reviewers can ask whether a new dependency crosses a boundary, whether a queue changes the flow, or whether a service has acquired a responsibility that belongs elsewhere.

Git also gives the team history. A previous version can be inspected, a branch can contain a proposed future design, and a change can be discussed before it lands. The diagram is no longer a screenshot that has to be manually rediscovered after a decision; it is an editable artifact in the same collaboration loop as code.

Keep the model purposeful. A diagram should answer a question for a specific audience. Start with system boundaries and major relationships, then add detail only where it helps explain a decision or guide work.

Choose a source of truth on purpose

There are several ways to represent architecture as code: a structured model, a text-based diagram language, or diagrams generated from source code. They solve different problems. A source index can reveal symbols and dependencies present in a repository, but it cannot reliably decide what the team considers a subsystem or an external boundary. A hand-authored model expresses that intent, but it needs maintenance.

tl;diagram (the open-source tld project) takes a structured approach. Its elements and connectors form views, and an element can own a child view for a deeper level of detail. The CLI supports local authoring and validation, while the application provides a visual editor. The project documents local YAML workspaces and synchronization with the UI; teams should choose and document which copy is authoritative for their workflow.

A small Git workflow

  1. Model the current system. Begin with the services, people, data stores, and external systems that matter to the change. Avoid mapping every class or package into the top-level view.
  2. Make the implementation change. Use the branch as the place to explore how the proposed code affects the system.
  3. Update the architecture model. Add or adjust only the relevant element, relationship, or nested view. Explain any intentional gap between the model and implementation in the pull request.
  4. Review both sides. Ask whether the code implements the intended relationship and whether the model communicates the new behavior clearly. A diagram diff does not replace code review or a decision record.
  5. Keep the model useful after merge. When later work changes the same boundary, make another focused update instead of waiting for a broad documentation cleanup.

With tld, the command-line workflow can create and inspect architecture objects, validate diagrams, and compare Git revisions. For example, tld git compare HEAD~1 HEAD produces a change impact scene; the documented comparison attempts to match changes to authored diagrams, then falls back to mapped or file elements. That makes it a useful aid for investigating a code change, not proof that an authored architecture model is complete.

What a diagram review should look for

Keep review questions concrete. Did a new connection introduce a dependency from a high-level boundary to an unexpected subsystem? Does the label describe the relationship rather than just repeat the names of its endpoints? Is a new queue a durable integration boundary, or only an implementation detail? Does a nested view add information, or does it repeat the overview?

These questions help separate architectural intent from incidental code structure. They also make review more inclusive: a reviewer does not need to know every file to spot a dependency that deserves discussion. The best diagram change is often small enough to understand in one glance.

Make drift a normal maintenance task

Version control improves the feedback loop, but it cannot force a team to update a model. Put diagram changes in the same definition of done as other documentation when a change alters a boundary or relationship. Use source mapping and comparison tools to find clues, then have an engineer decide what belongs in the conceptual model. Keep generated and authored information distinguishable so readers know which claims are design intent and which are inferred from code.

For a practical starting point, explore the tl;diagram quick start and its guide to Git revision comparison. The source project is available on GitHub under the Apache 2.0 license.