103 posts tagged with "EventCatalog"

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 decision records (ADRs) are growing in popularity, and they're becoming the standard way to capture an organization's decisions and the conversations behind them.

Teams spend time debating options and writing them up. The ADR goes into a GitHub repository or a document, and people may refer back to it, if you're lucky. But the code keeps changing across the organization, with no automated checks against those ADRs.

I'm happy to share a new workflow in EventCatalog that lets you document your ADRs and add automated checks to make sure code changes adhere to them.

Welcome to the monthly update for EventCatalog. At the end of September we announced EventCatalog v5 and the new licence for the project. In October we shipped it.

This has been one of the biggest months in the history of the project. EventCatalog v5 landed on the 14th, bringing one product with everything included, a new way to read your architecture diagrams, and EventCatalog Studio, live canvases inside your catalog for designing what comes next with your team and your AI agents.

We didn't stop there. Through the rest of the month we added Draw with AI to Studio, a single-file HTML export of your catalog, architecture fitness functions, support for any specification file, and a lot of polish on the new diagrams.

We started the month on 4.12.3 and finished on 5.7.5.

• EventCatalog v5 is here, read the announcement and the v5 upgrade guide
• One diagram, three levels of detail for every domain and system
• Design what comes next in EventCatalog Studio, now with Draw with AI
• Your diagrams inside your AI agent through the MCP server
• Group flows by domain, system or team
• Share your architecture as one HTML file with the architecture reference and custom exports
• Architecture fitness functions that can fail a pull request
• Attach any specification file, such as a WSDL or XML Schema
• Generators are now MIT licensed
• Other project improvements, with links to the relevant pull requests and issues, or browse every EventCatalog release

Last week we launched EventCatalog Studio (v2), live canvases inside your catalog for designing what comes next with your team.

A canvas is a good place to design, but you still have to draw on it. You know what you want to explore, whether that's adding buy now, pay later to checkout, splitting the Order Service, or seeing where the Payments domain might break. Most of the work is the drawing: finding the right services, dragging them on, connecting the right messages, and laying it all out. By the time it looks right, the meeting is over.

General-purpose AI tools don't help much here. They'll draw you boxes and arrows, but they don't know your architecture, so the services are made up and the names are wrong.

Today we're adding Draw with AI to EventCatalog Studio. Describe what you want to design, and the assistant draws it on a Studio canvas while you watch. It uses the services and messages in your catalog, and the AI model you choose.

Here's what it looks like. Type a request, and the assistant draws it:

Your team agrees that services in the Ordering domain should never read from the Payments database. If Ordering needs to know about a payment, it listens for an event or calls the Payments API. You write it down, maybe in an ADR, and everyone nods.

Six months later, someone adds the Payments data store to the Order Service's readsFrom. It was the quickest way to get a feature out. The catalog now documents the dependency perfectly. It doesn't tell anyone that it breaks a decision you made.

That's the gap I keep seeing. Teams spend real time documenting their architecture and agreeing on how it should look, but nothing checks that it still does.

Architecture fitness functions close that gap. The idea comes from Building Evolutionary Architectures by Neal Ford, Rebecca Parsons and Patrick Kua: a fitness function is an automated check that tells you whether your architecture still meets a goal you set for it. Your architectural decisions stop being something people have to remember, and become something that passes or fails.

So we built them into EventCatalog. You can now write architecture fitness functions for your catalog: rules about your architecture, written in TypeScript, that run against your catalog and tell you which resources break them.

Every now and then, someone asks for "a copy of the architecture".

It's never the people who can already open your catalog. It's the partner integrating with your payments, the auditor who needs to know where personal data lives, the team at the company you just acquired, the contractor who is still waiting on VPN access. They need to understand part of your architecture, and they can't get to where it's documented.

So someone opens the catalog, takes twenty screenshots and pastes them into a doc. By next month it's out of date.

API teams sorted this out years ago: write an OpenAPI file, generate a reference from it, send it to anyone. I wanted the same thing for a whole architecture, and a few of you have asked for it too.

So we built it. You can now export your catalog as one HTML file: all of it, or just the part someone needs. Every domain, system, service, message and flow in it is linked to everything it relates to, and it's written again every time you build.

EventCatalog is good at telling you how your architecture works today. Your teams document their domains, services and messages, and everyone can find out what talks to what.

