Skip to content

docs(architecture): make diagrams explain useful relationships #937

Closed

Description

@Juliusolsson05

The architecture reference added by #897 contains 42 diagrams, but several repeat adjacent tables or list classes without explaining a useful relationship. Unlabeled arrows, inconsistent color meaning, crowded layouts and very small inline labels make some views harder to use than the prose.

Improve the existing reference so a new maintainer can use each diagram to answer a concrete architecture question.

Acceptance criteria:

  • Audit every diagram: retain, redesign, combine or replace with existing prose/tables, recording the reason.
  • Keep a substantial opening application map with clear grouping and a visible reading order.
  • Give retained views an explicit question, clear scope and labeled relationships; preserve source-backed behavior and important failure cases.
  • Use a restrained palette with consistent meaning, text/shape cues beyond color and checked contrast.
  • Validate readability at ordinary Markdown width, standalone SVG rendering, editable-source agreement and links.
  • Document concise maintenance principles with primary-source design references.

Research basis: C4 diagram/notation guidance, Nielsen Norman Group visual-design principles, and W3C color/contrast guidance.

This is documentation and rendering-tool work; application behavior remains outside scope. Related: #100 and #897.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions