Architecture diagrams: how much detail and how to keep current?

[zyratlo]

While documenting the notebook migration tool we ended up with three kinds of architecture documentation:

• a single high-level architecture diagram
• a set of more detailed per-flow diagrams
• an ER diagram for the schema

Deciding what to publish and what to keep turned into a more general question about how this project documents architecture. Raising it here rather than settling it for one feature.

The question

For a given subsystem, what should exist?

A — One high-level diagram. The whole subsystem in one picture, plus an ER diagram where a schema is involved.

Example of A:

B — High-level plus detail. One overview diagram like A, plus separate detailed diagrams for individual flows.

Example of B (in addition to diagrams in A):

C — One file, multiple layers. High-level by default, with detail revealed by toggling layers.

Considerations raised so far

• External use needs a single diagram. A social post needs one simple picture; a blog can carry something denser.
• Detailed diagrams answer questions an overview cannot: call ordering, which component talks to which, differences in protocol and address between callers that look identical at a high level.
• Any diagram can drift from the code. More diagrams mean more surface to keep current.
• Layers keep everything in one file, but flows do not always share a component set, so the layers may not stack cleanly.
• Source code is increasingly readable by agents, which may change how much detail a diagram needs to carry for a human reader.

What would be useful to settle

1. What is the default for a new subsystem — A, B, or C?
2. If B (detailed diagrams are kept), who updates them and when? Should a PR that changes a flow be expected to update the diagram for that flow?
3. Should the answer differ by audience — social post, blog, repository, internal record?

[zyratlo]

1. From a project management perspective, I think A is enough. I recognize that too many diagrams, especially highly detailed ones, can drift and become inaccurate very quickly and will require the burden to maintain. And since agents can effectively extrapolate finer details by looking at the source code, highly detailed diagrams may not be as needed anymore for human developers. From a personal perspective, I like B more since I like having detailed diagrams, but that is just my personal preference.
2. Regardless of if we choose to have detailed diagrams or not, I think that whoever introduces the feature first creates the diagram. If another developer changes the architecture in a later PR, then they should also update the diagram accordingly.
3. Different audiences would want different diagrams. For github issues and PRs, detailed diagrams and ER diagrams are useful. Compared to social media or blogs, depending on their content and purpose it can be written for developer or non-developer audiences, so it will vary.

[chenlica]

I don't like B for the problems you mentioned. Those sub-diagrams could be included in those discussions, issues, and PRs.

We can unify A and C. If we use draw.io to create such a diagram, we can do C, and still keep one with some of the layers enabled.

[TongyiDai]

I would make A + an editable C-style source the repository default.

• Publish one high-level diagram that can be understood without toggling layers.
• Keep the editable source in the repository; layers may hold optional detail when the component set overlaps cleanly.
• Keep an ER diagram when the subsystem owns a meaningful persistence model.
• Add a persistent per-flow diagram only when sequence/protocol detail is needed repeatedly. Otherwise, put that temporary detail in the issue/PR where the design is being discussed.

That avoids making every subsystem pay the maintenance cost of B while preserving detail where it has durable value.

The update rule should be based on architecture impact, not on whether somebody remembered to inspect the docs. A PR must update the relevant diagram when it changes any of:

1. a component or trust/deployment boundary;
2. a persisted entity or important relationship;
3. an external protocol/interface;
4. a critical cross-component call sequence represented by a retained flow diagram.

Ownership should follow code ownership: the subsystem reviewer is responsible for rejecting a PR with stale architecture docs, while the PR author supplies the update. Store source and exported image together, and add a small CI check that the exported artifact was regenerated when the source changes. CI cannot prove semantic correctness, but it can prevent source/render drift.

For audiences:

• Repository docs: the canonical high-level export, ER diagram if relevant, and links to selected durable flow diagrams.
• Blog: reuse the canonical diagram or a simplified export from the same source.
• Social: a simplified derivative; never the source of truth.
• Issue/PR/internal working record: temporary detailed flows are fine and need not become permanent architecture documentation.

This gives a concrete policy: A is the required human-readable artifact, C is an implementation technique for its source, and B is an exception justified by a recurring reader question—not the default.