BFF Surface — HTTP as Capability Catalog (Developer Concept Doc)

Status: 2026-11-09. Audience: API consumers and integrators. Contract: the surface is described by capability, not by internal layout. Each desk is stated as PROBLEM → MECHANISM → INTERFACES → INVARIANTS. A compact catalog follows, then the full claims surface with its decision owner per row. (Source: entry-point registration areas; claims processing specification v1.1.0 and its interface test; operational memory BFF, auth, and NATS notes.)

Shared contract for every desk

PROBLEM — callers need one predictable HTTP edge with honest failure semantics. Without a shared contract, each desk would invent its own auth, throttling, and error story, and unfinished capabilities would fake success to fill the gap. (Source: entry-point ordering and honesty rules.)

MECHANISM — one edge on port 3030 with platform metrics, CORS for localhost and deployed origins, request logging, a five-megabyte JSON body limit, and a raw-body exception for payment webhooks that verifies signatures before JSON parsing. Liveness and readiness probes expose the entry point; readiness distinguishes service liveness from database reachability. (Source: entry-point health and body handling.)

INTERFACES — health probes plus capability groups below. Every capability group is reachable only through the same middleware pipeline. (Source: entry-point middleware order.)

INVARIANTS — auth and throttling are gateway policy, not desk policy. Local development may skip authorisation with a development identity and local scope; production requires a signed bearer token with strict key-set validation, and commerce probes are permitted only in development. Global throttling is shared-store backed and fails open to a no-op with a warning rather than failing boot; authentication traffic is capped at ten requests per minute per address. Truth-family routes require a vault scope header with an optional caller scope, and mutations require a signed transit-trail guard unless the development bypass is set. (Source: development skip and production authorisation guards; throttling and vault header rules.)

Desks as mechanisms

Claims desk

PROBLEM — lifecycle operations need guarded, auditable transitions with proof. Unguarded state changes cannot be audited, and soft plans that write would conflate simulation with execution. (Source: claims specification summaries.)

MECHANISM — the desk mediates the full claim journey: create, list, statistics, proof requirement declaration, dry-run guard evaluation, zero-write soft apply, timeline read, guarded transition, and finalise with a proof receipt. Proof gating is declared per scope and claim type; a dry run evaluates the same guard as execution with no state change; soft apply validates and plans with zero writes. (Source: claims specification operation summaries.)

INTERFACES — creation, listing, declaration, dry run, soft apply, read, transition, finalise. (Source: claims specification path set.)

INVARIANTS — every mutation is guarded before it lands and every finalisation carries evidence. Guards are declarative lookups, not code branches; soft operations honestly report they are not live. (Source: claims honesty contract.)

Panel desk

PROBLEM — provider selection must resolve from declared panels, not hardcoded rosters. Hardcoded panels cannot be versioned, scoped, or audited per claim type. (Source: panel desk summaries.)

MECHANISM — the desk lists provider panel roles for a claim type and resolves eligibility for one candidate against the declarative panel lookup. Resolution is a pure function of declared roles plus the candidate attributes. (Source: panel desk summaries; declarative panel lookup.)

INTERFACES — role listing and single-candidate eligibility. (Source: panel desk summaries.)

INVARIANTS — eligibility is declared-panel evaluation, never invented. No candidate is eligible by default. (Source: declarative panel rule.)

SLA desk

PROBLEM — service windows must be evaluated consistently per type and severity. Ad-hoc time checks drift and cannot record what action a breach triggered. (Source: SLA desk summaries.)

MECHANISM — the desk exposes the service window for a claim type and severity, evaluates a window against a start time, and records a breach with its action. Windows come from the declarative service-level lookup; evaluation is deterministic and recording emits through the lifecycle subject family. (Source: SLA desk summaries; declarative service-level lookup.)

INTERFACES — window read, window evaluation, breach recording. (Source: SLA desk summaries.)

INVARIANTS — windows are looked up, breaches are recorded, never synthesised. (Source: declarative service-level rule.)

Quorum desk

PROBLEM — high-value or high-risk transitions need threshold agreement, not single-actor flags. Single-actor approval cannot express the risk tiers that govern value. (Source: quorum desk summaries.)

MECHANISM — the desk lists quorum bands for a claim type, resolves the band template for an amount and risk combination, and opens a threshold group from the resolved template. Bands come from the declarative threshold lookup; group creation instantiates signer sets intermediately. (Source: quorum desk summaries; declarative threshold lookup.)

