Project: Next.js permit delivery and cache boundary

Build contract

• Keep identity and repository access server-side; transfer only bounded, permitted, serializable case fields.
• Document cache audience and stale window for public categories and private queue reads separately.
• Validate action fields and permission, deduplicate operation IDs atomically, then refresh the affected view after commit.
• Place only slow authorized metrics behind a nested fallback, with a recoverable failure path and stable layout.

Implementation checkpoint

function mayApplyPermitApproval(operationId, committedOperationIds) {
  return !committedOperationIds.has(operationId);
}
const committedOperationIds = new Set(["permit-62-reviewer-81-attempt-47"]);
console.log(mayApplyPermitApproval("permit-62-reviewer-81-attempt-47", committedOperationIds));
// Output: false

Cost and boundaries

A server read costs permission and repository work per reviewer. A public cache reduces repeated category reads, but a private URL-only cache can disclose case data across accounts. A bounded transfer of 47 summaries avoids shipping all 47,000 cases; client filtering costs O(n) over only those transferred cases. The deduplication ledger uses O(m) storage for m retained operation IDs and must be transactional with the mutation. Revalidating a broad path can increase database load during an approval burst, so measure fanout. Streaming can make the queue useful before slow metrics complete, but it does not shorten the metrics query itself. Keep the fallback bounded and accessible, and measure the time to the queue and the time to the completed panel separately.

Failure drill

Warm reviewer 47's queue, then open the same route as reviewer 81 and scan both HTML and client payloads for forbidden case IDs. Approve case 62, drop the response after commit, replay the same operation ID, and inspect one database transition and one notification. Return to the queue through a client transition and hard reload; both must converge on approved within the freshness window. Delay metrics 1.8 seconds and confirm the queue arrives first. Fail the metrics request after the shell streams and verify that the panel offers a recoverable state rather than showing zero or a permanent spinner. Disable browser scripts and repeat the first-page read.

Acceptance checks

• No forbidden fields cross the server/client boundary or appear in another reviewer response.
• Private queue reads cannot reuse a response across permission boundaries.
• One operation ID produces one logical approval, followed by a fresh visible status.
• The useful shell streams before slow metrics and survives a recoverable metrics failure.

Common Mistakes

• Moving the whole server page into a client component for one filter.
• Reusing a private response by route path alone.
• Refreshing cache state before the database commits.
• Treating a loading fallback as error recovery.

Related lessons

Next.js App Router Delivery Boundaries; Next.js Server and Client Component Data Boundary; Next.js Cache Scope and Private Read Invalidation; Next.js Server Functions, Validation, and Operation Identity; Next.js Streaming, Suspense, and Error Recovery.