#
Rejestr Decyzji Architektonicznych (ADR)
Projekt: Aplikacja do planowania podróży II — PoDrodze Autorzy: Kateryna Lytvyn, Mykyta Klymenko, Sebastian Wróblewski, Kyrylo Riabchenko Data utworzenia rejestru: listopad 2025
#
Spis treści
- ADR-001 – Architektura aplikacji i środowisko uruchomieniowe
- ADR-002 – Styl komunikacji frontend–backend
- ADR-003 – System rejestracji i logowania użytkowników
- ADR-004 – Preferencje użytkowników i generowanie tras
- ADR-005 – CI/CD i środowisko wdrożeniowe
- ADR-006 – Dokumentacja i testy API
- ADR-007 – Obsługa poczty e-mail
- ADR-008 – Hosting frontendu (GitHub Pages)
- ADR-009 – Zmiana narzędzia dokumentacji API na Swagger / OpenAPI
#
ADR-001: Wybór architektury aplikacji i środowiska uruchomieniowego
- Status: zaakceptowano
- Data: 2025-11
#
1. Kontekst
Celem projektu jest stworzenie skalowalnej aplikacji webowej do planowania podróży grupowych. System musi działać jednolicie na każdym komputerze, być wdrażalny w chmurze oraz umożliwiać przyszłą rozbudowę.
#
2. Decyzja
Wybrano architekturę dwuwarstwową (backend + frontend), w pełni konteneryzowaną za pomocą Docker.
Technologie:
- Backend: Laravel 12 (PHP 8.3-FPM)
- Frontend: Vue 3 (Vite)
- Reverse proxy: Caddy 2.10
- Baza danych: PostgreSQL 18 + PostGIS
- Cache / kolejki: Redis 8
- Orkiestracja: Docker Compose
#
3. Uzasadnienie
- Laravel zapewnia szybkie tworzenie API,
- Vue 3 dobrze współpracuje z backendem,
- PostGIS jest niezbędny dla funkcji geolokalizacyjnych,
- Redis przyspiesza cache i obsługę kolejek,
- Docker zapewnia przewidywalność i przenośność środowiska.
#
4. Alternatywy
- Nginx + Certbot
- MySQL (brak PostGIS)
- React (bardziej rozbudowana konfiguracja)
#
ADR-002: Styl komunikacji pomiędzy frontendem i backendem
- Status: zaakceptowano
- Data: 2025-11
#
1. Kontekst
Frontend i backend są w osobnych kontenerach i muszą wymieniać dane za pomocą ustandaryzowanego protokołu.
#
2. Decyzja
Zastosowano REST API oparte na Laravel Sanctum.
#
3. Uzasadnienie
REST jest prosty, czytelny, wspierany przez narzędzia frontendowe oraz łatwy do testowania w Postmanie.
#
4. Alternatywy
GraphQL – odrzucono jako zbyt rozbudowane na obecnym etapie projektu.
#
ADR-003: System rejestracji i logowania użytkowników
- Status: zaakceptowano
- Data: 2025-11
#
1. Decyzja
Zastosowano Laravel Breeze API (Sanctum) do logowania klasycznego oraz rozbudowy o Facebook OAuth.
#
2. Uzasadnienie
Breeze wprowadza gotowe, bezpieczne endpointy, pozwala łatwo dodawać OAuth i integruje się z tokenami API.
#
ADR-004: Preferencje użytkowników i generowanie tras
- Status: zaakceptowano
- Data: 2025-11
#
1. Kontekst
System musi generować trasy dopasowane do preferencji użytkowników i ich głosów.
#
2. Decyzja
- Model UserPreference (oceny kategorii 0/1/2).
- Dane o miejscach z Google Places, zapisywane w PostGIS.
- Głosy użytkowników i miejsca oznaczane jako „stałe”.
- Redis używany jako cache i do redukcji zapytań.
#
3. Uzasadnienie
Połączenie Google Places + PostGIS umożliwia szybkie i precyzyjne obliczenia geolokalizacyjne.
#
ADR-005: CI/CD i środowisko wdrożeniowe
- Status: zaakceptowano
- Data: 2025-11
#
1. Kontekst
Projekt musi być stale testowany i automatycznie wdrażany.
#
2. Decyzja
Zastosowano GitHub Actions do budowy kontenerów, testów i deploymentu na Azure Web Apps (containers).
#
3. Uzasadnienie
- GitHub Actions — tani i prosty CI,
- Azure — szybkie deploymenty i wsparcie dla kontenerów.
#
ADR-006: Dokumentacja i testy API
- Status: zaakceptowano
- Data: 2025-11
#
1. Decyzja
Wybrano Knuckles/Scribe jako narzędzie dokumentacji API.
#
2. Uzasadnienie
- Automatycznie generuje dokumentację z kontrolerów,
- Eksport do HTML i kolekcji Postman,
- Minimalna konfiguracja — idealne dla dynamicznego API.
#
3. Alternatywy
- Swagger / OpenAPI — bardziej rozbudowane i wymagające dodatkowych plików.
- Ręczna dokumentacja — zbyt podatna na błędy.
#
ADR-007: Obsługa poczty e-mail
- Status: zaakceptowano
- Data: 2025-11
#
1. Decyzja
- Środowisko dev: Mailpit (lokalny SMTP + GUI),
- Środowisko prod: zewnętrzny provider (np. SendGrid).
#
2. Uzasadnienie
Mailpit umożliwia testowanie maili bez faktycznej wysyłki.
#
ADR-008: Hosting frontendu (GitHub Pages)
- Status: zaakceptowano
- Data: 2025-11
#
1. Kontekst
Frontend (Vue 3) jest generowany statycznie i nie wymaga serwera.
#
2. Decyzja
Hosting frontendu na GitHub Pages, z automatycznym deploymentem przez GitHub Actions.
#
3. Uzasadnienie
- Darmowy hosting,
- Bardzo łatwa konfiguracja,
- Szybkie deploymenty,
- Idealne dla SPA połączonych z backendem API.
#
ADR-009: Zmiana narzędzia dokumentacji API na Swagger / OpenAPI
- Status: zaakceptowano
- Data: 2025-12
#
1. Kontekst
W projekcie pierwotnie zastosowano narzędzie Knuckles/Scribe do automatycznego generowania dokumentacji API. W miarę rozwoju backendu pojawiła się potrzeba korzystania ze standardowego, kontraktowego formatu OpenAPI, który lepiej wspiera:
- precyzyjne definiowanie struktur odpowiedzi i modeli,
- generowanie klientów frontendowych,
- integrację z narzędziami CI/CD,
- automatyczną walidację specyfikacji.
Scribe nie zapewniał pełnej zgodności ze standardem OpenAPI oraz wymagał dodatkowych obejść dla bardziej złożonych odpowiedzi.
#
2. Decyzja
Zdecydowano o zastąpieniu Scribe narzędziem Swagger / OpenAPI 3, z dokumentacją generowaną poprzez adnotacje PHP.
Swagger staje się jedynym obowiązującym źródłem dokumentacji dla backendu.
#
3. Uzasadnienie
- Adnotacje OpenAPI pozwalają na jasne opisanie modeli i struktur danych używanych w API.
- Dokumentacja w formacie OpenAPI może być automatycznie walidowana w CI/CD.
- Swagger UI umożliwia testowanie endpointów bezpośrednio z poziomu przeglądarki.
- Lepsza skalowalność w miarę rozbudowy systemu.
#
4. Alternatywy
- Pozostanie przy Scribe — odrzucono ze względu na ograniczoną zgodność z OpenAPI i mniej precyzyjną kontrolę nad specyfikacją.
- Ręczne utrzymywanie dokumentacji — odrzucono jako podatne na błędy i trudne w utrzymaniu.
#
5. Konsekwencje
Pozytywne:
- dokumentacja jest zgodna ze standardem OpenAPI 3,
- ujednolicony format komunikacji z frontendem,
- możliwość automatycznego generowania klientów API,
Negatywne:
- konieczność przepisania istniejących opisów do adnotacji Swagger,
- dodatkowy czas na wdrożenie początkowej konfiguracji dokumentacji.