architecture-diagrams-library
Architecture diagrams as code — AWS, C4, BPMN and event-driven, versioned and reviewable.
git clone https://github.com/fernandofatech/architecture-diagrams-library.gitA curated catalog of architecture diagrams written as code — AWS, C4, BPMN, event-driven, sequence and state — served by a Next.js application and kept under version control so every change is reviewable in a pull request.
Why diagrams as code
A diagram that exists only as a screenshot ages fast. When infrastructure changes, the image does not change with it — and nobody knows when it became stale. Treating diagrams as code solves that: every Mermaid, PlantUML or diagrams (Python) file lives in the repository, runs through CI, shows up in diffs, and can be embedded in ADRs, RFCs and documentation pipelines.
This discipline is not new in the infrastructure world — Terraform and CloudFormation already made infrastructure declarative and auditable. The same reasoning applies to the visual representations of that infrastructure. If an engineer changes an event-driven topology and does not update the corresponding diagram, the PR is incomplete. With versioned sources, diagram review becomes a natural part of the code review process.
The repository covers the layers that appear most frequently in my day-to-day work: AWS reference architectures, C4 models across four levels, BPMN process flows, messaging topologies (EventBridge, SNS/SQS, Kafka), and sequence and state diagrams for documenting runtime behaviour.
What is included
diagrams Python library — ready to copy into technical documentation.How the repository is organized
Versioned diagram sources feed a Next.js frontend that is tested in CI and published automatically on Vercel.
- Mermaid · .mmd files
- PlantUML · .puml files
- diagrams (Python) · .py files
- GitHub Actions · ci.yml
- GitHub Actions · security.yml
- GitHub Actions · frontend.yml
- Next.js 16 · App Router
- Tailwind CSS 4 · + React 19
- Vercel · diagrams.moretes.com
- Cloudflare · DNS
- Portfolio visitor · browser
Technical stack and design decisions
The frontend is built with Next.js 16 (App Router), React 19 and TypeScript 5. Tailwind CSS 4 handles styling without adding heavy component dependencies. The choice of Next.js is pragmatic: static rendering for diagram pages means Vercel serves pre-generated HTML, with no meaningful cold starts for portfolio visitors.
Diagram sources use three complementary tools. Mermaid is the default choice for sequence diagrams, state machines and simple flows — the syntax is readable directly on GitHub and requires no extra tooling to render in Markdown. PlantUML is used for C4 diagrams and cases where Mermaid's expressiveness falls short. The diagrams Python library is used for AWS architectures where official icons matter to the audience.
Three GitHub Actions workflows cover the lifecycle: ci.yml runs lint and build on every push, frontend.yml triggers a Vercel deployment on merges to the main branch, and security.yml runs security scans asynchronously. DNS is managed by Cloudflare, which acts as a proxy and protection layer in front of Vercel. All operational configuration is documented in OPERATIONS.md and SETUP.md.
Running locally
- 1
Clone the repository
Run
git clone https://github.com/fernandofatech/architecture-diagrams-library.gitand enter the created directory. - 2
Install frontend dependencies
Enter the
frontenddirectory and runnpm install. Node.js 18+ is recommended for compatibility with Next.js 16. - 3
Start the development server
Run
npm run devinsidefrontend. The server starts athttp://localhost:3000with hot reload. - 4
Consult the operational documentation
For environment variable configuration, deployment and security procedures, read
OPERATIONS.mdandSETUP.mdat the repository root. - 5
(Optional) Generate Python diagrams locally
The
.pyfiles using thediagramslibrary require Python 3 and Graphviz installed. Runpip install diagramsand thenpython diagram_name.pyto generate the images.
# Clone
git clone https://github.com/fernandofatech/architecture-diagrams-library.git
cd architecture-diagrams-library
# Frontend
cd frontend
npm install
npm run dev
# → http://localhost:3000
# (Optional) Python diagrams — requires Graphviz
pip install diagrams
python path/to/diagram.pySnippets ready for ADRs and RFCs
One practical use of this repository is as a reference library: instead of drawing an SNS/SQS fan-out diagram from scratch in every new project, I copy the corresponding snippet, adjust resource names and embed it directly in the ADR. This reduces documentation time and ensures visual consistency across projects.
Frequently asked questions
Can I use the diagrams in my own projects?
Yes. The license is MIT. Attribution is appreciated but not required.
Do I need Python to use the repository?
Not for the frontend. Python and Graphviz are only needed if you want to locally regenerate the .py diagrams that use the diagrams library. Mermaid and PlantUML diagrams work without Python.
How do I contribute a new diagram?
See CONTRIBUTING.md at the repository root. The standard flow is fork → branch → PR with the versioned source file and, if applicable, the generated image.
Why Next.js for a diagram catalog?
The App Router with static generation delivers pre-rendered pages with no server cost, which is appropriate for a public portfolio. It also allows adding interactivity (filters, search) without changing the stack.
Who this repository is for
This repository is useful in two distinct contexts. First, as a technical portfolio: visitors evaluating my work can see not just the final diagrams, but the versioned sources, CI workflows and stack decisions — which says more about engineering practice than a static image. Second, as a reusable reference library: architects and engineers working with AWS, event-driven or C4 can use the snippets directly in their own ADRs and documentation, adapting names and topologies as needed. It is not a framework or a diagram generation tool — it is a curated collection with a publishing infrastructure. If you are looking for an interactive diagramming tool, Mermaid Live or draw.io are more appropriate. If you are looking for concrete, versioned examples of architecture patterns that can go directly into technical documentation, this repository covers that space.