EventCatalog to świetne narzędzie, które pomaga udokumentować architekturę naszego systemu. W tym artykule pokażę Ci, jak działa on w praktyce, oraz poznasz kilka wskazówek, które pozwolą Ci pracować z nim wydajniej.

Jeśli preferujesz format video, to poniżej znajdziesz omówienie tematu wraz z demo wybranych funkcjonalności:

Czym jest EventCatalog?

EventCatalog to narzędzie do dokumentowania i wizualizacji architektury systemów. Umożliwia utworzenie katalogu zdarzeń, komend, domen, usług oraz zależności między nimi. W przeciwieństwie do wielu popularnych alternatyw dostępnych na rynku EventCatalog został zaprojektowany z myślą o dokumentowaniu architektury systemów. Dzięki specjalizacji narzędzia, dokumentowanie architektury jest moim zdaniem prostsze niż w konkurencyjnych produktach.

EventCatalog pozwala wdrożyć podejście Documentation as code. Dokumentacja projektu jest przechowywana w repozytorium w postaci plików tekstowych. Pozwala to na jej wersjonowanie z wykorzystaniem Gita, szybką aktualizację, przeglądanie w IDE i pull requestach, czy integrowanie z istniejącymi procesami CI/CD. EventCatalog wykorzystuje przygotowane wcześniej definicje i tworzy katalog obiektów opisujący system oraz interaktywne diagramy przedstawiające przepływ zdarzeń i relacje między nimi.

Takie narzędzie to świetny sposób na opisanie architektury i świetna alternatywa dla ręcznie rysowanych diagramów czy zwykłych plików tekstowych. Wdrożenie EventCatalog w projekcie nie tylko pomoże w dzieleniu się wiedzą o systemie w zespole, ale też pomoże wdrożyć się nowym osobom w projekt.

Elementy składowe EventCatalogu

Składowymi EventCatalogu są elementy znane z systemów zbudowanych w architekturze opartej na zdarzeniach.

Events – fakty opisujące coś, co już wydarzyło się w systemie. Logicznie są one traktowane jako niemutowalne i nie reprezentują instrukcji do wykonania. Przykłady: OrderCreated, PaymentAccepted, AccountSuspended.

Commands – reprezentują intencję wykonania operacji zmieniającej stan systemu. Przykłady: CreateOrder, ProcessPayment, SuspendAccount.

Queries – definiują zapytania wysyłane przez system. Query z definicji oczekuje odpowiedzi. EventCatalog obecnie nie oferuje wygodnego modelowania odpowiedzi. W praktyce można modelować odpowiedź jako osobny obiekt, np. dla GetOrderDetails odpowiednio GetOrderDetailsResponse, co pozwala zachować czytelność kontraktu.

Services – opisują serwisy istniejące w ramach danego systemu. Można w nich zdefiniować elementy, które serwis otrzymuje i wysyła, oraz zwizualizować je w formie grafu.

Domains – dokumentują zdefiniowane domeny biznesowe w ramach systemu np. Subscriptions, Payments. Pozwalają na przypisywanie innych zasobów np. Services czy Entities.

Entities – dokumentują obiekty biznesowe istniejące w systemie np. Subscription, Order czy Customer.

Flows – przedstawiają sekwencje i procesy dziejące się w systemie. Do ich modelowania możemy wykorzystać elementy zdefiniowane wcześniej, w szczególności Events, Commands i Queries. Nie ma sztywnego wymogu tworzenia pełnej definicji każdego elementu flow. Jednak skrupulatne pilnowanie dodawania definicji elementów z pewnością pomaga w zachowaniu spójności zarówno danego flow, jak i reszty EventCatalogu.

Elementy definiowane w EventCatalogu można wersjonować. Może to być przydatne, jeśli chcemy zachować jawną historyczność ewolucji kontraktu. Przyda się też, jeśli ewolucja kontraktów w naszym systemie jest stopniowa i w tym samym czasie system może pracować z kontraktami w kilku wersjach.

Dodatkowo EventCatalog umożliwia przechowywanie i przeglądanie Architecture Decision Records. Trzymanie ich blisko reszty dokumentacji sprzyja temu, że ktoś kiedyś je znajdzie i z nich skorzysta.

