What to Automate in Architecture Documentation—and What Needs an Architect

Architecture documentation has two kinds of work that are easy to confuse. Some tasks are repeatable: identify source files, find code relationships, compare revisions, check configuration, and publish a report. Other tasks are interpretive: explain the system’s purpose, choose a useful abstraction, decide which dependency is acceptable, and determine whether a team’s ownership boundary is coherent.

Automating the first category can save time and improve consistency. Expecting it to solve the second can create diagrams that look authoritative while missing the decisions readers need.

Automate evidence collection

A tool can scan repository structure and build a source graph from code it understands. The open-source tld project documents tld index for indexing repositories and creating snapshots. Its workflow can discover files, parse syntax, use available external indexers or language servers to resolve symbols and references, and optionally group a graph into architectural components with --map.

This is useful for navigation. If a reviewer needs to know which source files or symbols changed, or where a dependency may originate, an indexed view can provide leads more quickly than reading a large repository from scratch. It can also help create an initial map that an engineer then edits into a view with an explicit purpose.

Automate comparison when the question is bounded. The documented tld git compare command compares two Git revisions and surfaces changes in a scene, with matching to authored diagrams where possible and fallback to mapped or file elements. A simple invocation is:

tld git compare main feature-branch

That can supply context for a pull request, a release review, or a focused investigation into how a repository changed. The output is evidence about the compared revisions and the indexing process. It is not a complete description of runtime behavior or a recommendation about whether the change is desirable.

Automate routine checks and reminders

Several low-risk tasks are good candidates for automation: verify that workspace files parse, check that important diagrams have an owner or description, produce a change report, and remind authors to consider whether an architecture view should change. A team may also choose to run repository indexing on a schedule or as part of a local watch workflow. The tld index --watch documentation describes incremental local updates for supported workflows, with language-specific behavior and configuration to consider.

Use the result to reduce discovery cost. A report can point reviewers toward changed files, new relationships, indexing warnings, or views that may need attention. If the result is too noisy, adjust scope or budgets rather than making every diagram a blocking gate. Automated checks are strongest when they have a clear input, repeatable output, and a failure mode that a maintainer can understand.

Keep interpretation with the people who know the system

Source structure is not architecture by itself. An import does not necessarily mean a network dependency. A package is not automatically a deployable service. A code path can exist without being used in production, while configuration or dynamic behavior can create important relationships that static analysis does not capture. Team responsibilities, data ownership, security boundaries, operational failure modes, and product capabilities require additional evidence.

An architect or domain expert should decide what level of detail answers the reader’s question, which system boundaries are meaningful, whether a proposed coupling is acceptable, and what context a diagram needs to be understood. They should also validate generated groupings against deployment and runtime evidence when those distinctions matter.

“Human review” should be specific. Ask a knowledgeable reviewer to confirm a particular boundary or assumption, not to certify a massive autogenerated graph. A focused view of a request path, ownership boundary, or integration usually supports a more productive discussion than a map of every node the tooling found.

Design a human-in-the-loop workflow

1. State the decision. Write the architectural question before generating a view.
2. Collect relevant evidence. Use source indexing, Git history, deployment configuration, or operational data according to the question.
3. Inspect provenance and gaps. Identify what is authored, mapped, inferred, excluded, or unavailable. Read indexing warnings instead of assuming a clean output means complete coverage.
4. Ask an accountable reviewer. Have the relevant service or domain owner interpret the differences and confirm constraints.
5. Record the outcome. Update the diagram, document the intentional exception, or create an engineering action with an owner.

Make automation’s limits visible

Indexing depends on repository shape, supported languages, and installed tooling. The project’s documentation cautions that the pipeline is under active development and that large codebases may be rough or slow to process. Missing indexers can be skipped, so inspect diagnostics and scope before relying on an output. Generated structure should be labeled and reviewed in a way that readers can distinguish it from an intentional authored model.

Use automation to keep evidence close to engineering activity and make changes easier to notice. Use architecture judgment to turn that evidence into a useful explanation, a decision, or a boundary the organization is prepared to maintain. See the indexing documentation, revision comparison guide, and the tld source repository for current behavior and options.