INTERFACES — band listing, template resolution, group opening. (Source: quorum desk summaries.)

INVARIANTS — thresholds are data, signatures are evidence. A band without collected signatures does not satisfy the guard. (Source: threshold agreement semantics.)

VAS desk

PROBLEM — value-added service eligibility must be checkable per cover and per service. Eligibility embedded in fulfilment code cannot be versioned or explained to the customer. (Source: value-added desk summaries.)

MECHANISM — the desk lists eligibility for a cover and checks one service against one claim by evaluating the declarative eligibility lookup. Checks are pure evaluations with no side effects. (Source: value-added desk summaries; declarative eligibility lookup.)

INTERFACES — cover-level listing and single-service check. (Source: value-added desk summaries.)

INVARIANTS — eligibility is declared, not inferred from fulfilment. (Source: declarative eligibility rule.)

Intake desk

PROBLEM — field intake needs versioned maps that can be previewed before any upsert happens. Direct upserts hide mapping errors until they reach durable state. (Source: intake desk summaries.)

MECHANISM — the desk lists field maps for intake and provider updates and previews one map against a payload without persisting. Maps come from the declarative intake lookup and preview returns the would-be mapping plus errors. (Source: intake desk summaries; declarative intake lookup.)

INTERFACES — map listing and non-persisting preview. (Source: intake desk summaries.)

INVARIANTS — preview never writes. (Source: intake preview contract.)

Readiness desk

PROBLEM — operators need a live truth signal, not a configuration echo. Static readiness cannot distinguish a booted process from a reachable database and event path. (Source: readiness summary.)

MECHANISM — the desk probes real network conditions — database reachability plus the live event path — and returns the aggregated readiness decision. (Source: readiness summary.)

INTERFACES — single readiness probe. (Source: readiness summary.)

INVARIANTS — readiness reflects live checks or it says so. Failed checks return unavailable, never a synthesized ready. (Source: fail-closed rule.)

Metrics desk

PROBLEM — operational numbers must come from real claim events. Invented percentages and counts destroy trust in every adjacent desk. (Source: metrics summary.)

MECHANISM — the desk computes brief metrics from real claim events and aggregate statistics from the same event history. No metric is stored as a static constant; every value derives from observed events. (Source: metrics and statistics summaries.)

INTERFACES — brief metrics and aggregate statistics. (Source: metrics and statistics summaries.)

INVARIANTS — no synthetic metrics. If events are absent, metrics say so rather than inventing values. (Source: no-synthetic-payloads mandate.)

Vigilance and voyage desk

PROBLEM — operators need to watch a claim’s full journey and the fabric’s health in one place. Correlation without a projection invites per-hop debugging; fabric health without consumed counts invites blind batches. (Source: voyage summary; consumer health contract.)

MECHANISM — the desk projects a voyage by correlation identifier across claim, sourcing, proof, and delivery hops, and exposes event catch-up, statistics, and health surfaces for the fabric. The projection joins on the voyage identifier attached before enqueue; health reports consumed and refused counts with an invent-refusal flag set and a live-gate flag cleared. (Source: voyage summary; consumer health contract; envelope correlation rule.)

INTERFACES — voyage projection plus event catch-up, statistics, and health. (Source: voyage summary; event health surfaces.)

INVARIANTS — voyage is a projection, health never invents live state. (Source: consumer honesty contract.)

Capability catalog — one row per route group

(Source: claims specification summaries; declarative lookup set; consumer health contract.)

Claims surface — full path set with decision owner

The specification and its interface test enumerate twenty-three paths; the table shows twenty-four method rows because creation and listing share one path with two verbs. Purposes are shortened from specification summaries. (Source: claims processing specification v1.1.0 and interface test.)

(Source: claims processing specification path summaries and decision descriptions.)

Cross-cutting guards — auth, throttling, transport, honesty

Authorisation, throttling, and transport are gateway concerns that every desk inherits. Core-bus subscriptions use queue groups for request and reply plus direct publishes for receipts; durable configuration views and streams carry configuration reads, standing-order watches, and callback ingress. Declarative planes hold lookups, scenario packs, and templates, and every desk reads them live rather than from frozen copies. Soft surfaces refuse to invent live state with an explicit invent-refusal marker and companion client or service errors. (Source: entry-point transport inventory; consumer health contract; accumulation honesty note.)

Interface summary