EventCatalog wspiera również tworzenie diagramów z wykorzystaniem Mermaid. Jest to kolejne narzędzie idące z duchem Documentation as Code. Wykorzystanie Mermaid może stanowić świetne uzupełnienie dla mechanizmów z EventCatalogu. Jeśli nasza obecna dokumentacja zawiera diagramy narysowane w Mermaid, to przy migracji nie jesteśmy od razu skazani na ich całkowite porzucenie. Możemy je na start wrzucić do EventCatalogu i stopniowo przenosić do nowego narzędzia.

Instalacja

Do instalacji wymagany jest Node.js w wersji 22 lub wyższej. Instalację można wykonać, wywołując polecenie kreatora w CLI w miejscu, gdzie chcemy utworzyć katalog. W miejsce podajemy nazwę katalogu, w którym utworzony zostanie katalog.

npx @eventcatalog/create-eventcatalog@latest 

Jeśli myślimy o budowaniu faktycznego katalogu, rekomenduję wywołanie polecenia z parametrem --empty. W przeciwnym razie katalog zostanie stworzony z przykładami opisanych wcześniej elementów.

Kolejnym krokiem jest instalacja zależności (npm install) i uruchomienie serwera (npm run dev). Dość regularnie przy tym kroku trafiałem na błędy z biblioteki Astro. Jeśli taki problem wystąpi w Twoim przypadku, spróbuj usunąć katalog node_modules i przeinstalować zależności. Możesz również przeinstalować globalne dependencje. W moim przypadku zwykle to pomaga.

Swego czasu trafiłem również na problem z uruchomieniem katalogu, którego źródłem było wykorzystanie pnpm i jego funkcji workspaces. W tym przypadku rozwiązaniem było skorzystanie z opcji shamefullyHoist. Domyślnie katalog uruchamia się na porcie 3000.

Event Catalog Studio

Jeśli interesuje nas jedynie rysowanie diagramów i nie chcemy męczyć się z deploymentem i utrzymaniem pełnej wersji katalogu, to możemy skorzystać z webowej aplikacji EventCatalog Studio. Można ją traktować jako wyspecjalizowaną alternatywę dla narzędzi takich jak Miro czy Excalidraw.

Personalnie jestem fanem pełnego EventCatalogu, jednak jeśli komuś możliwości wersji webowej wystarczą, to wykorzystanie jej będzie dużo prostsze niż samodzielne stawianie pełnego katalogu.

Jak lepiej pracować z EventCatalogiem?

Praktyki opisane w dalszej części wynikają głównie z mojego doświadczenia w pracy z EventCatalogiem. Niezależnie od tego, czy skorzystasz z moich wskazówek, czy nie, zachęcam, byś wypróbował to narzędzie i samodzielnie wypracował sposób pracy, który będzie dla Ciebie odpowiedni.

Wykorzystaj AI

Najbardziej oczywistym zastosowaniem AI w pracy z EventCatalogiem jest tworzenie dokumentacji na podstawie istniejącej architektury. O ile udokumentowanie struktury eventów czy istniejących elementów systemu może nie być problematyczne, tak zamodelowanie przepływów czy relacji między systemami może już nie być trywialne. Istnieje spore ryzyko przekłamań, uwzględnienia nieistotnych komponentów systemu lub nieuwzględnienia istotnych. Jeżeli model sobie poradzi z tym zadaniem, to będzie to wymagało analizy praktycznie całego codebase. Jednak nawet to nie gwarantuje, że otrzymana dokumentacja będzie poprawna.

EventCatalog rozwijałem w dużej mierze z wykorzystaniem Claude Code. Generowane pliki i ich struktury były praktycznie zawsze poprawne i wiernie odzwierciedlały rzeczywistość. W przypadku opisywania przepływów i zależności początkowo wymagał nakierowania go, by projektował je zgodnie z moimi oczekiwaniami. Jednak wraz z powstawaniem kolejnych uwag pojawiało się coraz mniej, a oczekiwane rezultaty pojawiały się coraz szybciej.

Lepszym zastosowaniem AI jest pilnowanie aktualności dokumentacji. LLM-y świetnie radzą sobie z pilnowaniem rozjazdu między strukturą eventów a jej opisem w dokumentacji. Przy odrobinie wysiłku są również w stanie wyłapywać zmiany w przepływach czy zależnościach.

