logfab-nudge

System for handling notifications

Created from the "Logikfabriken app" template in Developer Hub (logfab-app@3): TanStack Start (React with server-side rendering), TypeScript, Tailwind CSS and shadcn/ui, with its own PostgreSQL database, file storage and login, already set up for Logikfabriken's OpenShift platform. What the template gained since, and how to add it here, is in its CHANGELOG.

Building with an AI agent (Claude Code, Cursor, Copilot and the like)? It reads AGENTS.md (Claude Code through CLAUDE.md), which tells it the stack and the platform's rules. Keep that file up to date as the app grows.

How it goes live

Push to main. A few minutes later it is live at https://logfab-nudge.apps.ocp.poc.logfab.cloud. On the way, every push is checked for leaked passwords (Gitleaks) and unsafe code (Semgrep), built, checked for known security holes (Trivy), signed, deployed, and scanned while it runs (OWASP ZAP). A failed check stops it. Follow each run in Developer Hub, on this app's CI tab.

You need no Dockerfile and no deploy settings: the platform builds it with npm run build and runs it with npm start.

Run it on your computer

npm install
cp .env.example .env    # settings for your computer
npm run dev             # http://localhost:3000

Before pushing: npm run typecheck, npm run lint and npm run build.

The database

The platform gives the app its own PostgreSQL database: two copies on two servers, so one can fail without the app noticing. The app finds it through DATABASE_URL, which the platform sets; nobody needs its password.

• Tables are in src/db/schema.ts (Drizzle). After changing them, run npm run db:generate and commit the new file in drizzle/. The app applies it to the database when it starts.
• Read and write in server functions, like the notes on the start page (src/routes/index.tsx).
• On your computer the app runs without a database until you set DATABASE_URL in .env to a Postgres of your own.
• Backed up by the platform: every change as it happens and a full backup every night, kept for 7 days; it can be restored to any moment in that time.

Files

The app also gets its own bucket in the platform's S3 storage, for uploads, images and the like (the server's disk is wiped at every deploy). Its address and keys arrive as S3_* settings, set by the platform.

• The client is in src/storage/ (@aws-sdk/client-s3); the start page has an upload example.
• The bucket is reachable from the app's server only; the browser gets files through /api/files/<key>.
• On your computer there is no bucket unless you set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY in .env to an S3 of your own.

Login

People sign in through Logikfabriken's Keycloak with their Microsoft account; the app never sees a password. Pages and server functions are open to everyone until you protect them:

• A page: beforeLoad: ({ location }) => requireLogin(location.href) in its route.
• A server function: const user = await requireUser() at its start.
• Only one Keycloak group: pass the group as well, e.g. requireUser('/logikfabriken/devex'). Not on the platform yet: it does not pass people's groups to apps, so user.groups is empty there and a group check lets nobody in. Ask the platform team if you need it.

All three come from @/auth/functions; AGENTS.md has examples. The start page has a sign-in and sign-out button. On your computer everyone is "Test User", without Keycloak.

Settings and keys

Keep them out of this repo. On the platform they live in Bitwarden Secrets Manager, project openshift-apps, as one secret named logfab-nudge/staging whose value is JSON:

{ "GREETING": "hello", "API_KEY": "...", "VITE_PUBLIC_MESSAGE": "hi" }

• Every value reaches the server as an environment variable (process.env.GREETING), for server functions and server routes. Real secrets belong here.
• Values starting with VITE_ also reach the browser, written in when the app is built (import.meta.env.VITE_PUBLIC_MESSAGE). Every visitor can read those, so only public values.

A changed value reaches the app at its next build: push to main.

Logs and health

• Server code logs with log from src/lib/log.ts: one JSON line per event, plus one per request. See them in Developer Hub (Topology tab, the app's pod) or the OpenShift console.
• GET /api/health tells OpenShift the app is up.

Docs

docs/ holds this app's docs, in Markdown, shown on its Docs tab in Developer Hub. A push to main that changes docs/ or mkdocs.yml publishes them. Add a page: a file in docs/ and a line under nav in mkdocs.yml.

Files

• src/routes/: the pages (index.tsx is the start page) and api/ endpoints.
• src/components/ui/: shadcn/ui components; add more with npx shadcn@latest add <name>.
• src/lib/: shared code (logger, helpers).
• src/start.ts: what runs around every request.
• docs/ and mkdocs.yml: the docs on the Docs tab.
• AGENTS.md: instructions for AI agents.
• catalog-info.yaml: how the app is listed in Developer Hub.