1
00:00:00,100 --> 00:00:01,770
Welcome to the Architecture 
Corner. 

2
00:00:01,960 --> 00:00:03,970
Today we're digging into a 
challenge. 

3
00:00:03,980 --> 00:00:09,490
I think many of you know all too
well the sheer complexity of 

4
00:00:09,500 --> 00:00:13,130
modern software systems, 
especially those builds with 

5
00:00:13,140 --> 00:00:16,450
event driven architectures. 
Keeping documentation 

6
00:00:16,460 --> 00:00:20,310
up-to-date, useful, even just 
findable, it could feel like a 

7
00:00:20,320 --> 00:00:21,930
constant struggle. 
Oh absolutely. 

8
00:00:21,940 --> 00:00:24,530
It's a huge pain point, but 
you've got this mix right? 

9
00:00:24,540 --> 00:00:26,410
Synchronous API is asynchronous 
stuff. 

10
00:00:26,420 --> 00:00:29,850
Commands, queries, events flying
around, and if your contract 

11
00:00:29,860 --> 00:00:32,870
documentation isn't solid and 
current, well, bringing in new 

12
00:00:32,880 --> 00:00:36,330
services or even just 
understanding the flow becomes a

13
00:00:36,340 --> 00:00:38,470
real headache. 
Remember one place we literally 

14
00:00:38,480 --> 00:00:41,730
had giant whiteboard drawings of
event flows because the digital 

15
00:00:41,740 --> 00:00:44,070
docs were just all? 
Useless. 

16
00:00:44,080 --> 00:00:46,850
Exactly that scenario. 
So our mission today is to look 

17
00:00:46,860 --> 00:00:48,910
at a really interesting 
solution, one that's being 

18
00:00:48,920 --> 00:00:51,970
called maybe the missing piece 
for actually understanding these

19
00:00:51,980 --> 00:00:54,000
complex systems. 
We're basing this on a great 

20
00:00:54,010 --> 00:00:55,750
article by Mario Bittencourt 
over on ITV. 

21
00:00:55,760 --> 00:00:59,170
NXT talks about turning that 
information chaos into something

22
00:00:59,180 --> 00:01:00,910
clear, something interactive. 
Yeah. 

23
00:01:00,980 --> 00:01:03,120
And that solution is Event 
Catalog. 

24
00:01:03,170 --> 00:01:07,000
It's open source and it's 
specifically built to help you 

25
00:01:07,070 --> 00:01:10,120
discover and understand your 
event driven architecture. 

26
00:01:10,170 --> 00:01:13,640
The core idea is this 
documentation as code approach 

27
00:01:13,710 --> 00:01:17,700
and that's a big shift. 
Documentation as dash code. 

28
00:01:18,190 --> 00:01:20,520
OK, how does that change things 
practically? 

29
00:01:20,610 --> 00:01:23,120
Well, it means the documentation
lives with the code. 

30
00:01:23,130 --> 00:01:25,900
It's version control. 
You can potentially test against

31
00:01:25,910 --> 00:01:28,120
it. 
It drastically cuts down on that

32
00:01:28,130 --> 00:01:31,530
lag where the code changes but 
the docs don't. 

33
00:01:31,620 --> 00:01:34,470
For weeks or months. 
Your documentation stops being 

34
00:01:34,480 --> 00:01:38,250
the static, often out of date 
thing and becomes an active part

35
00:01:38,260 --> 00:01:39,710
of understanding your system's 
health. 

36
00:01:39,720 --> 00:01:41,410
It can't really drift out of 
sync. 

37
00:01:41,460 --> 00:01:43,610
Right, that makes sense. 
So it's living documentation, 

38
00:01:43,880 --> 00:01:46,170
but the article talks about it 
being interactive. 

39
00:01:46,220 --> 00:01:49,150
How does Event Catalog make it 
more than just, say, up-to-date 

40
00:01:49,160 --> 00:01:50,850
markdown files? 
What are the key parts? 

41
00:01:51,080 --> 00:01:54,050
Good question. 
So event catalog defines some 

42
00:01:54,060 --> 00:01:56,510
core building blocks. 
You've got messages, that's your

43
00:01:56,520 --> 00:02:00,690
commands, Events, queries, the 
actual information being passed.

44
00:02:00,700 --> 00:02:04,100
But then you have channels. 
Think of these as the pathways. 

45
00:02:04,110 --> 00:02:08,780
Could be a Kafka topic, an SQQ, 
maybe even an Http://endpoint 

46
00:02:08,789 --> 00:02:11,370
for certain patterns. 
It maps the routes and then 

47
00:02:11,380 --> 00:02:14,850
there are domains to group 
things logically, services, the 

48
00:02:14,860 --> 00:02:17,260
actual applications, sending or 
receiving messages and 

49
00:02:17,270 --> 00:02:20,410
importantly, entities. 
Like business objects? 

50
00:02:20,420 --> 00:02:24,220
Exactly your customer order 
product defined right there with

51
00:02:24,230 --> 00:02:26,120
identifiers, maybe 
relationships. 

52
00:02:26,330 --> 00:02:28,700
It elevates the docs beyond just
message formats. 

53
00:02:28,710 --> 00:02:31,840
Plus, you can link users and 
teams as owners for these 

54
00:02:31,850 --> 00:02:34,530
domains or services, so 
accountability is clear. 

