# architecture-diagrams-library

Architecture diagrams as code — AWS, C4, BPMN and event-driven, versioned and reviewable.

- URL: https://fernando.moretes.com/open-source/architecture-diagrams-library

- Markdown: https://fernando.moretes.com/open-source/architecture-diagrams-library/guide.md?lang=en

- GitHub: https://github.com/fernandofatech/architecture-diagrams-library

- Language: TypeScript

- Topics: 

- Stars: 0

- Forks: 0

- Updated: 2026-05-16T01:43:36Z

---

A 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

- **AWS architectures** rendered with Mermaid and the `diagrams` Python library — ready to copy into technical documentation.
- **C4 Model** across four layers (Context, Container, Component, Code) to communicate architecture at different levels of detail.
- **BPMN** for business process flows — useful when the audience includes non-technical stakeholders.
- **Event-driven topologies** covering EventBridge, SNS/SQS and Kafka with emphasis on fan-out and routing patterns.
- **Sequence and state diagrams** via Mermaid and PlantUML to document runtime behaviour and state machines.
- **Reusable snippets** ready to embed in ADRs and RFCs, with CI (GitHub Actions) and automatic deployment on Vercel.

## How the repository is organized

Versioned diagram sources feed a Next.js frontend that is tested in CI and published automatically on Vercel.

### ✍️ Diagram Sources

- Mermaid .mmd files (storage)
- PlantUML .puml files (storage)
- diagrams (Python) .py files (storage)

### ⚙️ CI Pipeline

- GitHub Actions ci.yml (ci)
- GitHub Actions security.yml (security)
- GitHub Actions frontend.yml (ci)

### 💻 Frontend

- Next.js 16 App Router (frontend)
- Tailwind CSS 4 + React 19 (frontend)

### ☁️ Hosting

- Vercel diagrams.moretes.com (edge)
- Cloudflare DNS (network)

### 👤 Visitor

- Portfolio visitor browser (user)

### Flows

- mermaid -> nextjs: imported
- plantuml -> nextjs: imported
- diagrams -> nextjs: imported
- nextjs -> tailwind: styled by
- ci -> nextjs: lint + build
- security -> nextjs: scan
- frontend_ci -> vercel: deploy
- cloudflare -> vercel: DNS → origin
- visitor -> cloudflare: HTTPS

## 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.git` and enter the created directory.

2. **Install frontend dependencies** — Enter the `frontend` directory and run `npm install`. Node.js 18+ is recommended for compatibility with Next.js 16.

3. **Start the development server** — Run `npm run dev` inside `frontend`. The server starts at `http://localhost:3000` with hot reload.

4. **Consult the operational documentation** — For environment variable configuration, deployment and security procedures, read `OPERATIONS.md` and `SETUP.md` at the repository root.

5. **(Optional) Generate Python diagrams locally** — The `.py` files using the `diagrams` library require Python 3 and Graphviz installed. Run `pip install diagrams` and then `python diagram_name.py` to generate the images.

_Full install and local run sequence_

```bash
# 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.py
```

> **Snippets 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.

## References and links

- [fernandofatech/architecture-diagrams-library — GitHub](https://github.com/fernandofatech/architecture-diagrams-library)
- [Live site — diagrams.moretes.com](https://diagrams.moretes.com)
- [Project architecture docs](https://github.com/fernandofatech/architecture-diagrams-library/blob/main/docs/architecture.md)
- [Mermaid — diagramming and charting tool](https://mermaid.js.org)
- [diagrams — diagram as code for cloud infrastructure (Python)](https://diagrams.mingrammer.com)
- [PlantUML](https://plantuml.com)
- [C4 Model for software architecture](https://c4model.com)
- [Next.js App Router documentation](https://nextjs.org/docs/app)

## Links

- [GitHub repository](https://github.com/fernandofatech/architecture-diagrams-library)