Web app

The browser interface of the lake: React 19 built with Vite. Login is through Keycloak (keycloak-js, authorization code with PKCE). All data comes from the API.

Pages per role

Role	Menu
Admin	Vendors, Analysts, Views, API keys, SQL, Activity, Push API guide, Audit log, System status
Vendor	My projects, API keys (push keys), Activity, API guide
Analyst	My data, SQL, Views, API keys, Notebooks (a link)

Addresses

The address bar is the source of truth, so Back, Reload and a pasted link land in the same place. Plain paths are used (not #), because Keycloak answers in the URL fragment.

Role	Examples
Admin	/vendors, /vendors/3, /vendors/3/logins, /vendors/3/push, /vendors/3/projects/5/folders/9, /analysts/<id>, /views/<id>, /keys, /sql, /activity, /guide, /audit?source=files, /status
Vendor	/projects, /projects/5/folders/9, /projects/5/folders/9/automate, /push, /activity
Analyst	/data, /sql, /views, /keys

/ or an unknown or not-allowed address redirects to the role’s first page. A production web server must send index.html for unknown paths (the Vite dev server already does).

Run it locally

Start the API first, then:

cd apps/web
npm install
npm run dev          # http://localhost:5173

Open http://localhost:5173. The port is fixed (strictPort) and the host must be localhost, not 127.0.0.1, because Keycloak only accepts logins that return to localhost:5173. Vite forwards /api to http://127.0.0.1:4000.

Build static files for a server: npm run build (output in dist/, not committed).

Test it

cd apps/web
npm test

Node’s built-in test runner on the pure logic: addresses, SQL auto-complete schema, push snippets, the Activity model.

Three rules for every page

1. Everything you can navigate to is in the address. Page, open vendor/project/folder/view, tab, filters and page cursor. A new page or state adds its path to src/routes.js with a test.
2. Lists that record history grow without limit. They use server-side keyset paging, filters, thin one-line rows and a hard server cap (see the Audit and Activity pages). Only small bounded sets (vendors, projects, analysts) load whole, with search and “show more”.
3. Prove it at volume before calling a page done: hundreds to thousands of rows, long text, a narrow window. seed-stress-data.js makes the data.

Layout

Path	What
src/main.jsx, src/App.jsx	Start-up, sidebar and page switching
src/routes.js, src/router.js	All addresses in one place
src/auth.js	Keycloak login and the token for API calls
src/api.js	Calls to the API (with upload progress)
src/pages/	One file per page
src/ui.jsx, src/theme.js, src/icons.jsx	Shared components and styles
src/SqlEditor.jsx, src/sqlSchema.js	The SQL editor (CodeMirror 6) and its auto-complete
src/openapi-push.json	The push API specification shown on the guide page

Known shortcut

Styling uses Tailwind from a CDN link. Before an offline data centre it must be switched to a built stylesheet. The npm packages use ^ ranges and should be pinned and mirrored for an offline build.