Projektujesz endpoint zamówień i po chwili masz na ekranie kilka strzałek, trzy usługi oraz bazę danych, ale nadal nie widać, co właściwie dzieje się po kliknięciu „Kupuję”. Do backendu zwykle dobiera się diagram do pytania: C4 pokazuje strukturę systemu, diagram sekwencji przebieg żądania, a model danych relacje w bazie, choć jeden widok rzadko odpowiada na wszystko.

Dobry diagram pokazuje jedną warstwę systemu naraz
- C4 przedstawia system w kilku poziomach szczegółowości, od otoczenia po komponenty.
- Diagram sekwencji pomaga prześledzić kolejność wywołań API, usług i baz danych.
- ERD porządkuje encje oraz relacje w modelu danych.
- Diagram wdrożenia pokazuje, gdzie działają usługi i infrastruktura.
- OpenAPI opisuje kontrakt HTTP, ale nie zastępuje diagramu architektury.
Rodzaje diagramów dobieraj do pytania, nie do narzędzia
Wyobraź sobie, że nowa osoba w zespole pyta, gdzie trafia żądanie z aplikacji i co dzieje się z nim dalej. Diagram architektury powinien odpowiedzieć na to pytanie bez konieczności czytania całego repozytorium. Jeden widok, jeden cel zwykle działa lepiej niż plansza z każdą klasą, tabelą i usługą.
W backendzie spotkasz przede wszystkim diagramy struktury, przepływu i danych. Różnią się tym, co uwypuklają: statyczne połączenia między elementami, kolejność komunikatów albo kształt przechowywanych informacji. Uważam, że właśnie ten wybór, a nie styl graficzny, decyduje, czy ktoś szybko zrozumie diagram.
C4 prowadzi od obrazu systemu do jego elementów
Gdy odbiorcy nie znają jeszcze projektu, zacznij od szerokiego kadru. Diagram kontekstu systemu pokazuje aplikację jako całość, użytkowników i zewnętrzne systemy, z którymi się komunikuje. Przykładowo sklep internetowy może mieć na nim klienta, platformę sklepu, operatora płatności i firmę kurierską, bez rozrysowywania wnętrza backendu.
Poziom kontenerów przybliża obraz i pokazuje główne uruchamialne części, takie jak aplikacja webowa, API, baza danych czy broker wiadomości. Diagram komponentów schodzi jeszcze niżej, do odpowiedzialności wewnątrz wybranego kontenera. Model C4 opisuje te poziomy jako kontekst, kontenery, komponenty i kod, ale podkreśla, że nie trzeba tworzyć wszystkich, jeśli prostszy zestaw wystarcza.
Tu łatwo przesadzić: diagram komponentów szybko staje się nieczytelną mapą klas. Dla typowego przeglądu architektury zacząłbym od kontekstu i kontenerów; niższy poziom dodałbym dopiero wtedy, gdy trzeba wyjaśnić granice modułu lub odpowiedzialność konkretnej usługi.
Diagram sekwencji ujawnia, gdzie zatrzymuje się żądanie
Architektura może wyglądać poprawnie na statycznym obrazku, a mimo to ukrywać problem w kolejności wywołań. Diagram sekwencji rozpisuje uczestników w pionowych liniach życia, a komunikaty umieszcza od góry do dołu. W scenariuszu zakupu widać więc, czy API najpierw weryfikuje koszyk, rezerwuje towar, pobiera płatność, czy może czeka na odpowiedź zewnętrznego dostawcy.
To szczególnie przydatne przy błędach, ponowieniach i operacjach asynchronicznych. Jeśli płatność się powiedzie, ale zapis zamówienia zawiedzie, diagram może pokazać, czy system ma krok kompensujący, ponawia operację, czy pozostawia niespójny stan. Diagram sekwencji należy do notacji UML, ale da się go narysować prostymi symbolami, o ile kierunek i warunki komunikatów pozostają jasne.
Gdy problem brzmi „które elementy są połączone?”, sekwencja może być nadmiarem. Gdy brzmi „co wywołuje co i w jakiej kolejności?”, sam diagram kontenerów nie wystarczy.
ERD i OpenAPI odpowiadają na dwa różne pytania o API
Żądanie może przejść przez usługę bez błędu, a mimo to zapisać dane w nieodpowiedniej strukturze. ERD, czyli diagram encji i relacji, pokazuje obiekty domenowe, ich atrybuty oraz związki. Dla sklepu może przedstawić relację między zamówieniem, pozycją zamówienia i produktem, dzięki czemu łatwiej zauważyć, czy cena produktu jest zapisana jako historyczna wartość zamówienia, czy odczytywana wyłącznie z bieżącego katalogu.
Kontrakt endpointów opisuje inne zagadnienie. Specyfikacja OpenAPI definiuje maszynowo czytelny opis HTTP API, obejmujący między innymi operacje, parametry i odpowiedzi. Nie jest diagramem architektury: mówi, jak klient może wywołać interfejs, a nie jak wewnętrznie rozłożono backend.
W praktyce te materiały mogą się uzupełniać. OpenAPI pozwala sprawdzić kształt żądania i odpowiedzi, diagram sekwencji pokazuje jego drogę przez usługi, a ERD wyjaśnia, jak dane trafiają do modelu. Rozdzielenie tych pytań zapobiega jednemu z częstszych nieporozumień: oczekiwaniu, że dokumentacja endpointu wyjaśni całą architekturę.
Wybór diagramu zależy od tego, co trzeba rozstrzygnąć
Gdy nie wiadomo, od czego zacząć, nazwij konkretną niewiadomą. Czy zespół nie zna granic systemu, myli kolejność wywołań, czy nie rozumie relacji między danymi? Rodzaj diagramu powinien wynikać z odpowiedzi, a nie z tego, który szablon ma otwarty edytor.
| Sytuacja | Co prawdopodobnie jest niejasne | Co narysować |
|---|---|---|
| Nowa osoba nie wie, jakie systemy łączą się z aplikacją | Otoczenie i granice rozwiązania | Diagram kontekstu C4 |
| Zespół nie rozumie, z jakich uruchamialnych części składa się backend | Podział na aplikacje, usługi i magazyny danych | Diagram kontenerów C4 |
| Błąd pojawia się po kilku kolejnych wywołaniach | Kolejność komunikatów, warunki lub obsługa błędu | Diagram sekwencji |
| Trudno ustalić, jak zamówienie łączy się z produktem | Encje, atrybuty i relacje w bazie | ERD |
| Nie wiadomo, gdzie działają usługi w środowisku | Węzły infrastruktury i rozmieszczenie instancji | Diagram wdrożenia |
Na przykład przy incydencie, w którym klient otrzymuje błąd po zatwierdzeniu płatności, zacząłbym od diagramu sekwencji, bo trzeba odtworzyć kolejność operacji i sprawdzić zachowanie po awarii. Jeśli problemem jest natomiast pytanie, czy usługa płatności należy do własnego systemu czy jest zewnętrzną zależnością, lepszy będzie diagram kontekstu. Ten sam przypadek biznesowy może wymagać dwóch diagramów, ale każdy powinien rozstrzygać inną niewiadomą.
Diagram ma pomagać w rozmowie, a nie udawać cały kod
Łatwo dopisać każdą klasę i każdy endpoint, aż zniknie główna myśl. Zostaw szczegóły w kodzie, specyfikacji API lub dokumentacji danych, a na diagramie pokaż elementy potrzebne do konkretnej decyzji. Prawdę mówiąc, diagram, którego nie da się odczytać bez przewijania i lupy, zwykle wymaga podziału na mniejsze widoki.
Przy każdej strzałce dodaj sensowną etykietę, na przykład „wysyła żądanie płatności” zamiast ogólnego „komunikuje się”. Zaznacz granice systemu, odróżnij zależności zewnętrzne i utrzymuj spójne nazwy z kodem oraz kontraktem API. Wtedy diagram backendu staje się mapą, która prowadzi od pytania do właściwego poziomu szczegółu, zamiast kolejnym obrazkiem do aktualizacji.