Aplikacja frontendowa

Interfejs użytkownika platformy DataFlow AI to aplikacja jednostronicowa zbudowana na React 19, Vite 7 i TypeScript 5.9. Prezentuje cały produkt ETL/ELT — projektowanie potoków, monitoring, nadzór, migrację i administrację — poprzez jedną adaptującą się do persony powłokę, która komunikuje się wyłącznie z bramą API pod /api/v1.

Stos technologiczny

SPA znajduje się w frontend/ i jest budowana oraz serwowana niezależnie od usług platformowych JVM. Zestaw zależności jest celowo nowoczesny i skupiony na niewielkiej liczbie dobrze wspieranych bibliotek.

Aplikacja jest serwowana produkcyjnie przez nginx (port hosta 3006) i dociera do backendu wyłącznie poprzez bramę API.

Rozruch aplikacji

Komponent główny App.tsx jest celowo minimalny. Opakowuje <RouterProvider router={router}> w ErrorBoundary react-error-boundary najwyższego poziomu, którego fallbackiem jest ErrorFallback, a którego akcja resetu nawiguje przeglądarkę do /. Przy montowaniu odczytuje theme z useThemeStore i synchronizuje klasę dark na document.documentElement.

App.tsx
 └─ ErrorBoundary (fallback: ErrorFallback, reset → window.location.href = '/')
     └─ RouterProvider (router from router.tsx)
         └─ AppShell  (route '/')
             └─ ProtectedRoute → <Outlet/>  (every in-shell page)

Każda strona jest ładowana przez lazy() i opakowana w pomocnika SuspenseWrap — ErrorBoundary plus Suspense z fallbackiem spinnera — tak aby awaria lub wolny fragment na jednej stronie nigdy nie zepsuł reszty powłoki.

Powłoka aplikacji

components/shell/AppShell.tsx renderuje trwały układ dla każdej trasy wewnątrzaplikacyjnej. Komponuje chrome nawigacyjne, główny outlet treści, AI Copilot oraz kilka globalnych nakładek.

┌──────────────────────────────────────────────────────────────────────┐
│  TopBar   [breadcrumbs]            [search ⌘K] [lang] [notifs] [user]  │
├────────────┬───────────────────────────────────────────────────────────┤
│            │                                                           │
│  Sidebar   │   <main id="main-content">                                │
│            │                                                           │
│  ▸ Home    │     <Outlet/>  — the active page                          │
│  ▸ Design  │                                                           │
│    Studio  │                                                           │
│  ▸ Monitor │                                                           │
│  ▸ Govern. │                                                ┌────────┐ │
│  ▸ Migrate │                                                │  AI    │ │
│  ▸ Data    │                                                │Copilot │ │
│  ▸ Admin   │                                                │Sidebar │ │
│            │                                                │(toggle)│ │
│ [collapse] │                                                └────────┘ │
├────────────┴───────────────────────────────────────────────────────────┤
│  MobileBottomNav  (mobile only)                                         │
└──────────────────────────────────────────────────────────────────────┘

Kompozycja powłoki

• Sidebar (Sidebar.tsx) — nawigacja na desktopie i tablecie; składany między 60px a 240px, z rozwijaniem przy najechaniu na tablecie.
• MobileMenu i MobileBottomNav — nakładki nawigacyjne wyłącznie mobilne.
• TopBar — nagłówek z okruszkami nawigacji, wyzwalaczem wyszukiwania globalnego, przełącznikiem języka, powiadomieniami i stopką użytkownika.
• <main id="main-content"> — responsywne wcięcie, renderuje routowany <Outlet />.
• AICopilotTrigger (pływający przycisk akcji) oraz AICopilotSidebar, pokazywane warunkowo, gdy ustawione jest copilotOpen.
• Modal GlobalSearch — otwierany za pomocą Ctrl/Cmd+K poprzez handler keydown w powłoce; oparty na prawdziwym, rankingowanym endpointcie wyszukiwania.
• OnboardingTour — wyświetlany, dopóki tourCompleted w onboardingStore nie ma wartości true.
• HelpDrawer i CatalogAskPanel — sterowane lokalnym stanem komponentu (helpOpen, askOpen).
• Link pominięcia nawigacji do #main-content dla użytkowników klawiatury i czytników ekranu.

