Over the years, I've spoken to a lot of engineering teams about documenting their software architecture. Different industries, different sizes, different tech stacks. But when I ask what their biggest problem is, the answer is nearly always the same: keeping it up to date.

Nobody I speak to thinks documentation doesn't matter. Most teams are already documenting their architecture, their specs and their APIs. What they struggle with is keeping it all up to date as things change. The information is scattered across the organization: diagrams in one tool, docs in a wiki, specifications in repositories, each in a different place for a different audience. It's no wonder it's hard to keep up to date.

The code moves on, and the docs don't. Keeping them current starts to feel like a job in itself. If there's one problem everyone shares with documentation, it's that it goes out of date.

In this post, I want to dig into that drift: why it happens, what it costs, and how you can bring your own models to EventCatalog to keep your architecture knowledge in sync across your organization.

Architecture docs drift away from reality

Many teams trying to document their software architecture struggle because the implementation drifts away from the documentation. In almost every team I speak to, it goes the same way:

• It's drawn once. A diagram for a design review, a page for a new service. It's a snapshot of the system on the day it was made.
• The implementation keeps moving. New events, changed schemas, replaced services and new data stores, across dozens of repositories and teams.
• Nobody's job is to update it. So it happens late, or not at all.

Nobody decides to let the docs go stale. The gap opens one pull request at a time:

What's running

ship-order.ts

producer.send({ type: 'OrderShipped', orderId, carrier, }); payments.capture(order);

Out of sync

What the docs say9 months ago

ServiceOrders Service

EventOrderCreated

ServiceBilling Service

EventOrderShipped

• Billing Service was replaced by the Payments API
• OrderShipped isn't documented

Neither side was wrong on the day it was written. But nine months on, the diagram describes a system that no longer exists: a service that was replaced, and an event nobody documented.

With EventCatalog, you don't draw your diagrams by hand. They're generated from your documentation: document a service and the messages it sends and receives, and every diagram it appears in follows. That keeps your diagrams in sync with your docs. But it leaves the harder question: how do you keep your docs in sync with your code?

What drift costs you

Out-of-date architecture docs are risky, because people still act on them. When the docs drift, it shows up everywhere:

• Nobody trusts them. Engineers read the code or ask in Slack instead, and the people who know the system get interrupted all day.
• New starters take longer. They learn the system from whoever has been around longest, not from the docs.
• Decisions start from the wrong picture. Design reviews, impact analysis and incident response all begin with a diagram that's out of date.
• AI makes it worse. With AI writing more of our code, teams ship faster than their docs can follow. And the AI tools your teams use now read those docs too. When an agent reads a stale diagram, it doesn't double-check. It gives you the wrong answer with total confidence.

Why architecture docs drift faster than most

Systems change faster than we can update the docs and diagrams that describe them. A single pull request can add an event, change a schema or replace a service, and every page and diagram that mentions it is now slightly wrong.

The responsibility is spread across the organization, too. One team owns the service, another drew the diagram, and someone else wrote the wiki page. When the code changes, it's rarely clear who should update what, so nobody does.

Specifications have solved part of this. Teams that go spec-first with OpenAPI and AsyncAPI keep their API contracts next to their code, and EventCatalog can generate docs from them. But a spec describes one service. It doesn't tell you how your services connect, who owns them, or why they exist.

Everything else usually lives far from the code: in Confluence, a wiki, or a diagram tool that nobody opens while reviewing a pull request. The change happens in one place, the docs live in another, and they quietly go stale.

So the fix has to start where the change happens: in the pull request.

Self-updating architecture knowledge with EventCatalog

EventCatalog lets you document your software architecture with the primitives you already think in: domains, systems, services, messages, schemas and owners. Because your architecture is documented as structure, not free text, it can be automated too. Your architecture knowledge can be kept up to date from different inputs, such as your code, pull requests, specifications and schema registries.

With EventCatalog Agents, you can bring your own models to your catalog, and keep it in sync with your code across your organization.

orders-servicepayments-serviceinventory-service

EventCatalog Agents

your-catalogIn sync

When a pull request merges in one of your repositories, the agent workflow:

1. Reads the change, and finds the resources it affects in your catalog.
2. Plans which docs need to change, and why. If nothing needs to change, it says so and stops.
3. Updates your catalog the way it's already written: same folder structure, same page layout, same conventions.
4. Checks its work with the EventCatalog linter and your fitness functions, and fixes anything it broke.
5. Opens a pull request in your catalog for your team to review.

Nothing reaches your catalog without a review. Merge it, edit it, or close it.

Built for how you work

We built EventCatalog Agents around three things:

Bring your own model. The agents run with your own key: Claude, GPT, a model on Amazon Bedrock, or any other provider. You choose the model, and you pay your provider directly.

Your data stays private. The agents run as a GitHub Action in your own CI. Your code goes only to the model provider you choose. We never see your code, your catalog or your pull requests.

Your own workflows. Every organization is set up differently, and EventCatalog is flexible enough to fit. Point every repository at one central catalog, or give each team its own catalog and combine them with Federation. Update the catalog when a pull request merges, or while it's in review. Use code owners to send each update to the team that owns that part of the catalog.

Get started

The quickest way to set it up is to let your AI coding agent do it. Sync docs with your code has a prompt you can copy into Claude Code, Codex, Cursor or any other agent.

EventCatalog Agents are source available on GitHub. If you'd like help rolling them out across your organization, contact us and we'll walk you through the options.

Your docs shouldn't be where knowledge goes to die. They should be something your teams, and your AI tools, can trust. I'd love to hear how you get on, so come and say hello on Discord.