Architektura, kod i deploy pokazane jak produkt

ExKSeF jest aplikacją, w której widoczny ekran jest tylko końcówką większego procesu. Lista faktur, płatności albo harmonogram nie działa samodzielnie: za nimi stoją use case'y, porty integracyjne, reguły domenowe, repozytoria, joby i wdrożenie utrzymujące web oraz procesy w tle w tej samej konfiguracji.

Strona techniczna jest potrzebna, bo pokazuje nie tylko co robi produkt, ale jak został zbudowany. Dla potencjalnego pracodawcy to ważniejsze niż kolejna lista funkcji: widać tu separację odpowiedzialności, odporność na rozjazd konfiguracji, świadome bramki bezpieczeństwa, automatyzację deployu i miejsca, gdzie testy zamrażają reguły architektury.

Zakres techniczny pokazany na stronie

• Warstwy aplikacji - domena i use case'y w Application, persistence i adaptery poza logiką biznesową, hosty Web/Scheduler jako wejścia do systemu.

• Integracje - KSeF, KSeF Lighthouse, VAT Whitelist, CEIDG, KRS, Pekao Connect, PDF service, e-mail, SMS i push podłączone przez kontrakty albo dedykowane adaptery.

• Procesy runtime - web obsługuje UI i API dla mobile, scheduler wykonuje joby, PDF service renderuje dokumenty jako osobny proces Node.

• Deploy - Gitea Actions liczy wersję, buduje trzy obrazy, publikuje je do rejestru i wdraża instancje na podstawie osobnych sekretów środowiskowych.

Repozytorium jest podzielone według odpowiedzialności, a nie według przypadkowych folderów. Solution zawiera projekty Application, Client, Infrastructure, Adapters, Scheduler, Mocks oraz testy jednostkowe i integracyjne. Ten podział jest widoczny w kodzie i potwierdzony testami architektonicznymi.

Application

To miejsce dla domeny, kontraktów i use case'ów. W tej warstwie mieszczą się reguły płatności, faktur, kontrahentów, ról, schedulerów i integracji rozumianych jako porty. Application nie powinien wiedzieć, czy wywołanie przyszło z Blazora, mobile API, schedulera czy testu.

Infrastructure i Adapters

Persistence odpowiada za EF Core, migracje, repozytoria, eksporty i wspólny dostęp do bazy. Adaptery realizują komunikację z zewnętrznymi systemami: KSeF, KSeF Lighthouse, VAT Whitelist, CEIDG, KRS, Banking i Pekao Connect. Dzięki temu reguły biznesowe mogą operować na kontraktach zamiast na szczegółach transportu.

Hosty

Web host składa UI, autoryzację, endpointy API dla Fluttera, antiforgery dla UI, rate limiting logowania, nagłówki bezpieczeństwa, forwarded headers pod reverse proxy i rejestrację use case'ów. Scheduler host składa te same rdzenie persistence, KSeF, XML, VAT, banking i Pekao Connect, ale uruchamia je przez joby oraz własny kontekst systemowego użytkownika.

Testy architektoniczne

Projekt ma osobny pakiet testów architektonicznych oparty o NetArchTest. Pilnuje on, żeby domena nie zależała od EF Core, Infrastructure ani ASP.NET Core, a Application nie zależał od ASP.NET Core, EF Core ani SDK klienta KSeF. To konkretna ochrona przed przypadkowym rozmyciem warstw podczas kolejnych zmian.

Workflow Gitea `Deploy exksef` startuje po pushu do gałęzi `main`. Najpierw liczy wersję z pliku `VERSION`, liczby commitów i krótkiego SHA, a potem buduje trzy obrazy: web, scheduler i pdf. Każdy obraz dostaje tag wersji, SHA oraz `latest`, po czym trafia do `registry.darweb.eu`.

Wdrożenie nie polega na kopiowaniu lokalnej aplikacji na serwer. Pipeline przygotowuje katalog instancji w `/opt`, zapisuje plik Firebase service account z sekretu, ustawia katalogi `data`, `logs` i `keys` pod UID 1654, kopiuje `docker-compose.deploy.yml`, tworzy `.env` z odpowiedniego sekretu instancji i dopisuje `IMAGE_TAG` oraz `APP_VERSION`.

Wiele instancji z tego samego artefaktu

Ten sam zestaw obrazów jest wdrażany do kilku środowisk: `fuz`, `auravita`, `demo`, `matea` i `duet`. Różni je konfiguracja w sekretach, katalog danych, certyfikaty i nazwa projektu compose. To ważny element architektury, bo produkt może obsługiwać różne firmy bez utrzymywania osobnych gałęzi albo ręcznie zmienianych paczek.

Kontener runtime

Compose produkcyjny uruchamia trzy kontenery: `web`, `scheduler` i `pdf`. Web i scheduler współdzielą wolumeny danych, logów, kluczy Data Protection oraz certyfikatów Pekao Connect w trybie read-only. Oba procesy mają ustawione `TZ`, `APP_VERSION`, konfigurację integracji i endpoint serwisu PDF. PDF service działa jako osobny kontener Node i jest widoczny dla weba oraz schedulera po nazwie compose.

Technicznie projekt jest prowadzony tak, żeby zmiana funkcjonalna przechodziła przez kilka poziomów kontroli: zrozumienie procesu biznesowego, zmiana use case'u lub domeny, podłączenie do web/mobile/schedulera, aktualizacja uprawnień oraz testy tam, gdzie ryzyko jest największe.

Typowy przebieg zmiany

1. Reguła domenowa - najpierw trzeba ustalić, czy zmiana dotyczy statusu faktury, płatności, kontrahenta, uprawnienia, schedulera czy integracji.

2. Use case - operacja trafia do Application, żeby dało się ją wywołać z weba, API mobile albo joba bez kopiowania logiki.

3. Adapter albo persistence - jeśli zmiana dotyka bazy, KSeF, banku, PDF lub zewnętrznego słownika, implementacja zostaje po stronie infrastruktury.

4. UI i API - web i mobile pokazują tylko dostępne akcje, a API nadal broni dostępu i spójności danych.

5. Testy - testy jednostkowe sprawdzają reguły, integracyjne pilnują trudnych przepływów Pekao Connect, a architektoniczne bronią kierunku zależności.

6. Deploy - po merge/push na `main` Gitea buduje obrazy i odtwarza instancje z wersją zapisaną w konfiguracji runtime.

Dlaczego to dobrze wygląda w prezentacji

Ta część portalu nie musi opowiadać o każdym pliku. Wystarczy pokazać, że projekt ma realne granice odpowiedzialności, automatyzację wydania, wiele procesów runtime, wieloinstancyjność oraz testy zabezpieczające najważniejsze decyzje. To są elementy, które odróżniają dojrzałą aplikację biznesową od prototypu.