Zachowanie responsywne jest obliczane przez useIsMobile, useIsTablet i useSidebarState z hooks/useResponsive; wartość effectiveMargin przesuwa główną treść, aby dopasować ją do bieżącej szerokości paska bocznego.

ProtectedRoute

components/shell/ProtectedRoute.tsx opakowuje każdy element trasy wewnątrz powłoki i wymusza uwierzytelnianie oraz autoryzację:

1. Podczas isLoading renderuje spinner z etykietą „Sprawdzanie dostępu...".
2. Jeśli użytkownik nie jest uwierzytelniony, renderuje <Navigate to="/login">, przenosząc pierwotną lokalizację from w stanie routera.
3. Oblicza effectivePersona — w trybie deweloperskim z personaStore, w przeciwnym razie z user.persona wyprowadzonej z ról Keycloak.
4. Wywołuje canAccess(persona, pathname) z data/permissions; jeśli dostęp jest odmówiony, renderuje <AccessDenied />.

Każda decyzja jest logowana przez createLogger('auth.protected-route').

Mapa tras

Routing jest zdefiniowany w frontend/src/router.tsx przy użyciu createBrowserRouter. Trasy dzielą się na dwie grupy: niewielki zestaw renderowany poza powłoką (bez chrome) oraz większość renderowana wewnątrz AppShell i opakowana w ProtectedRoute.

Trasy poza powłoką

Główne trasy wewnątrz powłoki

Monitor — /monitor (MonitorLayout, zagnieżdżony)

Migracja — /migration (MigrationLayout, zagnieżdżony)

Nadzór — /governance (GovernanceHub, zagnieżdżony)

Administracja — /admin (AdminConsole, zagnieżdżony)

