Architecture documentation that leads back to source files

Start with a change someone needs to make

An architecture page is useful when it helps a maintainer predict the consequences of a change. For the parcel demo, the question is simple: where would you change the fee for a heavier package? The answer should connect quote to the functions in pricing and explain what the calculation represents.

For a larger repository, choose one request path or scheduled job. Document its inputs, the module boundary it crosses, and the result it produces. Avoid claiming that a code graph captures runtime infrastructure or business ownership automatically.

Use two layers of explanation

RepoDocs scaffold writes deterministic architecture and reference artifacts from the repository index. In the checked demo, the reference page lists four source entities, but the graph has no edges and the overview contains a generic RepoDocs workflow. Inspect generated output before adopting it as architecture documentation.

Add a short editorial layer for deployment boundaries, external systems, failure handling, and the reasons behind important decisions. A function signature cannot explain a commercial constraint or a migration strategy. Name the team member responsible for reviewing those statements.

Make a small, reviewable architecture change

In the demo, changing weight_fee is a useful review exercise. Read its callers in the source and update the explanation of the fee rule. The recorded scaffold run returned zero dependency edges for this small Rust fixture, so its graph cannot answer the caller question. This is a concrete reason to compare generated artifacts with implementation.

1. Choose one behavior and find its entry point.
2. Locate the functions and modules it depends on.
3. Record the current behavior and its source location.
4. Describe the reason for the boundary separately from generated output.
5. Have another developer follow the page to make a small change.

Keep architecture claims bounded

Repository analysis can miss dynamic wiring, generated code, reflection, and services configured elsewhere. Review these boundaries explicitly instead of treating an empty graph as proof that no dependency exists.

RepoDocs currently provides a CLI workflow. Subscribe for updates to follow new releases and improvements to repository analysis; the landing page does not offer a hosted architecture dashboard.