Skip to content

Contact BFF Contract

Purpose

Define the boundary for site contact-form submission so page intent stays declarative while runtime transport, validation, audit, and delivery remain inside the Contact BFF.

Boundary

  • oves-sites owns:
  • whether a contact page exists
  • the route for that page
  • the selected contact-form block
  • editorial copy and visible field labels
  • generated ISR apps own:
  • wiring the rendered form to the configured Contact BFF endpoint
  • request serialization
  • client-side validation and error/success state handling
  • the Contact BFF owns:
  • authoritative validation
  • audit stamping
  • anti-spam and rate limiting
  • downstream CRM, email, or workflow delivery

Site Intent Contract

Site intent files must expose a top-level contactBffUrl alongside the other runtime BFF endpoints.

Example:

articleBffUrl: https://dirac-fed-dev.omnivoltaic.com/article-bff
productBffUrl: https://dirac-fed-dev.omnivoltaic.com/product-bff
contactBffUrl: https://dirac-fed-dev.omnivoltaic.com/contact-bff

Operational rule:

  • page-block props must not hardcode a live contact submission endpoint
  • scaffold/app consumers should read contactBffUrl from site intent and inject runtime submission wiring there

Minimum Submission Shape

The Contact BFF should accept a single canonical submit operation carrying:

  • name
  • email
  • company
  • country
  • message
  • sourceSite
  • sourceRoute

Optional fields may include:

  • phone
  • interest
  • campaign
  • utm
  • locale

Response Expectations

The Contact BFF should return:

  • success/failure status
  • a stable submission identifier
  • user-safe validation errors when input is invalid

The response must not expose internal delivery details.

Audit And Identity

  • the Contact BFF is the only approved mutation gateway for contact submissions
  • actor/request identity must be resolved server-side where available
  • audit timestamps and operational attribution must be stamped in the BFF/service layer
  • client payload must not be treated as authoritative audit identity

Implementation Rule

If a contact page is scaffolded from site intent, the generated app must bind the form submit handler to contactBffUrl. It must not leave a placeholder action such as "#" in production behavior.

The route-level interaction workflow for contact pages is defined separately in:

  • docs/contracts/contact-form-workflow.md