Analizę zgodności diagramów z rzeczywistością można wpleść w proces code review robionego przez AI jako punkt na checkliście do sprawdzenia. Nawet jeśli LLM nie zaktualizuje za nas zawartości katalogu, to wskaże nam braki, które będziemy mogli uzupełnić samodzielnie.

EventCatalog pozwala również na wystawienie serwera MCP. Dzięki temu możemy podłączyć go do naszego firmowego agenta i w razie potrzeby odpytać o szczegóły architektoniczne lub wykorzystać wiedzę zgromadzoną w katalogu.

Autor EventCatalogu przygotował również zestaw skillów pomocnych w codziennej pracy. Można je wykorzystać np. w przenoszeniu diagramów C4 czy do usprawniania opisu obecnej architektury.

Najpierw wpis do katalogu, a potem implementacja… lub na odwrót!

Nie jest to porada ściśle związana z samym narzędziem, a raczej dotycząca ogólnego podejścia do projektowania systemów. Rzucając się w wir implementacji przed powstaniem dokumentacji, możemy dojść do miejsca, w którym okaże się, że czegoś nie przewidzieliśmy. Nasze rozwiązanie może okazać się niewystarczające lub błędne.

Rozpoczynając pracę od rozrysowania i udokumentowania naszego pomysłu, dajemy sobie szansę na wyłapanie takich problemów przed etapem implementacji. Na wyrysowanym diagramie znacznie łatwiej jesteśmy w stanie dostrzec ewentualne nieścisłości, braki czy sprzeczności. Mając gotowe definicje i diagramy, jesteśmy w stanie również efektywniej przedyskutować nasz pomysł z resztą zespołu. Również rozpoczynając pracę od dokumentacji, unikamy sytuacji, gdy dokumentacja ostatecznie nie powstaje, czy to z roztargnienia, czy z uwagi na inne priorytety.

Problem może stanowić to, że ostateczna implementacja może w detalach różnić się od projektu i trzeba to uwzględnić w dokumentacji.

Opisane podejście ma rację bytu w dojrzałych systemach, gdzie istnieją już ugruntowane części systemu. W świeżych i dynamicznie rozwijających się systemach takie podejście może prowadzić do nadmiernej formalizacji procesu. Ponadto dostosowywanie dokumentacji do każdej zmiany w kodzie jest bezproduktywne i każda niespójność obniża zaufanie do dokumentacji i jej użyteczność. Przy dużej dynamice prac rozważyłbym dokumentowanie zmian dopiero gdy poczujemy, że dane zmiany się ugruntowały w systemie.

Dokumentuj tylko to, co faktycznie potrzeba i twórz małe flows

To dość oczywiste, że małe flow czyta się lepiej niż duże. Jednak sam na początku mojej przygody z EventCatalogiem notorycznie łapałem się na próbie pełnego zobrazowania systemu wraz ze wszystkimi szczegółami. Jednak po czasie uważam, że jest to błędne podejście. Nie tylko wymaga ono wysiłku niewspółmiernego do korzyści, ale też prowadzi do stworzenia katalogu, który jest arcytrudny do utrzymania w dłuższej perspektywie.

Jeśli mamy duże flow, warto zastanowić się, czy można rozbić je na kilka mniejszych i wzajemnie je polinkować. Również jeśli mamy fragment powtarzalny w wielu flow, to można go wyciągnąć do osobnego flow i zlinkować w pozostałych. Przykładowo, jeśli mamy prosty serwer wystawiający CRUD schowany za load balancerem, to zamiast tworzyć 4 flow opisujące całość, postawiłbym na trzy proste flow:

• Flow przedstawiające rolę load balancera w komunikacji między klientem a serwerem.
• Opis flow zwracającego dane z wykorzystaniem Query.
• Opis flow wykonującego polecenie w systemie – Create/Update/Delete.

Jeśli jest taka potrzeba, można rozbić to na trzy osobne flow dla każdego polecenia. Jednak w przypadku prawdziwego systemu zastanowiłbym się, czy dokumentowanie tak prostych rzeczy ma w ogóle sens. Proste synchroniczne flow raczej nie wymagają dokumentacji do pełnego zrozumienia. Zdecydowanie większą korzyść ma dokumentowanie nieoczywistych flow, szczególnie tych asynchronicznych i opartych na zdarzeniach. Prześledzenie ich w kodzie i debuggowanie to dużo trudniejsze zadanie niż w przypadku prostych synchronicznych akcji.

