Frontend Data and State

A handwritten copy of a request, a response, or a schema drifts from the contract silently: the API changes, the copy still compiles, and the page sends a request the API no longer accepts. A generated client turns the same contract change into a compile error in every application at once, at every call site the change affects.

Reviewed forWhich client, type, schema, or operation option is handwritten instead of generated from the published OpenAPI document? Look in the generated client directory and the contract it names.

Marked guidance: a reviewer answers this question.

The configured client owns the base address, the credentials, the headers, and the mapping from a failure to a problem. A call that builds its own request opts out of all four at once: it can point at the wrong host, miss the session cookie, skip the write marker, and surface a raw failure outside the page's problem shape. Routing every read and write through the one client keeps those four decisions in one place.

Reviewed forWhich reads or writes bypass the one configured client? Look in the frame client configuration and the call sites.

Marked guidance: a reviewer answers this question.

Every value a script can read is a value any script on the page can read, including a script an attacker injected. Tokens kept in frontend code or browser storage are therefore readable by the same attack the session is meant to resist. The API runs the authorization code flow and keeps the tokens encrypted in an HTTP-only cookie the browser sends on its own, so frontend code holds no token. A refused sign-in lands on a signed-out page rather than on an error, because the reader is not signed in.

Reviewed forWhich tokens sit in frontend sources instead of the API-owned HTTP-only cookie? Look in the API session handling and the frontend sources.

Marked guidance: a reviewer answers this question.

A browser attaches its cookies to a cross-site request on its own, so the cookie alone fails to distinguish the page's own write from a forged post submitted from another site. The marker header separates the two: the page's client adds it to every write, and a page on another site adds no custom header without a preflight, which the API grants to no foreign origin. The API therefore accepts a cookie-authenticated write only when the header is present. The header name varies by project, so configuration owns it rather than code; it has the form X-<Project>-Request with the value 1.

Reviewed forWhich writes lack the configured marker header of the form X-<Project>-Request? Look in the client configuration and the API write acceptance.

Marked guidance: a reviewer answers this question.

A raw response body carries whatever the API included: field names, internals, sometimes data kept from the reader. Rendering it leaks that content and gives the reader no consistent recovery path, because each failure looks different. One problem type gives every failure the same shape: the page branches on the published code, so its decision survives a reworded message, and the trace identifier in the detail lets support find the request the reader saw fail. The identifier stays out of the headline, which says what happened in words the team wrote.

Reviewed forWhich failures render outside the one problem type, or hide the trace identifier from the detail? Look in the frame problem mapping and the error surfaces.

Marked guidance: a reviewer answers this question.

A refusal at the top of a page says that something failed but not what, so the reader scans the page to find the control that caused it. Rendered beside the refused record or control, the refusal answers both questions at once. The sentence comes from the application's own dictionary for that code rather than from the response body, so the words stay consistent and translatable; the code in the markup lets a test provoke the refusal by name.

Submitting an expense above the receipt threshold with no receipt refuses with spending.receipt-missing under result/submit-expense.receipt-missing. The page renders the application's sentence for that code beside the Submit control, carries the code in the markup so a test provokes it by name, and keeps the trace identifier in the detail in copyable form.

Reviewed forWhich refusals render away from the refused record or control, or without the application's sentence and code in the markup? Look in the screen's page files beside the refusing controls.

Marked guidance: a reviewer answers this question.

A list of problems above a long form forces the reader to read each sentence and each label to pair them, and a problem below the fold is missed entirely. The frame's one helper puts each problem on the field it names, so the reader sees what to fix where they fix it. The form stays open until each problem is resolved or the reader abandons the form, so no input is lost to a closed dialog.

Reviewed forWhich field problems miss their fields, bypass the frame helper, or close the form? Look in the forms and the frame helper.

Marked guidance: a reviewer answers this question.

The generated schema is the contract's statement of what the API accepts, so it holds even where the browser accepts more. Validating the form against it refuses bad input before the request leaves the page. The application extends the schema with the message shown for each rule and any rule beyond the contract's reach, rather than replacing it, so the form refuses everything the API refuses.

Reviewed forWhich forms validate against a handwritten restatement instead of the generated request schema extended with application rules? Look in the form sources and the generated schemas.

Marked guidance: a reviewer answers this question.

The query cache owns freshness: a page renders the cached answer, not a new request. A command that changes a record but leaves its cache entry therefore shows the old record until something else happens to refetch, so the reader's own write appears to have no effect. Invalidating exactly the queries the command changed refreshes what changed; invalidating more costs a needless request per affected page.

The generated client holds both sides of one write: the expenses route calls the submit operation with the expense values, and the list reads through the list operation. After the submit succeeds, the page invalidates the list query and no other query, so the list shows the new expense without refetching unrelated pages.

Reviewed forWhich successful commands leave a changed query cached, or invalidate a query their answers left unchanged? Look in the command call sites and the cache keys.

Marked guidance: a reviewer answers this question.

Server data belongs in the query cache, shareable values in the address, input in form state, and the rest in the component's own state. A value kept above its narrowest owner, typically in a shared store, makes unrelated components re-render when it changes and hides where the change came from. The order gives each value the smallest audience that can use it.