Trasa wychwytująca wszystko /* renderuje <Navigate to="/" replace />.

Architektura komponentów

Komponenty są zorganizowane według obszaru funkcjonalnego pod frontend/src/components/.

Zestaw ui/ zawiera około czterdzieści prymitywów prezentacyjnych — kontrolki formularzy, tabele, pomoce nawigacyjne, wykresy (LineChart, BarChart, GaugeChart), pomocniki układu (Stack, ResponsiveGrid, Divider) oraz pomocniki dostępności, takie jak SkipNav i PermissionGate.

Zarządzanie stanem

Magazyny Zustand

Stan klienta znajduje się w dwunastu magazynach Zustand pod frontend/src/stores/. Wszystkie są tworzone przez create(); cztery opakowują middleware persist, aby utrwalić swój stan w localStorage pod kluczami dataflow-*.

Stan serwera

Dane serwera są zarządzane za pomocą TanStack React Query 5 poprzez generyczny hook useApiQuery oraz per-funkcjonalne hooki danych, takie jak usePipelineData, useCatalogData, useMonitorData, useGovernanceData i useAdminData. React Query obsługuje buforowanie, deduplikację i rewalidację; Axios wykonuje transport leżący u podstaw.

Warstwa klienta API

Klient bazowy

Klient bazowy to instancja Axios w api/client.ts. Jego baseURL to VITE_API_URL ?? '/api/v1', jego timeout to VITE_API_TIMEOUT ?? 30s, a withCredentials jest celowo ustawione na false — ustawienie go na true zatrzymywało fragmentowane odpowiedzi bramy.

Klient implementuje kilka zachowań przekrojowych:

• Wstrzykiwanie akcesora tokena. registerTokenAccessor(fn) jest wywoływane raz przez AuthProvider, unikając cyklicznego importu singletona Keycloak.
• Bramka gotowości uwierzytelniania. signalAuthReady() rozwiązuje obietnicę po zakończeniu Keycloak.init(). Interceptor żądań await-uje ją — ścigając się z AbortSignal żądania oraz 5-sekundowym timeoutem bezpieczeństwa — tak aby pierwsze wywołania /api/v1/* zawsze niosły JWT i nie zwracały 401.
• Interceptor żądań. Dołącza Authorization: Bearer <token>; przy POST/PUT/PATCH/DELETE dodaje X-CSRF-Token, odczytywany ze znacznika <meta name="csrf-token"> lub ciasteczka XSRF-TOKEN; emituje logowanie deweloperskie.
• Interceptor odpowiedzi. Przy 401 odświeża token raz — chroniony nagłówkiem x-retry-after-refresh — i ponawia żądanie. Rekurencyjnie konwertuje klucze snake_case na camelCase (Jackson backendu dostarcza SNAKE_CASE) i normalizuje każdy błąd do ApiError niosącego status, code i errors, z pomocniczymi getterami isUnauthorized, isForbidden, isNotFound i isValidation.

Na górze znajdują się wygodne opakowania apiGet, apiPost, apiPut, apiPatch i apiDelete.

Moduły domenowe API

Około pięćdziesiąt per-funkcjonalnych typowanych opakowań znajduje się pod api/ — na przykład pipelines, pipelineTemplates, connections, cdc, cdr, catalog, copilot, governance, lineage, quality, monitoring, metrics, migration, dataProducts, masking, gdpr, auditLog, admin i search. api/index.ts to barel re-eksportu.

Transport czasu rzeczywistego

Folder services/ zawiera sse.ts / SSEManager.ts dla Server-Sent Events (alerty na żywo, metryki, strumieniowanie copilota), websocket.ts / WebSocketManager.ts dla transportu WebSocket oraz pipelineValidator.ts dla walidacji potoków po stronie klienta. Dane czasu rzeczywistego są konsumowane przez hooki takie jak useAlertStream, useMetricsStream, useCopilotStream, usePipelineStream i useMonitorWebSocket.

Uwierzytelnianie

Konfiguracja Keycloak

auth/keycloak.ts przechowuje singleton keycloakInstance skonfigurowany z VITE_KEYCLOAK_URL (domyślnie http://localhost:8180), VITE_KEYCLOAK_REALM (dataflow) i VITE_KEYCLOAK_CLIENT_ID (dataflow-app). Instancja jest udostępniana na window.__keycloak dla diagnostyki Playwright. Opcje inicjalizacji to onLoad: 'check-sso', pkceMethod: 'S256', silentCheckSsoRedirectUri wskazujący na /silent-check-sso.html oraz checkLoginIframe: false.

ROLE_PERSONA_MAP akceptuje zarówno natywne dla Keycloak nazwy ról (org_admin, workspace_admin, developer, operator, data_steward, analyst), jak i uprawnienia Spring ROLE_*, mapując je — uszeregowane priorytetowo, z domyślnym analyst — na cztery persony: admin, steward, engineer i analyst. Kluczowe stałe to TOKEN_REFRESH_BUFFER_SECONDS = 30, SESSION_TIMEOUT_WARNING_SECONDS = 60 oraz MIN_TOKEN_VALIDITY_SECONDS = 60.

Przepływ uwierzytelniania

auth/AuthProvider.tsx dostarcza kontekst React, konsumowany przez useAuth(), udostępniający isAuthenticated, isLoading, isDevMode, user, token, personas, login(), logout(), hasRole() i hasPermission().

 mount AuthProvider
   │
   ├─ register token accessor with api/client
   │
   ├─ keycloakInstance.init()  ──── Promise.race ──── 15s timeout
   │        │                                            │
   │     success                                      failure
   │        │                                            │
   │   build KeycloakUserProfile                  allowDevModeFallback?
   │   from tokenParsed:                           ┌──────┴───────┐
   │   realm_access.roles, names,                 yes            no
   │   email, workspace_id                         │              │
   │        │                                  dev mode      unauthenticated
   │   derive persona + permissions            (personaStore +
   │        │                                   buildDevProfile)
   │   schedule silent refresh (30s pre-expiry)
   │   schedule session warning (60s pre-expiry)
   │        │
   └────────┴──► signalAuthReady()  → unblocks the API interceptor

1. Przy montowaniu AuthProvider rejestruje akcesor tokena w api/client i uruchamia keycloakInstance.init() pod 15-sekundowym timeoutem Promise.race.
2. Przy powodzeniu buduje KeycloakUserProfile z tokenParsed — realm_access.roles, given_name/family_name, email, workspace_id — i wyprowadza personę plus personaPermissions.
3. Planuje ciche odświeżenie tokena poprzez updateToken 30 sekund przed wygaśnięciem oraz ostrzeżenie o przekroczeniu czasu sesji 60 sekund przed wygaśnięciem, które otwiera SessionTimeoutModal.
4. Przy niepowodzeniu inicjalizacji, jeśli allowDevModeFallback ma wartość true, wchodzi w tryb deweloperski, używając personaStore i buildDevProfile; w przeciwnym razie pozostaje nieuwierzytelniony.
5. Zawsze wywołuje signalAuthReady() po inicjalizacji, niezależnie od wyniku, co odblokowuje interceptor żądań API.
6. login() przekierowuje do Keycloak (domyślne przekierowanie /); logout() czyści timery i stan oraz przekierowuje do /login.

Uwierzytelnianie deweloperskie

auth/devAuth.ts definiuje cztery zakodowane na stałe persony deweloperskie — Jan Kowalski (engineer), Anna Nowak (analyst), Piotr Wiśniewski (admin) i Maria Kamińska (steward), wszystkie w domenie @polkomtel.pl. Testy end-to-end Playwright używają obejścia VITE_AUTH_MODE=dev. SessionTimeoutModal jest pokazywany tylko w rzeczywistym, niedeweloperskim trybie.

Internacjonalizacja

i18n/index.ts podpina i18next z react-i18next oraz i18next-browser-languagedetector.

• Języki: en i pl — angielski i polski. supportedLanguages = ['en','pl'] z fallbackLng: 'en'.
• Osiem przestrzeni nazw: common, admin, governance, pipeline, monitor, migration, catalog i copilot. Zasoby JSON są dołączane per język pod i18n/locales/{en,pl}/.
• Kolejność wykrywania: localStorage (klucz dataflow-language), następnie navigator; wybrany język jest buforowany z powrotem do localStorage.
• react.useSuspense ma wartość false; returnNull i returnEmptyString mają obie wartość false.
• Tłumaczenia są dostępne przez hook useT, a powłoka udostępnia komponent LanguageSwitcher.

Model nawigacji paska bocznego w data/navigation.ts kluczuje swoje etykiety przez navI18nKeys pod prefiksem nav.*, dzięki czemu całe drzewo nawigacji jest tłumaczalne.

Motywy i tokeny projektowe

Motywy są sterowane przez themeStore z domyślnym ustawieniem dark. Magazyn przełącza klasę dark na <html>, a Tailwind CSS 4 rozwiązuje semantyczne tokeny projektowe względem tej klasy. Komponenty odwołują się do klas tokenów, a nie surowych kolorów — bg-surface-0/1/2, text-heading/body/secondary/muted, border-primary — z amber-500 jako akcentem marki.

Formularze używają react-hook-form z resolverami zod poprzez hook useFormWithSchema. Błędy są wychwytywane na trzech poziomach: globalny react-error-boundary w App.tsx, per-trasowy ErrorBoundary wewnątrz SuspenseWrap oraz PanelErrorFallback dla awarii ograniczonych do panelu. Każda strona jest ładowana przez lazy() z fallbackiem spinnera Suspense dla podziału kodu.