architecture-diagrams-library

The problem this repository solves is not drawing — it's keeping the drawing true after the architecture changes. A diagram that exists only as a PNG exported from a visual tool loses its source on the first laptop swap, has no diff and nobody reviews it. Six months later the architecture document shows three SQS queues where five now exist and a Lambda that was retired.

I applied to diagrams the same discipline applied to infrastructure: text source, in a repository, behind a pull request. A Mermaid .mmd or a PlantUML .puml fits in a code review, shows line by line what changed and can be rendered by the documentation pipeline without a human in the loop. When someone swaps EventBridge for SNS/SQS in an ADR, the diagram change lands in the same PR as the decision change.

What the repository is: a curated catalog of those sources, organized by type (AWS reference, C4 layers, BPMN process, event-driven topology, sequence, state), plus a Next.js 16 frontend that renders and publishes all of it. What it is not: a new diagramming tool. The renderers are the usual ones — Mermaid, PlantUML and the Python diagrams library — the value is in the curation and the review flow.

There are two halves with separate responsibilities. The sources: text files in three diagram languages. Mermaid covers most of it — C4 via the C4Context/C4Container syntax, sequence, state and flowcharts for event-driven — because it renders on GitHub itself and in almost every documentation generator without a plugin. PlantUML steps in where Mermaid runs short, mainly long sequences with groups and notes. The Python diagrams library is reserved for AWS architectures where the official service icon makes the picture readable to non-engineers.

The frontend: a Next.js 16 application (App Router, React 19, TypeScript 5, Tailwind CSS 4) under frontend/ that reads the sources, renders and publishes the catalog. It runs on Vercel; DNS for diagrams.moretes.com is managed on Cloudflare.

The pipeline: four GitHub Actions workflows — CI, Frontend, Vercel and Security. CI validates sources on the PR; Security scans dependencies; Frontend builds the site; the deploy goes to Vercel. The detail that matters: validation happens before merge, so a .mmd with broken syntax never reaches main — it breaks in the PR, where someone is looking. That is the difference between a catalog that stays maintained and a folder of files nobody trusts.

The operational documents live in the repository itself: docs/architecture.md for the system design, SETUP.md for the environment, OPERATIONS.md for day-to-day and CONTRIBUTING.md for anyone who wants to add a diagram.

The most common case is not opening the site — it's opening an ADR. When I write a decision about, say, orchestration with Step Functions versus choreography with EventBridge, each option gets a sequence or topology diagram pasted from the catalog and adjusted with the domain's real names. The reviewer sees option A and option B side by side, in the same Markdown, in the same style. Without that, every architect draws in whatever tool is at hand and the architecture board spends the first ten minutes decoding legends.

C4 in layers, not all at once: the mistake I see most is a single diagram trying to be Context and Component at the same time. The catalog splits the four layers into separate files precisely so Context fits on one screen and Component can be detailed without polluting what the business stakeholder needs to see.

BPMN next to the technical view: when the business process and the event topology live in the same repository, divergence between them becomes a diff. An approval step that exists in the BPMN with no matching event in the topology is a design bug you catch in review — before it becomes a production bug at 2 AM.

The cost this repository reduces is not drawing the first diagram — it's keeping fifty diagrams true over years, with teams that change.