Architecture diagrams often go stale for a familiar reason: the system changes in the repository, while the diagram lives somewhere else with a separate editing process. The gap is not solved simply by putting a file next to source code. Teams need conventions for scope, ownership, review, and how generated evidence relates to authored intent.
“Close to code” means close enough that engineers naturally encounter the model while changing the system, can propose edits in a familiar review flow, and can trace a diagram element back to its evidence where that connection is available.
Put diagrams where maintainers look
Choose a stable home in version control. A repository-level .tld/ directory can hold the workspace configuration and authored element and connector definitions used by the open-source tld tooling. Committing that workspace lets diagram changes travel with code and makes the model reviewable through the same history.
Keep the structure predictable. Name views for the question they answer, such as “Order fulfillment” or “Identity boundary,” rather than for a meeting date. Store short descriptions of each view’s scope and audience. Avoid putting secrets, machine-specific paths, or local service settings into shared files; the project documentation distinguishes workspace configuration from global configuration for local preferences and credentials.
For multi-repository systems, make the boundaries explicit. The workspace guide describes repository entries and local roots for connecting diagrams to source. This can help a team keep a system view while individual services evolve independently, but cross-repository diagrams still need an owner who understands the integration model.
Make model changes reviewable
When a pull request adds or changes a service, ask whether the architecture model should change too. Include a small diagram update in the same pull request when it records a durable boundary or relationship. The author can explain the intent beside the code, and reviewers can discuss both implementation and design together.
It is reasonable for implementation changes not to alter a high-level diagram. Record the reason in the review when a change crosses a boundary or introduces a dependency that could affect architectural understanding. Conversely, avoid editing the overview for every internal refactor; too much churn makes maintainers less likely to trust and review it.
Use source indexing as supporting evidence
The tld index workflow can index a repository into a code graph and snapshots. Documentation describes --map as a way to group that graph into architectural components, and --watch as a way to follow local repository changes. Those features can help engineers explore source relationships and produce a starting point for a map.
Generated structure is not the same as a complete architecture. Indexing depends on available parsers, external indexers or language servers, configuration, and repository contents. A static source edge may be an implementation dependency without being a network connection; runtime behavior, deployment boundaries, team ownership, business capability, and intent may require other evidence or a human explanation. The indexing guide itself notes active development and possible rough edges or long runtimes on large repositories.
Use indexing to ask better questions: Which code appears to depend on this package? What changed between snapshots? Where should I look in the source? Then validate the result against deployment configuration, runtime behavior, and the team’s intended boundaries before presenting it as an architectural claim.
Automate the reminder, not the judgment
Teams can add lightweight process around the model. A pull request template might ask whether a boundary or integration changed. A CI job can validate that configuration parses, or produce a comparison artifact when a repository revision changes. The tld git compare command is documented for comparing two revisions and surfacing a change-oriented scene. Automation can help make changes visible consistently; it cannot decide whether the new design is sound or whether an authored view tells the right story.
Keep checks proportionate. If a generated view is too large, noisy, or incomplete, make it optional context rather than a required approval gate. If a diagram is a deliberate contract—for example, a security boundary—then assign an accountable reviewer and explain what change requires an update.
Give each diagram a maintenance path
- Set an owner. Name a team or role responsible for deciding what belongs in the view and when it needs revision.
- Set a scope. State what the diagram covers, what it omits, and when it was last checked against evidence.
- Link evidence. Where practical, connect elements to repositories, files, or symbols to help readers navigate from model to implementation.
- Review changes at natural points. Include architecture updates in relevant code reviews, migrations, and integration proposals.
- Retire misleading views. An archived or removed diagram is better than a polished picture that teams know is wrong.
The workspace documentation explains project files and repository connections. For indexing behavior and limitations, see the indexing guide and the open-source tld repository.