55
00:02:34,600 --> 00:02:37,100
And this really helps foster 
that ubiquitous language from 

56
00:02:37,110 --> 00:02:39,920
Domain Driven Design because you
define the terms right there in 

57
00:02:39,930 --> 00:02:41,850
the shared documentation for 
that domain. 

58
00:02:41,920 --> 00:02:45,890
OK, so defining all these 
pieces, messages, channels, 

59
00:02:45,940 --> 00:02:51,330
services, entities, even owners,
builds this structured view. 

60
00:02:51,380 --> 00:02:53,820
Let's make it concrete. 
Imagine you've got a new 

61
00:02:53,830 --> 00:02:56,730
architect joining without 
something like this. 

62
00:02:56,780 --> 00:03:00,090
How long does it take them to 
trace, say, a points redeemed 

63
00:03:00,100 --> 00:03:02,810
event across different systems? 
Loyalty. 

64
00:03:02,860 --> 00:03:05,690
Fulfillment. 
Ages potentially with Vent 

65
00:03:05,700 --> 00:03:09,090
catalog, because you've defined 
these things, usually in simple 

66
00:03:09,100 --> 00:03:11,990
markdown files with some front 
matter, it can generate this 

67
00:03:12,000 --> 00:03:13,980
interactive map. 
You can click on a service, see 

68
00:03:13,990 --> 00:03:17,110
what it sends, what it receives,
follow the path of an event. 

69
00:03:17,200 --> 00:03:19,190
And it understands difference 
keep formats too right? 

70
00:03:19,200 --> 00:03:22,150
Like open API is sync API, what 
does that unlock? 

71
00:03:22,160 --> 00:03:25,590
Yeah, support for things like 
open API, async API, Jason 

72
00:03:25,600 --> 00:03:28,450
schema, Avro is key. 
This isn't just about a visual 

73
00:03:28,460 --> 00:03:30,110
diagram. 
It means event catalog can be 

74
00:03:30,120 --> 00:03:32,870
your single source of truth for 
those contracts. 

75
00:03:33,040 --> 00:03:35,740
And that opens the door to 
things like automated contract 

76
00:03:35,750 --> 00:03:38,870
testing, integrating with API 
gateways, maybe even generating 

77
00:03:38,880 --> 00:03:41,530
client code. 
It turns the documentation into 

78
00:03:41,540 --> 00:03:44,410
a real engineering tool. 
That sounds powerful, especially

79
00:03:44,420 --> 00:03:45,910
for bigger, more complex 
systems. 

80
00:03:46,350 --> 00:03:49,340
But what about getting started? 
Is there a big hurdle for teams 

81
00:03:49,350 --> 00:03:52,350
already deep in a project? 
This doc is code thing. 

82
00:03:52,590 --> 00:03:54,700
Honestly, the learning curve is 
pretty gentle. 

83
00:03:54,750 --> 00:03:57,340
It uses markdown YAML stuff most
developers know. 

84
00:03:57,350 --> 00:03:59,940
Integrating it into git 
workflows is usually 

85
00:03:59,950 --> 00:04:02,410
straightforward. 
The real work is the initial 

86
00:04:02,420 --> 00:04:05,410
effort of defining your system 
components, but the payoff 

87
00:04:05,420 --> 00:04:08,960
making the implicit explicit. 
That shared understanding the 

88
00:04:08,970 --> 00:04:10,920
interactive map comes pretty 
quickly. 

89
00:04:11,430 --> 00:04:14,420
So wrapping up what we've seen 
is that Event Catalog offers 

90
00:04:14,430 --> 00:04:19,630
this interactive, genuinely 
helpful way to document event 

91
00:04:19,640 --> 00:04:22,180
driven systems. 
It uses that documentation as 

92
00:04:22,190 --> 00:04:25,620
code approach to map out domain 
services messages. 

93
00:04:25,630 --> 00:04:28,230
It brings clarity where there's 
often just a complexity. 

94
00:04:28,290 --> 00:04:30,620
And as Mario Bittencourt's 
article points out, bringing in 

95
00:04:30,630 --> 00:04:33,990
concepts like Ubiquitous 
Language Owners entities really 

96
00:04:34,000 --> 00:04:36,860
enriches that understanding. 
Yeah, imagine just being able to

97
00:04:36,870 --> 00:04:41,240
click through a live catalog and
understand any part of your 

98
00:04:41,250 --> 00:04:43,160
event system. 
It's not just about docs 

99
00:04:43,170 --> 00:04:46,600
anymore, it's really about 
enabling better collaboration, 

100
00:04:46,610 --> 00:04:48,960
getting people up to speed, 
plaster, and building systems 

101
00:04:48,970 --> 00:04:50,910
that are fundamentally easier to
grasp. 

102
00:04:50,920 --> 00:04:52,120
Definitely something to think 
about. 

103
00:04:52,160 --> 00:04:55,040
For more information and to dive
deeper into event catalog and 

104
00:04:55,050 --> 00:04:58,610
these ideas, do check out the 
description for this deep dive. 

105
00:04:58,680 --> 00:05:01,890
And of course, don't forget to 
subscribe for free to the 

106
00:05:01,900 --> 00:05:03,410
Architecture Corner newsletter 
over at 

107
00:05:03,420 --> 00:05:05,490
architecturecorner.substack.com.