But the conversations that matter most are often about tomorrow. "How would we add buy now, pay later?" "What happens if we split the Order Service?" "Who needs to know if we retire this API?"

Those conversations usually happen somewhere else: a whiteboard, a slide, a diagram tool that knows nothing about your architecture. Someone redraws the services by hand, gets a few of them wrong, and the result ends up in a folder nobody opens again.

We kept hearing the same thing from customers: we document the present in EventCatalog, but we plan the future somewhere else.

Today we're excited to introduce EventCatalog Studio (v2): live, collaborative canvases inside your catalog, for designing what comes next with your team and your AI agents.

The first version of EventCatalog Studio was a separate tool for drawing designs with architecture primitives. Studio v2 lives inside EventCatalog itself, so your designs start from the architecture you already document, and your team and your agents can work on them together.

A flow tells the story of a business process. A shopper checks out, the cart is priced, payment is authorized, the order is created, and the customer gets a confirmation.

Flows in EventCatalog have always been good at showing the steps. But once a team has the steps, the next questions are almost always about ownership:

• Which teams are involved in this process?
• Where does it cross from one domain into another?
• Which systems have to work together for this to succeed?

Those questions matter because every boundary in a flow is a handoff. It's a contract between two teams, a dependency someone has to coordinate, and usually the place where things break. Until now, you had to work that out by clicking through each step.

In EventCatalog v5, you can group any flow by domain, system or team. You see the boundaries straight away, and you don't need to change a single line of your flows.

Ask an AI tool how a service works and you get a wall of text.

"The Order Service accepts PlaceOrder, publishes OrderCreated and OrderCancelled, which are consumed by Fulfilment and Notifications, which..." By the third service, you are drawing the diagram in your head.

Some tools will draw one for you. But a diagram an AI model generates is a guess. It can look right and still be wrong, and you have no way to tell without checking it against the real thing.

You already have the real thing. Your catalog knows exactly how your services, messages and domains connect.

In EventCatalog v5, the MCP server can show your actual architecture diagrams and schemas inside the conversation. In Claude, ChatGPT, VS Code and other tools that support MCP Apps, you get the interactive EventCatalog visualiser right in the chat.

Different people ask different questions of the same architecture.

A head of engineering wants to know which domains depend on each other. An architect wants to see the systems inside a domain and how they connect. An engineer about to change a service wants to see every message it sends and receives.

Until now, EventCatalog answered those questions with different pages. A domain had a System Diagram and a Resource Diagram. A system had a Context Diagram and a Resource Diagram. Services had a Data Dependency Graph, and there was a Domain Integration Map that most people never found. They were useful, but you had to know which one to open.

In EventCatalog v5, every domain and system has one diagram with three levels of detail. Start with the big picture, then zoom in until you can see the messages.

EventCatalog started as an open source project. The idea was simple: document event-driven architectures in a way that doesn't go stale the week after someone draws the diagram. The community took it further than we ever expected. Today hundreds of organisations use it every month, from startups to banks, airlines and some of the biggest retailers in the world.

To make the project sustainable, we moved to an open-core model: the catalog free and open source, with paid plugins, integrations and enterprise features on top. It worked for a while, and it's the reason EventCatalog could become a full-time project. But AI is changing the ecosystem around EventCatalog, and the open-core model we have today no longer fits it.

So with EventCatalog v5, we're simplifying everything: one product, simpler pricing, and a new licence. EventCatalog stays free for individuals, open-source projects, education and organisations under $10M. Organisations above that pay by how many teams use the catalog, and every release becomes open source in the long run.

When someone opens a schema in your catalog, they rarely stop at the schema.

They want to know how to publish the message. Who else is consuming it. Which business flow it is part of. What changed since the version they integrated against.

Until now, most of those answers lived somewhere else in the catalog, or in someone's head.

EventCatalog 4.12 turns every schema into a page your consumers can work from.

This release (along with 4.11, which shipped the first part of this work) brings:

• A richer schema page: tabs for examples, producers and consumers, flows, versions, and details, all linkable.
• Written usage examples: explain how to use a message, with code in several languages, right next to the schema.
• Two new components: <Columns /> and <CodeGroup />, for any page in your catalog.
• No more .eventcatalog-core folder: EventCatalog now runs directly inside your project.
• Custom pages that match the rest of your catalog, and the assistant upgraded to AI SDK v7.