EA - arc42: Efektywne Dokumentowanie Architektury Systemu

    Tworzenie i zarządzanie dokumentacją architektury oprogramowania bywa wyzwaniem, szczególnie w dużych, złożonych projektach. Brak jasno określonych zasad dokumentacji może prowadzić do nieporozumień, powtarzających się spotkań i problemów komunikacyjnych, co ostatecznie odbija się na jakości projektu. Tutaj na pomoc przychodzi arc42 – framework, który dostarcza struktury do efektywnego dokumentowania architektury systemu, zapewniając łatwą komunikację i zrozumienie między wszystkimi interesariuszami.

W artykule przedstawiamy, jak zastosować arc42, wykorzystując różne narzędzia wspierające kluczowe aspekty dokumentacji architektonicznej, od diagramów po rejestry ryzyk.

Czym jest arc42?

arc42 to framework stworzony specjalnie do dokumentowania architektury systemów. Zapewnia jasną strukturę, obejmującą zarówno wysokopoziomowe przeglądy, jak i szczegóły techniczne, dzięki czemu dokumentacja jest zrozumiała i łatwa do utrzymania. Składa się z 12 głównych sekcji, które opisują różne aspekty systemu, takie jak jego cele, funkcjonalność, komponenty i wymagania niefunkcjonalne.

Struktura arc42

Poniżej przedstawiam szczegółowy opis każdego punktu frameworka arc42 wraz z przykładami narzędzi, które można wykorzystać do ich efektywnego dokumentowania.

1. Wprowadzenie i Cele

Ta sekcja określa ogólne cele systemu i interesariuszy, co jest kluczowe dla zrozumienia, jakiego rodzaju rozwiązanie ma być dostarczone. Używanie OKR-ów (Objectives and Key Results) pozwala na sformułowanie klarownych celów, które są mierzalne i stanowią punkt odniesienia dla projektu.

• Przykład: "Zwiększenie wydajności systemu do obsługi 5000 użytkowników jednocześnie".

2. Ograniczenia

W tej sekcji dokumentowane są wszelkie ograniczenia projektowe, takie jak regulacje, technologie, zasoby i budżet. Precyzyjne określenie ograniczeń projektowych na wczesnym etapie pozwala uniknąć późniejszych komplikacji.

• Przykład: System musi być zgodny z RODO i działać w chmurze AWS.

3. Kontekst i Zakres

Określenie kontekstu i zakresu systemu obejmuje jego integracje z innymi systemami oraz granice. Diagramy C4 świetnie sprawdzają się w wizualizacji kontekstu na różnych poziomach szczegółowości.

• Przykład: Diagram C4 na poziomie kontekstowym przedstawia interakcje między systemem e-commerce, systemem płatności oraz bazą danych użytkowników.

4. Widok Funkcjonalny

Opisuje główne funkcje i przypadki użycia systemu, kluczowe dla jego działania. Drivery architektoniczne pomagają zidentyfikować najważniejsze funkcje, które będą miały wpływ na decyzje architektoniczne.

• Przykład: Wyszukiwanie produktów i proces płatności są kluczowymi driverami architektury systemu e-commerce.

5. Widok Bloków Budowlanych

Ta sekcja przedstawia kluczowe komponenty systemu oraz ich interakcje. Diagramy C4 i PlantUML są idealne do wizualizacji struktury modułowej.

• Przykład: Diagram komponentów pokazuje, jak mikroserwisy w systemie e-commerce komunikują się między sobą.

6. Widok Runtime

Opis działania systemu w czasie rzeczywistym, w różnych scenariuszach, aby zobrazować jego przepływy sterowania. Diagramy sekwencji w PlantUML pomagają pokazać, jak system działa pod obciążeniem.

• Przykład: Diagram sekwencji przedstawiający kroki logowania użytkownika.

7. Widok Wdrożenia

W tej sekcji opisano topologię wdrożenia systemu, czyli jak i gdzie są wdrażane poszczególne komponenty. Diagramy wdrożeniowe w PlantUML oraz rejestr ryzyk mogą przedstawiać potencjalne ryzyka związane z infrastrukturą.

• Przykład: Diagram wdrożenia pokazuje, jak system e-commerce działa na klastrach Kubernetes w AWS, z potencjalnym ryzykiem awarii serwera.

8. Koncepcje Przekrojowe

Koncepcje przekrojowe obejmują mechanizmy, które wpływają na różne części systemu, takie jak bezpieczeństwo i monitorowanie. Konwencje dotyczące np. uwierzytelniania mogą pomóc zachować spójność i bezpieczeństwo.

• Przykład: W systemie e-commerce stosowanie OAuth2 jako mechanizmu uwierzytelniania oraz ELK Stack do monitorowania.

9. Decyzje Projektowe

Zapis kluczowych decyzji projektowych, motywacji oraz rozważanych alternatyw w postaci ADR (Architecture Decision Records) pomaga w śledzeniu, dlaczego pewne rozwiązania zostały wybrane.

• Przykład: Decyzja o zastosowaniu PostgreSQL jako bazy danych, udokumentowana w ADR.

10. Wymagania Jakościowe

Opis wymagań niefunkcjonalnych, takich jak wydajność, dostępność, i ich znaczenie dla systemu. OKR-y oraz rejestr ryzyk mogą wspierać dokumentowanie celów jakościowych i potencjalnych zagrożeń.

• Przykład: Wymóg dostępności na poziomie 99,9% i ryzyko przeciążenia serwera w godzinach szczytu.

11. Ryzyka i Dług Techniczny

W tej sekcji znajduje się lista potencjalnych ryzyk oraz długu technicznego, które mogą wpłynąć na projekt. Rejestr ryzyk służy do dokumentowania zagrożeń i ich wpływu na projekt.

• Przykład: Ryzyko związane z aktualizacją bibliotek zewnętrznych, które może wpłynąć na stabilność systemu.

12. Glosariusz

Sekcja ta definiuje terminologię używaną w dokumentacji, aby uniknąć nieporozumień. Konwencje pomagają utrzymać spójność języka.

• Przykład: Definicja terminów takich jak „koszyk”, „zamówienie” i „płatność”.

Zastosowanie arc42 w Złożonych Projektach

arc42 może być stosowane w projektach o wysokiej dynamice zmian, ponieważ jego struktura jest elastyczna i ułatwia aktualizację dokumentacji w miarę rozwoju projektu. Integracja narzędzi takich jak diagramy C4, PlantUML, ADR i rejestr ryzyk z procesem CI/CD pozwala na automatyczne monitorowanie i dokumentowanie zmian, co jest szczególnie przydatne w dużych projektach o złożonej architekturze.

Podsumowanie

arc42 to potężne narzędzie do dokumentowania architektury systemu, które ułatwia zrozumienie struktury i funkcji systemu wszystkim interesariuszom. Dzięki zastosowaniu różnych narzędzi i technik w każdej sekcji, arc42 zapewnia kompleksowe podejście do dokumentacji, ułatwiając zarządzanie projektami w każdym etapie ich rozwoju.