Welcome to the Architecture Corner.
Today we're digging into a challenge.
I think many of you know all too well the sheer complexity of
modern software systems, especially those builds with
event driven architectures. Keeping documentation
up-to-date, useful, even just findable, it could feel like a
constant struggle. Oh absolutely.
It's a huge pain point, but you've got this mix right?
Synchronous API is asynchronous stuff.
Commands, queries, events flying around, and if your contract
documentation isn't solid and current, well, bringing in new
services or even just understanding the flow becomes a
real headache. Remember one place we literally
had giant whiteboard drawings of event flows because the digital
docs were just all? Useless.
Exactly that scenario. So our mission today is to look
at a really interesting solution, one that's being
called maybe the missing piece for actually understanding these
complex systems. We're basing this on a great
article by Mario Bittencourt over on ITV.
NXT talks about turning that information chaos into something
clear, something interactive. Yeah.
And that solution is Event Catalog.
It's open source and it's specifically built to help you
discover and understand your event driven architecture.
The core idea is this documentation as code approach
and that's a big shift. Documentation as dash code.
OK, how does that change things practically?
Well, it means the documentation lives with the code.
It's version control. You can potentially test against
it. It drastically cuts down on that
lag where the code changes but the docs don't.
For weeks or months. Your documentation stops being
the static, often out of date thing and becomes an active part
of understanding your system's health.
It can't really drift out of sync.
Right, that makes sense. So it's living documentation,
but the article talks about it being interactive.
How does Event Catalog make it more than just, say, up-to-date
markdown files? What are the key parts?
Good question. So event catalog defines some
core building blocks. You've got messages, that's your
commands, Events, queries, the actual information being passed.
But then you have channels. Think of these as the pathways.
Could be a Kafka topic, an SQQ, maybe even an Http://endpoint
for certain patterns. It maps the routes and then
there are domains to group things logically, services, the
actual applications, sending or receiving messages and
importantly, entities. Like business objects?
Exactly your customer order product defined right there with
identifiers, maybe relationships.
It elevates the docs beyond just message formats.
Plus, you can link users and teams as owners for these
domains or services, so accountability is clear.
And this really helps foster that ubiquitous language from
Domain Driven Design because you define the terms right there in
the shared documentation for that domain.
OK, so defining all these pieces, messages, channels,
services, entities, even owners, builds this structured view.
Let's make it concrete. Imagine you've got a new
architect joining without something like this.
How long does it take them to trace, say, a points redeemed
event across different systems? Loyalty.
Fulfillment. Ages potentially with Vent
catalog, because you've defined these things, usually in simple
markdown files with some front matter, it can generate this
interactive map. You can click on a service, see
what it sends, what it receives, follow the path of an event.
And it understands difference keep formats too right?
Like open API is sync API, what does that unlock?
Yeah, support for things like open API, async API, Jason
schema, Avro is key. This isn't just about a visual
diagram. It means event catalog can be
your single source of truth for those contracts.
And that opens the door to things like automated contract
testing, integrating with API gateways, maybe even generating
client code. It turns the documentation into
a real engineering tool. That sounds powerful, especially
for bigger, more complex systems.
But what about getting started? Is there a big hurdle for teams
already deep in a project? This doc is code thing.
Honestly, the learning curve is pretty gentle.
It uses markdown YAML stuff most developers know.
Integrating it into git workflows is usually
straightforward. The real work is the initial
effort of defining your system components, but the payoff
making the implicit explicit. That shared understanding the
interactive map comes pretty quickly.
So wrapping up what we've seen is that Event Catalog offers
this interactive, genuinely helpful way to document event
driven systems. It uses that documentation as
code approach to map out domain services messages.
It brings clarity where there's often just a complexity.
And as Mario Bittencourt's article points out, bringing in
concepts like Ubiquitous Language Owners entities really
enriches that understanding. Yeah, imagine just being able to
click through a live catalog and understand any part of your
event system. It's not just about docs
anymore, it's really about enabling better collaboration,
getting people up to speed, plaster, and building systems
that are fundamentally easier to grasp.
Definitely something to think about.
For more information and to dive deeper into event catalog and
these ideas, do check out the description for this deep dive.
And of course, don't forget to subscribe for free to the
Architecture Corner newsletter over at
architecturecorner.substack.com.