Skip to content

docs(diagrams): add template and decompose CRITICAL diagrams [ADR-040]#2395

Closed
SatoryKono wants to merge 1 commit intomainfrom
codex/create-template-for-architecture-diagrams-3nl3wr
Closed

docs(diagrams): add template and decompose CRITICAL diagrams [ADR-040]#2395
SatoryKono wants to merge 1 commit intomainfrom
codex/create-template-for-architecture-diagrams-3nl3wr

Conversation

@SatoryKono
Copy link
Copy Markdown
Owner

Motivation

  • Reduce layout overload and Dagre failures by decomposing oversized architecture diagrams into focused, renderable Views and standardize metadata for CI and onboarding.
  • Provide a single canonical template and a formal superseded marker so historical originals are retained but excluded from automated renders.
  • Ensure consistent theming and subgraph styling by pointing authors to the external theme and forbidding inline %%{init:} blocks for new files.

Description

  • Added docs/02-architecture/mmd-diagrams/_template.mmd with standardized metadata fields (@status, @view, @parent, @nodes) and theming guidance (no %%{init:} for new files).
  • Updated all architecture/*.mmd files to include normalized header metadata (%% @status active and %% @nodes <n>) and recomputed node counts for accuracy.
  • Decomposed CRITICAL diagrams into focused Views by creating new files (examples: architecture/01a-01c-*, architecture/13a-13d-*, foundation/01a-01c-*, foundation/50a-50c-*) and added %% @view/%% @parent metadata to each decomposed file.
  • Marked original heavy diagrams with a standardized SUPERSEDED header (%% @status superseded + %% @superseded-by ...) and updated docs/02-architecture/mmd-diagrams/README.md to link ADR-040, list decomposed views, annotate superseded files, and provide a recommended onboarding order.
  • Updated docs/02-architecture/mmd-diagrams/render.sh to skip files containing @status superseded so CI rendering excludes historical originals.

Testing

  • Ran node-count verification (grep-based heuristic) across decomposed files and confirmed @nodes matches the computed unique node counts and all decomposed views are ≤20 nodes (check succeeded).
  • Performed shell syntax check (bash -n docs/02-architecture/mmd-diagrams/render.sh) and Python compile check for the lint script (python -m compileall scripts/lint_diagrams.py), both of which succeeded.
  • Executed python scripts/lint_diagrams.py which ran (reported "All diagrams pass policy checks" in this environment), noting it reported zero files processed due to environment scope but the script exercised the updated code path.
  • Attempted a render smoke-test with mmdc but it failed because the mmdc binary is not installed in the execution environment; pre-commit hooks run in this environment also surfaced unrelated repository-wide checks (auto-formatting, missing pip-audit, and root-level VCR cassette placement) which are external to these diagram edits.

Codex Task

@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@SatoryKono
Copy link
Copy Markdown
Owner Author

Superseded by #2422.

@SatoryKono SatoryKono closed this Mar 2, 2026
@SatoryKono SatoryKono deleted the codex/create-template-for-architecture-diagrams-3nl3wr branch March 3, 2026 09:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant