Mermaider: Code-Based Architecture Diagrams for AI Engineering

AI-assisted engineering makes it possible to change a software repository faster than I can keep its architecture in my head.

A new worker appears. A deployment gains another step. A database relationship changes. A registration flow starts sending an event to a queue. Each change may be reasonable, reviewed and tested. Together, they create a system whose shape becomes harder to explain.

I can ask my coding agent how everything works. Often, the explanation is useful. Ask again in a different session, with a different selection of files, and I may get a slightly different story. One answer emphasizes the API. Another treats a worker as the main entry point. A third overlooks the failure path that matters most.

I want an architectural record I can inspect, compare and challenge against the implementation. That is why I built Mermaider: an open-source tool that combines a coding-agent skill, executable source analysis and native hooks to maintain Mermaid diagrams from a repository.

It produces browsable HTML for people, plus Mermaid and Markdown sources for review and agent context. Its core promise is precise: the same sources, saved models, configuration and tool version produce the same generated files.

A better development workflow still needs a map

I use agent frameworks because they give the work structure. Superpowers provides composable skills for planning, implementation and verification. Oh My Codex adds reusable roles, task workflows and coordination around Codex.

Those capabilities help an agent build software deliberately. Maintaining a current map of the implemented system is another responsibility. A plan explains what we intended to build. A diagram tied to current source explains the selected parts we have actually implemented.

I need both. A deployment pipeline is easier to discuss when I can see the jobs and dependencies. A signup flow is easier to review when I can follow the interaction between the handler, database and external services. A data model is easier to understand when related tables are visible together.

The diagram should survive the conversation that created it. The next agent, a colleague or my future self should be able to read the same artifact and find the sources behind its claims.

What “deterministic architecture” can honestly mean

Architecture diagrams contain choices. Two correct diagrams can show the same system at different levels. A product overview can group several workers into one service. A technical view can show them individually.

The implementation also does not establish every property of the running system. A configuration declares a resource. A runtime trace can show whether a request reached it. A design document describes an intended change. These are different kinds of evidence.

So I would be overstating the product if I said Mermaider automatically discovers the complete truth about any codebase.

The useful guarantee starts once the inputs and scope are explicit. Extract the supported facts with code. Save the relationships that require interpretation in versioned models. Attach evidence. Generate the selected views using stable rules.

An LLM still helps interpret a business process. Its reasoning is not deterministic. Saving and checking that interpretation makes it reviewable and gives future runs a stable starting point.

This separation matters whenever someone asks, “Did the architecture change?” I want to compare source and model changes. A differently phrased explanation should not masquerade as a system change.

Three layers: facts, meaning and presentation

Mermaider separates work into three layers.

Facts come from executable extraction. The current adapters cover declared Wrangler resources, GitHub Actions jobs and their dependencies, package and Cargo manifests, TypeScript structures and imports, and supported declarative SQL schema and migration operations.

These are bounded capabilities. An import establishes a dependency; it does not prove a runtime call. A status enum lists values; it does not prove which transitions are allowed. Unsupported or dynamic constructs need visible diagnostics.

Meaning lives in source-backed models. A registration sequence or provisioning flow may span files and systems. The agent inspects the implementation and records the relevant nodes, relationships or ordered steps. Each claim carries source evidence. The model also distinguishes implemented, planned and observed behavior.

Presentation comes from a fixed renderer. Stable identities and ordering make output reproducible. Mermaid and Markdown remain reviewable files. The HTML viewer makes the same selected diagrams practical to browse.

A fresh file and a correct explanation are separate assertions. A checksum can establish which source a model references. It cannot establish that the model understood that source correctly.

Start with the diagrams you actually need

I do not want an agent to generate every possible diagram on first contact. A repository can contain dozens of candidate topics, and a large diagram can become as difficult to understand as the original code.

The skill begins with discovery. It inspects the repository, reads its documentation conventions and proposes a concrete catalogue. The user then selects the topics, audience, detail and destination.

A useful starting selection might include an infrastructure overview, a CI/CD pipeline and the account data model. Later, I can add a registration sequence or a deployment state diagram when that question becomes important.

The choice is saved in .mermaider/config.json. Future updates maintain that scope. Newly discovered topics remain suggestions until selected.

This is a product decision as much as a technical one. A diagram earns its place by helping someone answer a question: What does this service depend on? What happens before production publication? Which tables belong to this domain? Where can this operation fail?

A coherent subset is often the right answer. The viewer can use short navigation labels and focused projections, with coverage limits stated explicitly.

Why a deployment diagram needs more than a happy path

Consider a hypothetical deployment process. The system accepts a request, builds an application, publishes an artifact and checks health.

That sequence makes a tidy diagram. It also leaves important questions unanswered. What happens if the build fails? Can publication finish while the health check times out? What makes a retry safe? Does the product mark the deployment complete before all required steps succeed?

A useful process model follows the code that establishes those behaviors. It looks at conditions, awaited operations, state changes and error handling. Where the evidence supports only part of the process, the diagram should say so.