Duplikacja klocków dla lepszej czytelności, ale kosztem rzetelności

We wczesnych wersjach EventCatalogu sporym problemem była niska czytelność przepływów na generowanych diagramach. Strzałki generowały się tak, by ich długość była ograniczona do minimum, bez uwzględniania innych strzałek czy etykiet. Na przestrzeni kolejnych wersji problem ten częściowo udało się poprawić. Jednak bardziej złożone flow wciąż bywają nieczytelne. Tyczy się to szczególnie flow, gdzie powstają pętle. Przeanalizuj poniższy przykład.

By pozbyć się pętli i przekształcić flow w prostą sekwencję, możemy zdefiniować kopię UsersService, np. dodając sufiks w id elementu. Dzięki temu powstanie liniowy flow, który jest prostszy w zrozumieniu.

Różnica ta będzie tym bardziej widoczna, im bardziej mamy złożone flow. Jeśli celem jest wyłącznie uproszczenie prezentacji, taki zabieg może mieć sens. Czasami pokazanie złożoności i nieliniowości danego flow jest pożądane.

Z tym zabiegiem należy jednak uważać. Jeśli zależy nam na wiernym odwzorowaniu systemu, taki zabieg może być wręcz szkodliwy. Diagramy powinny jawnie pokazywać pętle i złożoność komunikacyjną systemu. Daje to obraz trudniejszy w odbiorze, lecz lepiej opisujący rzeczywistość.

Korzystaj z ikonek i kolorów

Wykorzystanie ikon i kolorów może istotnie zwiększyć czytelność tworzonych przez nas diagramów. Pomoże to również w szybszym przyswojeniu diagramu, czasami bez konieczności czytania opisu każdego elementu.

Komponenty podobnego typu można oznaczać tymi samymi kolorami. W przypadku kolorów możemy również postawić na kolory spójne z identyfikacją wizualną określonych technologii. Np. w przypadku NGINX-a można wybrać kolor zielony, a w przypadku PostgreSQL niebieski. W przypadku ikon EventCatalog wykorzystuje repozytorium Heroicons.

Przeanalizuj przykład prostego flow diagramu opisującego synchroniczne zapytanie użytkownika przechodzące przez load balancer i kończące się zapisem do bazy danych.

Diagram oczywiście spełnia swoje zadanie. Zobacz jednak, o ile bardziej czytelnie będzie on wyglądał po dodaniu kolorów i ikon dla poszczególnych technologii.

Problemy z EventCatalogiem

Po omówieniu zalet EventCatalogu przejdźmy do omówienia jego ograniczeń.

Utrzymanie

Moja praktyka pracy pokazuje, że jeżeli nie mamy zautomatyzowanej procedury aktualizującej zawartość katalogu, to prędzej czy później rzeczywisty stan systemu i zawartość katalogu się rozjedzie. Tu ktoś doda nowe pole do eventu i zapomni zaktualizować katalog. Tam ktoś wykorzysta event w nowym miejscu i nie opisze przepływu. Jeśli nie będziemy trzymać ręki na pulsie, to katalog przestanie opisywać rzeczywistość i stanie się bezwartościowy.

Idealnym rozwiązaniem byłoby pełne zautomatyzowanie tego procesu. O ile w przypadku opisania struktury eventów raczej nie powinno to stanowić problemu, o tyle automatyzacja opisywania zależności czy przepływów może być już nieco bardziej karkołomnym zadaniem. Nawet jeśli udałoby się to zautomatyzować, jakość takiej dokumentacji może pozostawiać wiele do życzenia.

W pracy nad utrzymaniem spójności i aktualności zawartości EventCatalogu pomocne są narzędzia AI. W szczególności mam na myśli te mające dostęp do kodu źródłowego, takie jak Claude Code czy Cursor.

Połączenie kilku projektów

Jeśli w ramach naszej organizacji rozwijamy kilka projektów i dokumentujemy je z wykorzystaniem EventCatalog, to jeśli te projekty są w jakimkolwiek stopniu komplementarne, to pojawi się potrzeba połączenia katalogów.