Reviewed forWhich values live above their narrowest owner instead of the query cache, the address, form state, or component state? Look in the state declarations.

Marked guidance: a reviewer answers this question.

The handler is the one place a use case exists: its validation, its rules, and its result. A screen or component that composes its own sequence of Domain calls and storage writes creates a second definition that no record names and no test pins down. Routing every use case through a handler keeps the screen or component a caller and the handler the definition.

The expense screen invokes the submit-expense Application handler for EXP-1042 rather than composing the Domain expense calls and writing the expense store itself.

Reviewed forWhich screens or components compose Domain calls or write storage instead of invoking an Application handler carrying a Command or Query role suffix? Look in the screen and component sources.

Marked guidance: a reviewer answers this question.

The classification decides what happens to the state: durable state is persisted, versioned, and exported, device-local state is persisted but excluded from export, and derived state is never persisted. Without a declared classification each reader guesses, and a value the user made can end up unpersisted while a computed value ends up stored and stale.

The expense draft for the Rotterdam client visit is durable state, the device copy of the receipt photo is device-local state, and the expense total for EXP-1042 is derived state computed from its lines.

Reviewed forWhich aggregates introducing state name no durable, device-local, or derived classification on their page? Look on the aggregate pages.

Marked guidance: a reviewer answers this question.

A query string leaks: proxies log it, the browser keeps it in history, and the next page the reader opens receives it as the referrer. A value naming a person therefore travels in a request header the contract declares per operation, where it reaches the API without landing in those three places. The address keeps its own copy for filters and paging, so a filtered list stays a link somebody can share.

Reviewed forWhich person-naming values travel in the query string instead of contract-declared headers? Look in the contract headers and the call sites.

Marked guidance: a reviewer answers this question.

Permissions are the project's permission records: an actor holds a role at a scope, a role allows permissions, and a use case needs permissions. The page reads the permissions the signed-in actor holds from the session the API returns, and offers only the commands those permissions allow at the record's scope, so the reader meets no offer that ends in a refusal. The API still decides every command, so an action offered in error is refused rather than executed.

Reviewed forWhich offered commands exceed the permissions the session actor holds at the record scope? Look in the page command guards and the session shape.

Marked guidance: a reviewer answers this question.

An instant from the API carries no zone, so a formatter left to pick one shows the reader's own zone: a payout cut-off reads as midnight in the reader's city instead of the office's. The caller resolves the zone from the record the screen shows: a record with its own zone states it, otherwise the account's zone applies, and an account that chooses none falls back to UTC. Passing the zone explicitly makes each timestamp name whose day it belongs to.

Reviewed forWhich timestamp formatters run without an explicit IANA zone resolved from the shown record? Look in the formatter call sites.

Marked guidance: a reviewer answers this question.

Local storage, session storage, IndexedDB, and a build-time public variable are all readable by any script on the page, so a secret kept there is available to the same injected script the secret is meant to resist. Refresh tokens, provider secrets, and privileged credentials therefore stay out of the browser entirely. A preference the reader chooses, such as a theme or a locale, is not a secret and can be stored under a named key in the frame.

Reviewed forWhich refresh tokens, provider secrets, or privileged credentials sit in browser storage or browser-visible variables? Look in the storage writes and the public variables.

Marked guidance: a reviewer answers this question.

An optimistic update shows a value the server has not confirmed. Without a stable client identity the retry after a failure creates a duplicate; without declared conflict behavior two writers overwrite each other silently; without a rollback path a failed update leaves the shown value wrong. Declaring identity, conflict behavior, rollback, and reconciliation up front makes each of those cases designed instead of improvised. Money, irreversible actions, and uncertain authorization skip optimism entirely and wait for the server result.

Reviewed forWhich optimistic updates lack a declared client identity, conflict behavior, rollback, or reconciliation path, and which money, irreversible, or uncertainly authorized actions run optimistically instead of waiting for the server? Look in the optimistic update definitions.

Marked guidance: a reviewer answers this question.

A rollback is a silent visual change: the shown value changes back with no event a screen reader announces. The reader heard the optimistic value confirmed and hears nothing when it is withdrawn, so they act on a value the server refused. Announcing the reconciled outcome through a live region tells them what actually holds. The ARIA live-region technique is the mechanism, and a test of the route asserts the announcement.

Reviewed forWhich reconciled outcomes differing from the shown value announce through no live region? Look in the route tests asserting the announcement.

Marked guidance: a reviewer answers this question.

One sentence written in two components drifts at the first rewording, because the author finds one copy and misses the other. A dictionary per language keeps each sentence in one place, keyed by a typed key the compiler checks, with fill and plural support so variable content and counts render correctly in every language. One chunk per language keeps a reader's download to the language they read, and a key the catalog lacks fails where the declared fallback says it fails instead of rendering a raw key.

A workspace that carries its own dictionary machinery still meets the same contract.

Reviewed forWhich copy bypasses the locale dictionaries, or misses fill, plural, chunking, typed keys, or a declared fallback? Look in the locale dictionaries and the copy call sites.

Marked guidance: a reviewer answers this question.