Mermaider can extract the dependency structure declared in a GitHub Actions workflow. A product deployment sequence spanning application code and external systems may need a reviewed semantic model as well. Calling both “the deployment pipeline” without stating the perspective would hide the distinction.

The same applies to database diagrams. A migration that created a table months ago is only one part of the history. Later supported operations must be considered, and operations the extractor cannot establish should remain visible as gaps.

I would rather have a smaller diagram with defensible relationships than a comprehensive-looking picture filled with assumptions.

HTML for people, source text for agents

Mermaid describes diagrams using text and renders them into visual form. That makes it a useful foundation for documentation that lives beside code.

I want the deliverable to work for two audiences. People need a readable view. Agents need the underlying relationships, explanation and evidence in text.

Mermaider therefore always saves a browsable HTML collection, alongside Mermaid and Markdown files. Curated models and configuration use JSON. There is no dedicated XML export in the current version.

SVG remains useful inside the viewer. It is itself an XML format, so the issue is not that an agent can never read it. The issue is that layout coordinates and drawing instructions are a poor primary record of a process. I want the source definitions and claims preserved directly.

The offline HTML viewer shows one diagram at a time. Readers can switch topics, pan, zoom and fit the view. Sources and coverage notes are available without filling the main reading area with metadata. The layout follows the Sebmer brand.

Saving the source also keeps review practical. A pull request can show that a relationship was added or a sequence changed, without requiring the reviewer to compare two screenshots.

Hooks connect maintenance to the work

Documentation is easier to neglect when updating it requires remembering a separate task.

Mermaider uses native hooks to notice when selected documentation needs attention. Codex and Claude Code provide lifecycle events that can return context to the running agent. Their exact setup and trust rules belong to the clients. Codex hooks, Claude Code hooks.

The Mermaider adapter checks repository state and asks the current agent to run the skill. The agent reviews the affected sources, updates the relevant models or diagrams, generates HTML and runs the checks.

The hook does not create a second agent or decide to commit. Repository instructions and the current task determine how documentation changes should be committed. A completion hook allows at most one extra maintenance pass per user turn, which helps prevent endless follow-up loops.

This works during a supported, running agent session with trusted hooks. If a commit happens while the agent is closed, it is noticed at the next eligible session or event. Mermaider is not a background watcher that continuously updates a repository on its own.

Codex and Claude adapters have executable contract tests. The installation guide records a live Claude Code smoke test and distinguishes it from protocol testing. Cursor and Gemini definitions remain experimental preparations.

A practical first run

The current release uses a built checkout and requires Node.js 22.13 or later and Git. The installation guide covers skills and hooks for the supported clients.

git clone https://github.com/sebmer-com/mermaider.git
cd mermaider
npm ci
npm run build
node dist/cli.js discover --repo ../my-app

Here, my-app stands for a separate target repository beside the Mermaider checkout. Discovery helps establish which diagrams are available before anything is selected.

After installing the skill, I can ask:

Use Mermaider to inspect this repository. Show me useful architecture, pipeline, data and process diagrams. Help me choose which ones to maintain, then save the collection as HTML in the appropriate docs folder.

For a direct CLI workflow, I can select the currently discovered architecture, pipeline and data candidates:

node dist/cli.js init --repo ../my-app --families architecture,pipeline,data
node dist/cli.js update --repo ../my-app
node dist/cli.js check --repo ../my-app

Initialization saves the current selection. It does not subscribe to every future candidate in those families. Semantic processes still need inspected evidence and models.

The output location follows repository rules and saved choices. Existing architecture docs take priority in the default detection. A Superpowers project otherwise uses docs/superpowers/mermaider; a plain or Oh My Codex project defaults to docs/mermaider. These are Mermaider conventions, and an existing repository convention can override them.

I open the resulting index.html, inspect the dense views and review the generated diff. Syntax validation alone cannot establish that a diagram is readable.

What the first projects taught me

Oh My Host already had Mermaid diagrams and a documentation checking mechanism. That provided a useful starting point: the requirement was to maintain an understandable record as the code evolved.

I also applied Mermaider locally to PGCF, the Cloudflare PostgreSQL project. Infrastructure, deployment pipelines and data models create different reading needs. They benefit from separate views and short navigation, rather than one large graph.

These projects informed the first implementation and viewer. They do not demonstrate complete analysis of every repository or establish every possible agent installation. Public examples use synthetic repositories so the tool can be inspected without publishing private application details.

The current approach is deliberately extensible. New extractors should add supported facts with clear evidence. New models should preserve the distinction between source-backed claims and interpretation. New agent adapters should prove the real handoff as well as the event format.

The architectural record belongs in the repository

Mermaider is open source under Apache-2.0. It works independently and can fit into a Superpowers or Oh My Codex workflow.

I built it because I want the understanding of a system to accumulate as I build. The code changes, the selected models are reviewed, and the diagrams change with them. A new conversation can start from that record and challenge it.

AI-assisted engineering gives me more capacity to implement ideas. Keeping the resulting system understandable requires an explicit record of what connects to what, what happens in which order, and which evidence supports the explanation.

That is the job I want Mermaider to do.

Explore Mermaider on GitHub, inspect its design and limitations, or start with the installation guide.