Połączenie kilku instancji EventCatalog jest możliwe z wykorzystaniem EventCatalog Federation. Należy jednak powiedzieć uczciwie, że nie jest to gra warta świeczki. By móc skorzystać z tej funkcjonalności, konieczne jest przejście na płatny plan Scale lub Enterprise. W przypadku tego tańszego mówimy o kwocie $449 miesięcznie. Nawet jeśli uwzględnimy całą masę innych funkcjonalności, które daje przejście na płatne plany, $449 miesięcznego fee za produkt będący wewnętrzną dokumentacją projektową to moim zdaniem zdecydowanie zbyt dużo.

Jako darmową alternatywę można rozważyć duplikację potrzebnych nam komponentów czy workflow, lub definiowanie innego projektu jako External i odsyłanie do jego event catalogu linkiem.

Sporadyczne problemy ze stabilnością

Niestety, po projekcie momentami widać, że nie stoi za nim żaden duży gracz. Zdarzają się wpadki, np. opublikowanie wersji, która nie buduje się poprawnie, problemy z UI czy problemy z zależnościami. Nawet stawiając testowy EventCatalog od zera na potrzeby tego artykułu, trafiłem na problemy z zależnościami, których rozwiązanie zajęło mi dłuższą chwilę. Potencjalne problemy i ich rozwiązania opisałem zresztą w sekcji dotyczącej instalacji narzędzia.

Absolutnie nie jest to wada skreślająca EventCatalog, jednak warto być świadomym, że takie problemy sporadycznie występują. Zwykle cofnięcie się o jedną wersję wcześniej lub przeinstalowanie zależności rozwiązuje problem.

Kiedy NIE korzystać z EventCatalogu?

EventCatalog to dość zaawansowane i rozbudowane narzędzie. Tym stwierdzeniem można już pośrednio wskazać część przypadków, gdzie jego wykorzystanie mija się z celem. Jeśli nasza aplikacja jest mała i prosta, to dokumentowanie jej w EventCatalogu będzie armatą na muchę. Włożymy dużo wysiłku w przygotowanie i utrzymanie dokumentacji przy otrzymaniu marginalnych korzyści. W przypadku prostych i małych systemów, zamiast tworzyć obszerną dokumentację, czas lepiej poświęcić na rozwój samej aplikacji.

Kolejnym przypadkiem, w którym EventCatalog nie przynosi dużej wartości, są niewielkie systemy pozbawione komunikacji asynchronicznej i złożonych zależności. W takich przypadkach większość informacji o przepływach i kontraktach można szybko znaleźć bezpośrednio w kodzie.

Podsumowanie

Jestem ogromnie ciekaw Twoich doświadczeń w dokumentowaniu architektury i building blocków systemu. Jeśli EventCatalog jest Ci znany, to koniecznie daj znać w komentarzu, jak Ci się z nim pracuje. Jeśli wykorzystujesz inne narzędzia dokumentacyjne, to również zachęcam do podzielenia się nimi w komentarzu. Ponownie zachęcam też do sprawdzenia powiązanego materiału video.

Źródła i materiały dodatkowe

• Jak SKUTECZNIE dokumentować architekturę systemu – EventCatalog
• Event Catalog – The architecture knowledge base for engineering teams
• Oskar Dudycz, David Boyne – Documenting Event-Driven Architecture with EventCatalog and David Boyne
• EventCatalog – docs
• EventCatalog Studio
• Repozytorium Simple Icons
• EventCatalog Docs – Using mermaid
• EventCatalog Docs – MCP Server
• GitHub repository – EventCatalog AI Skills
• Omid Eidivandi – Automating EventCatalog at Scale
• Billy Pilger – 7 More Common Mistakes in Architecture Diagrams

Zaobserwuj mnie w mediach społecznościowych!

LinkedIn jest głównym medium, poza blogiem, gdzie publikuję swoje przemyślenia. Zachęcam też do zaobserwowania devszczepaniak.pl na Facebooku, gdzie oprócz informacji o nowych artykułach publikuję linki do ciekawych treści.

Udostępnij wpis

Szukasz taniego i dobrego VPS? Skorzystaj z Mikrusa i przy zakupie odbierz dodatkowy miesiąc usługi za darmo!

📖 Koniecznie sprawdź ofertę księgarni Helion oferującej tysiące książek dla programistów w dobrych cenach! Kupując z tego linku, pomagasz w rozwoju bloga.

📈 Szukasz księgowości dla swojej JDG? Skorzystaj z mojego polecenia i odbierz pierwszy miesiąc za 1zł netto!

Chcesz docenić moją pracę? Postaw mi kawę!