What if your context maps, event flows, and dependency graphs just... generated themselves from Markdown?

What if your context maps, event flows, and dependency graphs just... generated themselves from Markdown?

Your architecture diagrams are lying to you. Not intentionally — they were accurate the day someone drew them. But that was six months ago, and since then three services got renamed, two teams reorganised, and the person who maintained the draw.io file left the company. The model still lives in a desktop app that nobody opens, on a Confluence page nobody finds, in someone's head that is now at a different employer.

The tooling is either too heavy (paid enterprise tools that require a two-day training course) or too manual (Markdown ADRs that are great for decisions but tell you nothing about how 40 systems relate to each other). There is a gap between "I have docs" and "I have a living architecture model."

The idea

What if architecture elements were just Markdown files in Git? And what if the relationships you declared in those files were enough for the diagrams to draw themselves?

No diagram tool. No proprietary format. No model-to-code sync problem — the Markdown is the model. You declare what exists and how things connect. A static site build reads those files, resolves the graph, and generates every view automatically.

That is what Architecture Catalog does.

How it works

Three steps. That is the whole thing.

Step 1: Define your schema (one YAML file)
         ↓
Step 2: Add elements (Markdown files with YAML frontmatter)
         ↓
Step 3: Build (npm run build → static site)

The schema file (registry-mapping.yaml) defines your layers, element types, relationships, and branding. The Markdown files are your elements — one file per system, service, domain, or whatever your vocabulary calls them. The build reads both, resolves the graph, and generates an interactive site.

No server. No database. No runtime dependencies.

What you get

• Dashboard with domain cards — top-level view across all domains with health indicators, element counts, and quick navigation.
• Interactive context maps — search, filter, and focus mode. Click any element to see its first-degree and second-degree relationships. The graph is built from the relationship declarations in your Markdown files.
• Animated event flow diagrams — shows which systems publish events, which systems consume them, and how data flows across domain boundaries. Designed for teams that have moved to event-driven architectures and lost track of who owns what.
• PlantUML, BPMN, and draw.io viewer — if you have existing diagrams, they render inside the catalog next to the registry elements. You are not forced to throw away what you have.
• Element detail pages — every element gets its own page: description, layer, domain, all declared relationships, and links to related diagrams.
• Dark mode by default — because architects apparently live at night.
• White-label and deploy anywhere — it is a static site. Firebase, S3, GitHub Pages, Netlify — your choice.

See it live

The live demo is at architecture-catalog.web.app. It has 6 domains, 180+ entities, and is fully interactive — context maps, event flows, element drill-down, the lot.

The documentation site is at docs-architecture-catalog.web.app if you want to understand the schema before you start.

Open either one before reading the rest of this post. The 30 seconds you spend clicking around will make the next part more concrete.

The schema-driven part

This is the piece that makes it maintainable at scale.

Everything flows from a single YAML file. Here is the minimal version — a site configuration and one element type:

site:
  name: "My Architecture Catalog"
  description: "Architecture model for Acme Corp"
  accent_color: "#4A90D9"

layers:
  - id: application
    name: Application
    color: "#1E3A5F"
    types:
      - id: service
        name: Service
        icon: "⬡"
        graph_rank: 2
        description: "A deployable service or microservice"

That is it. With this in place, you create Markdown files in the registry-v2/application/services/ folder and they automatically appear in the dashboard, get their own detail pages, and participate in context maps.

Adding a new element type means adding one entry to this YAML file and creating a _template.md. Zero code changes. The UI derives everything — page structure, graph layout, relationship rendering, sidebar navigation — from the schema.

It is also vocabulary-agnostic. You can use ArchiMate, TOGAF, C4, or whatever your organisation invented. The catalog does not care what you call your elements. Rename every type and layer in the YAML and the site still builds and renders correctly.

Validated at scale

I have been running a version of this internally across 30 domains with over 6,000 registered elements. The build still takes under 15 seconds. The output is pure static HTML — no server, no database, no runtime dependencies.

The architecture team stopped manually maintaining diagrams. Context maps generate from what teams declare in their Markdown files. New elements show up in the catalog as soon as the PR merges.

That is the real test — not whether it works on a demo dataset, but whether it holds at enterprise scale without becoming a maintenance burden.

Why Markdown and Git

This is not a new argument, but it is worth making clearly:

• Git history is your architecture changelog. Every structural change is a commit. You can diff the architecture between quarters.
• PRs are architecture reviews. When a team adds a new service or declares a new dependency, it goes through the same review process as code. No separate approval workflow.
• AI can read it without instruction. Plain Markdown with structured frontmatter is natively parseable by any LLM. Ask your AI assistant about a domain — it can read the actual model, not a summary someone wrote last year.
• No vendor lock-in. Markdown files in a Git repo will be readable in 20 years. The same cannot be said for every architecture tool on the market today.

Try it

git clone https://github.com/ea-toolkit/architecture-catalog.git
cd architecture-catalog/catalog-ui
npm install
npm run dev

Open localhost:4321 and you will see the dashboard. The demo data is a fictional B2B SaaS CRM — 3 domains, 71 elements — built to show off the features without being distracting.

The README has instructions for pointing it at your own registry. The schema documentation on the docs site walks through every field in registry-mapping.yaml.

Open source, MIT licensed

The project is open source under the MIT license. Contributions are welcome — issues, PRs, feature requests, and feedback on the schema design are all useful.

I am presenting this at DDD Europe 2026, where the talk covers the broader problem: how do you make architecture observable at enterprise scale without creating a second job for the architecture team? The catalog is part of that answer.

If you have opinions on architecture tooling — what is broken, what you have tried, what you wish existed — I would genuinely like to hear them. How does your team track architecture decisions and element relationships today?

One Takeaway

Architecture tooling fails because it separates the model from the thing being modelled. Plain Markdown in Git closes that gap — the model lives where the work lives, changes when the work changes, and reads the same way code does.

The diagrams drawing themselves is a side effect. That is the point.