Skip to content

Add a guide and template for frontends a team runs itself - #835

Merged
nlundee merged 2 commits into
mainfrom
ka-frontends
Nov 19, 2026
Merged

nlundee merged 2 commits into
mainfrom
ka-frontends

Conversation

@nlundee

@nlundee nlundee commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

What and why

Milestone M9 of #771: a guide and a template for a frontend a team runs itself and registers in genki as a browser frontend of its service, the second half of the mixed model in ADR 0061. The guide is docs/run-your-own-frontend.md; the template is examples/team-frontend (plain TypeScript, no dependencies, an nginx image, a Dockerfile and a README).

Risk

Low. Docs and an example only; no API, auth or infra code changes. The template handles login tokens, so its choices are worth a look: code flow with PKCE, state and nonce checked, tokens in sessionStorage only, a CSP of 'self' plus the issuer, answer and source text rendered as text, links only for http(s). The guide says to keep tokens on a server before real people log in (ADR 0034).

Undo

Revert is enough.

How it was tested

  • npx vitest run examples/team-frontend: 10 tests, among them refuses a callback whose state is not the one it sent, refuses tokens whose nonce is not the one it sent, streams an answer, drops retracted text and returns its sources, thread and task, sends no request without a signed-in person. The state, nonce and retract tests were seen failing with those checks removed.

  • docker build of the template (its tsc runs inside), npm run typecheck, npm run build, npm run atlas:build and atlas:test, prettier and eslint on the touched files, scripts/docs-bundle.test.ts and scripts/delivery.test.ts.

  • By hand, in a browser: the template's image against a local genki in dev mode with Postgres, the knowledge server's demo generation (npm run knowledge:seed), a rag-single-shot service on it and the local test model replaying a recorded answer. Registered the frontend with PUT /tenants/991825827/clients/..., logged in through the mock Ansattporten as a test person with use-services, got a streamed answer citing [1] with its source, reopened the thread after a reload and a new login, and asked a follow-up in it. Not run against genki-test or real Ansattporten.

  • npm run check passes

Checklist

  • Every new rule has a test whose name states it
  • User-facing text is in the i18n catalogues, in bokmål and English, with no em-dashes
  • Vendor SDKs stay in packages/providers-*
  • ADRs, docs and docs/architecture/modules are updated if a contract, boundary or module changed
  • No secrets, personal data or local paths

A service that needs its own frontend code runs it in its own container and registers it in genki as a browser frontend (ADR 0061). This adds the guide and a small template for that path.

- docs/run-your-own-frontend.md: who owns what, registering the Ansattporten client and the genki Client, what genki-test's lockdown needs, the login, the calls for streamed answers, threads and sources, limits, and what changes for production (#464).
- examples/team-frontend: plain TypeScript with no dependencies (login with PKCE, services, streamed answers, threads, feedback), an nginx image that writes its config from the environment, proxies /genki/ and sets a strict CSP, and tests for the login and streaming rules.
- Links from the README, Build a frontend and the frontend contract.

Tested: the template's tests, the image build, and a run in the browser against a local genki with the mock login, the demo knowledge generation and the local test model: login, an answer with a cited source, a reopened thread and a follow-up in it. No live model calls.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 findings, 1 Important. The summary comment has the overview.

Comment thread docs/run-your-own-frontend.md Resolved
Comment thread examples/team-frontend/app.ts Resolved
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Model review

5 findings: 5 open (3 Important), 0 fixed, 0 dismissed.

Walkthrough

The pull request adds a guide (docs/run-your-own-frontend.md) and a copy-ready template (examples/team-frontend) for a frontend that a team runs in its own container. The frontend is registered in genki as a browser Client, people log in with Ansattporten using PKCE, and the page calls genki through an nginx proxy. The existing frontend docs and the README now link to the guide. I found two problems: the guide says a missing channel or origin gets a 403, but genki answers 401; and the template's response to a 401 is a reload that never ends.

Area What changes
docs Adds the 'Run your own frontend' guide. It covers who owns what, registering in Ansattporten and in genki, login, the calls a chat frontend needs, how to run it and its limits. Links to it are added from README.md, docs/build-a-frontend.md and docs/frontend-contract.md.
examples/team-frontend Adds a dependency-free TypeScript browser frontend: genki.ts does the PKCE login and the calls for services, streamed answers, threads and feedback, and app.ts is the page. Also adds an nginx-unprivileged Dockerfile that writes /config.json from the environment, proxies /genki/ and sets a strict CSP, plus vitest tests for genki.ts against a fake genki.

Findings

Where Finding Status
Important docs/run-your-own-frontend.md:103 Guide says a refused channel or origin gets 403, but genki answers 401
make an ADR, the API docs or docs/development.md say something the code does not do
Open
Important examples/team-frontend/default.conf.template:17 Verify the upstream API's TLS certificate
weaken authentication, or let a dev-only setting
Open
Important docs/run-your-own-frontend.md:7 Describe the hosted assistant as proposed, not available
make an ADR, the API docs or docs/development.md say something
Open
Nit examples/team-frontend/app.ts:25 A 401 from genki makes the template reload forever
Everything else is Nit at most
Open
Nit examples/team-frontend/index.html:14 Localize the template's visible text
Text a user sees goes through the i18n catalogues
Open
Fix the open findings with your coding agent
Fix these review findings on digdir/genki#835. Read each thread first; if a finding is wrong, reply in the thread instead of changing code. Add or update a test for each fix, then run npm run check.

1. docs/run-your-own-frontend.md:103: Guide says a refused channel or origin gets 403, but genki answers 401
   Fix: Say that a missing channel or a disallowed origin is answered with 401, like an unknown token, and that only a refused environment or right is a 403 with a reason.
2. examples/team-frontend/default.conf.template:17: Verify the upstream API's TLS certificate
   Fix: Enable proxy_ssl_verify and configure a trusted CA bundle and the expected upstream hostname, following the existing apps proxy.
3. docs/run-your-own-frontend.md:7: Describe the hosted assistant as proposed, not available
   Fix: Explicitly label the hosted assistant and its BFF as proposed future alternatives in both places.
4. examples/team-frontend/app.ts:25: A 401 from genki makes the template reload forever
   Fix: Remove the stored session before redirecting on a 401 from genki, for example `sessionStorage.removeItem(`${config.clientId}.session`)` or an exported `forgetSession` in genki.ts. Alternatively, show the message for a 401 that is not `signed_out` instead of reloading. Add a test that a 401 from genki ends with the person signed out.
5. examples/team-frontend/index.html:14: Localize the template's visible text
   Fix: Add small bokmål and English catalogues and use the selected language consistently for page labels, login, API requests and locally generated errors.

Reviewed at 36622c7 with claude-opus-5-5 in 1.7 min. Pushes are checked against open findings, and fixed ones are resolved. Add the label review again to review new commits.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cross-model review by gpt-6.1-sol: 3 findings, 2 Important, on the security-sensitive parts of this change.

Comment thread docs/run-your-own-frontend.md Resolved
Comment thread examples/team-frontend/index.html Resolved
- The guide says a refused channel or origin answers 401, as the API does.
- A 401 from genki forgets the stored session, so the page no longer reloads forever.
- The nginx proxy verifies genki's TLS certificate and host name.
- The guide says what of the genki host is built and that its BFF is proposed.
- The template's texts, login and calls follow one language, bokmål or English.
@nlundee
nlundee added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 5d08da8 Nov 19, 2026
18 checks passed
@nlundee
nlundee deleted the ka-frontends branch November 19, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant