Skip to content

docs: add mermaid diagrams#469

Open
maxkrivachev-web wants to merge 1 commit intofaif:masterfrom
maxkrivachev-web:master
Open

docs: add mermaid diagrams#469
maxkrivachev-web wants to merge 1 commit intofaif:masterfrom
maxkrivachev-web:master

Conversation

@maxkrivachev-web
Copy link

Add Mermaid overview diagrams to each pattern category in README

Summary

This PR adds three lightweight Mermaid diagrams to README.md — one per pattern category (Creational, Structural, Behavioral) — to give readers a quick visual orientation before they dive into the pattern tables.

Closes / related to: Issue #468


Motivation

The README is an excellent reference, but it is primarily textual. For learners encountering design patterns for the first time, a compact visual overview significantly reduces the cognitive load of figuring out how patterns in the same group relate to each other. This is a well-documented pedagogical benefit: visual representations of abstract relationships improve comprehension and recall.

The Mermaid diagrams on GitHub render natively (no external tooling required), so this is a zero-dependency improvement.


What changed

README.md — three diagram blocks inserted, one before each pattern table:

Section Diagram shows
Creational Factory / Builder / Pool flow: Client → Factory → Product
Structural Facade, Adapter, Proxy, Composite — composition relationships
Behavioral Observer broadcast, Chain of Responsibility, Strategy delegation, Memento save/restore

Each diagram block is:

  • Enclosed in a standard ```mermaid ``` fenced code block
  • Separated from surrounding text by blank lines above and below (prevents GitHub renderer issues)
  • Intentionally minimal — not a full UML diagram, just enough to orient the reader

Design decisions

Why graph LR / graph TD and not class or sequence diagrams?
Flowcharts render cleanly in GitHub's built-in Mermaid renderer and are the most broadly understood diagram type. Class diagrams would require defining attributes/methods per node, which would make the diagrams noisy and harder to scan at a glance.

Why keep diagrams simple?
The detailed implementation already lives in each .py file. The diagrams are meant to answer "what role does this group play?", not "how does every pattern work?".


Screenshots

Diagrams render natively in GitHub — no action needed. You can preview them by pasting the blocks into mermaid.live.


Checklist

  • No changes to .py source files or tests
  • README.md only — no new files added
  • Diagrams tested in mermaid.live for syntax errors
  • Blank lines added above and below each diagram block (GitHub rendering requirement)
  • Diagrams do not duplicate or contradict the existing pattern descriptions

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant