Frontend application

The DataFlow AI Platform user interface is a single-page application built on React 19, Vite 7 and TypeScript 5.9. It presents the entire ETL/ELT product — pipeline design, monitoring, governance, migration and administration — through one persona-adaptive shell that talks exclusively to the API gateway under /api/v1.

Tech stack

The SPA lives in frontend/ and is built and served independently from the JVM platform services. The dependency set is deliberately modern and centred on a small number of well-supported libraries.

The application is served in production by nginx (host port 3006) and reaches the backend exclusively through the API gateway.

App bootstrap

The root component App.tsx is intentionally minimal. It wraps <RouterProvider router={router}> in a top-level react-error-boundary ErrorBoundary whose fallback is ErrorFallback and whose reset action navigates the browser to /. On mount it reads theme from useThemeStore and synchronises the dark class on document.documentElement.

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

Each page is lazy()-loaded and wrapped in a SuspenseWrap helper — an ErrorBoundary plus a Suspense with a spinner fallback — so a failure or slow chunk in one page never breaks the rest of the shell.

The app shell

components/shell/AppShell.tsx renders the persistent layout for every in-app route. It composes navigation chrome, the main content outlet, the AI Copilot, and several global overlays.

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

Shell composition

• Sidebar (Sidebar.tsx) — desktop and tablet navigation; collapsible between 60px and 240px, with hover-expand on tablet.
• MobileMenu and MobileBottomNav — mobile-only navigation overlays.
• TopBar — header with breadcrumbs, global search trigger, language switcher, notifications and the user footer.
• <main id="main-content"> — responsive padding, renders the routed <Outlet />.
• AICopilotTrigger (a floating action button) and AICopilotSidebar, shown conditionally when copilotOpen is set.
• GlobalSearch modal — opened with Ctrl/Cmd+K via a keydown handler in the shell; backed by a real ranked search endpoint.
• OnboardingTour — displayed until tourCompleted is true in onboardingStore.
• HelpDrawer and CatalogAskPanel — driven by local component state (helpOpen, askOpen).
• A skip-navigation link to #main-content for keyboard and screen-reader users.

Responsive behaviour is computed by useIsMobile, useIsTablet and useSidebarState from hooks/useResponsive; an effectiveMargin value offsets the main content to match the current sidebar width.

ProtectedRoute

components/shell/ProtectedRoute.tsx wraps every in-shell route element and enforces authentication and authorization:

1. While isLoading, it renders a spinner labelled "Checking access...".
2. If the user is not authenticated, it renders <Navigate to="/login">, carrying the originating from location in router state.
3. It computes an effectivePersona — in dev mode from personaStore, otherwise from user.persona derived from Keycloak roles.
4. It calls canAccess(persona, pathname) from data/permissions; if access is denied it renders <AccessDenied />.

Every decision is logged through createLogger('auth.protected-route').

Route map

Routing is defined in frontend/src/router.tsx using createBrowserRouter. Routes split into two groups: a small set rendered outside the shell (no chrome), and the bulk rendered inside AppShell and wrapped in ProtectedRoute.

Routes outside the shell

Core in-shell routes

Monitor — /monitor (MonitorLayout, nested)

Migration — /migration (MigrationLayout, nested)

Governance — /governance (GovernanceHub, nested)

Admin — /admin (AdminConsole, nested)

The catch-all route /* renders <Navigate to="/" replace />.

Component architecture

Components are organised by feature area under frontend/src/components/.

The ui/ kit holds about forty presentation primitives — form controls, tables, navigation aids, charts (LineChart, BarChart, GaugeChart), layout helpers (Stack, ResponsiveGrid, Divider) and accessibility helpers such as SkipNav and PermissionGate.

State management

Zustand stores

Client state lives in twelve Zustand stores under frontend/src/stores/. All are created with create(); four wrap the persist middleware to back their state with localStorage under dataflow-* keys.

Server state

Server data is managed with TanStack React Query 5 through a generic useApiQuery hook and per-feature data hooks such as usePipelineData, useCatalogData, useMonitorData, useGovernanceData and useAdminData. React Query handles caching, deduplication and revalidation; Axios performs the underlying transport.

API client layer

Base client

The base client is an Axios instance in api/client.ts. Its baseURL is VITE_API_URL ?? '/api/v1', its timeout is VITE_API_TIMEOUT ?? 30s, and withCredentials is deliberately false — setting it true stalled chunked gateway responses.

The client implements several cross-cutting behaviours:

• Token accessor injection. registerTokenAccessor(fn) is called once by AuthProvider, avoiding a circular import of the Keycloak singleton.
• Auth-readiness gate. signalAuthReady() resolves a promise once Keycloak.init() completes. The request interceptor awaits it — racing against the request AbortSignal and a 5-second safety timeout — so the first /api/v1/* calls always carry a JWT and do not 401.
• Request interceptor. Attaches Authorization: Bearer <token>; on POST/PUT/PATCH/DELETE it adds X-CSRF-Token, read from a <meta name="csrf-token"> tag or the XSRF-TOKEN cookie; emits dev logging.
• Response interceptor. On a 401 it refreshes the token once — guarded by an x-retry-after-refresh header — and retries the request. It recursively converts snake_case keys to camelCase (the backend's Jackson ships SNAKE_CASE) and normalizes every error into an ApiError carrying status, code and errors, with helper getters isUnauthorized, isForbidden, isNotFound and isValidation.

Convenience wrappers apiGet, apiPost, apiPut, apiPatch and apiDelete sit on top.

Domain API modules

Roughly fifty per-feature typed wrappers live under api/ — for example pipelines, pipelineTemplates, connections, cdc, cdr, catalog, copilot, governance, lineage, quality, monitoring, metrics, migration, dataProducts, masking, gdpr, auditLog, admin and search. api/index.ts is the barrel re-export.

Real-time transport

The services/ folder holds sse.ts / SSEManager.ts for Server-Sent Events (live alerts, metrics, copilot streaming), websocket.ts / WebSocketManager.ts for WebSocket transport, and pipelineValidator.ts for client-side pipeline validation. Real-time data is consumed through hooks such as useAlertStream, useMetricsStream, useCopilotStream, usePipelineStream and useMonitorWebSocket.

Authentication

Keycloak configuration

auth/keycloak.ts holds a singleton keycloakInstance configured from VITE_KEYCLOAK_URL (default http://localhost:8180), VITE_KEYCLOAK_REALM (dataflow) and VITE_KEYCLOAK_CLIENT_ID (dataflow-app). The instance is exposed on window.__keycloak for Playwright diagnostics. Init options are onLoad: 'check-sso', pkceMethod: 'S256', a silentCheckSsoRedirectUri pointing at /silent-check-sso.html, and checkLoginIframe: false.

A ROLE_PERSONA_MAP accepts both Keycloak-native role names (org_admin, workspace_admin, developer, operator, data_steward, analyst) and Spring ROLE_* authorities, mapping them — priority-ordered, defaulting to analyst — onto four personas: admin, steward, engineer and analyst. Key constants are TOKEN_REFRESH_BUFFER_SECONDS = 30, SESSION_TIMEOUT_WARNING_SECONDS = 60 and MIN_TOKEN_VALIDITY_SECONDS = 60.

Auth flow

auth/AuthProvider.tsx provides a React context, consumed via useAuth(), exposing isAuthenticated, isLoading, isDevMode, user, token, personas, login(), logout(), hasRole() and 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. On mount, AuthProvider registers the token accessor with api/client and runs keycloakInstance.init() under a 15-second Promise.race timeout.
2. On success it builds a KeycloakUserProfile from tokenParsed — realm_access.roles, given_name/family_name, email, workspace_id — and derives a persona plus personaPermissions.
3. It schedules a silent token refresh via updateToken 30 seconds before expiry, and a session-timeout warning 60 seconds before expiry that opens SessionTimeoutModal.
4. On init failure, if allowDevModeFallback is true it enters dev mode using personaStore and buildDevProfile; otherwise it stays unauthenticated.
5. It always calls signalAuthReady() after init, regardless of outcome, which unblocks the API request interceptor.
6. login() redirects to Keycloak (default redirect /); logout() clears timers and state and redirects to /login.

Dev authentication

auth/devAuth.ts defines four hard-coded dev personas — Jan Kowalski (engineer), Anna Nowak (analyst), Piotr Wiśniewski (admin) and Maria Kamińska (steward), all on @polkomtel.pl. Playwright end-to-end tests use a VITE_AUTH_MODE=dev bypass. SessionTimeoutModal is only shown in real, non-dev mode.

Internationalization

i18n/index.ts wires i18next with react-i18next and i18next-browser-languagedetector.

• Languages: en and pl — English and Polish. supportedLanguages = ['en','pl'] with fallbackLng: 'en'.
• Eight namespaces: common, admin, governance, pipeline, monitor, migration, catalog and copilot. JSON resources are bundled per language under i18n/locales/{en,pl}/.
• Detection order: localStorage (key dataflow-language) then navigator; the chosen language is cached back to localStorage.
• react.useSuspense is false; returnNull and returnEmptyString are both false.
• Translations are accessed through the useT hook, and the shell exposes a LanguageSwitcher component.

The sidebar navigation model in data/navigation.ts keys its labels through navI18nKeys under the nav.* prefix, so the entire navigation tree is translatable.

Theming and design tokens

Theming is driven by themeStore with a default of dark. The store toggles the dark class on <html>, and Tailwind CSS 4 resolves semantic design tokens against that class. Components reference token classes rather than raw colours — bg-surface-0/1/2, text-heading/body/secondary/muted, border-primary — with amber-500 as the brand accent.

Forms use react-hook-form with zod resolvers via the useFormWithSchema hook. Errors are caught at three levels: a global react-error-boundary in App.tsx, a per-route ErrorBoundary inside SuspenseWrap, and a PanelErrorFallback for panel-scoped failures. Every page is lazy()-loaded with a Suspense spinner fallback for code splitting.