Repository navigation
Add a guide and template for frontends a team runs itself - #835
Conversation
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.
Model review5 findings: 5 open (3 Important), 0 fixed, 0 dismissed. WalkthroughThe 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
Findings
Fix the open findings with your coding agentReviewed 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 |
- 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.
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
browserfrontend of its service, the second half of the mixed model in ADR 0061. The guide isdocs/run-your-own-frontend.md; the template isexamples/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,
stateandnoncechecked, tokens insessionStorageonly, 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 themrefuses 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 buildof the template (itstscruns inside),npm run typecheck,npm run build,npm run atlas:buildandatlas:test, prettier and eslint on the touched files,scripts/docs-bundle.test.tsandscripts/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), arag-single-shotservice on it and the local test model replaying a recorded answer. Registered the frontend withPUT /tenants/991825827/clients/..., logged in through the mock Ansattporten as a test person withuse-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 checkpassesChecklist
packages/providers-*docs/architecture/modulesare updated if a contract, boundary or module changed