GitHub user zyratlo created a discussion: Architecture diagrams: how much detail and how to keep current?
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: <img width="2916" height="890" alt="Screenshot 2026-09-19 161124" src="https://github.com/user-attachments/assets/333547fe-bdb9-473d-9667-a4bb7ab8e866"; /> **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): <img width="2914" height="932" alt="Screenshot 2026-09-19 161300" src="https://github.com/user-attachments/assets/59e1b62a-10c4-436e-8c84-66d92d245c8f"; /> **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? GitHub link: https://github.com/apache/texera/discussions/8609 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
