BFF Developer Note: Current Contract Direction¶

2026-04-11

Purpose¶

This note summarizes:

The deployed BFF has drifted from the intended canonical contract, especially in article objects and product BoM composition.
The article API currently exposes a flat runtime shape and mutation surface that does not preserve the fuller intended object semantics expressed in local intent/staging.
Product modeling was split incorrectly between Product and Item, which encouraged the backend to treat component objects as weaker objects with reduced semantics.
Product BoM semantics then drifted further into a runtime shape where line-item references are exposed through property, forcing consumer-side adaptation.
Local schema/docs, live runtime behavior, and downstream scaffold assumptions were allowed to diverge instead of being kept under one governing contract.

Refactor current consumers and scaffolding to use the live BFF as the authority for article and product content objects.
Keep only leftover site and page design metadata in oves-sites.
Leftover site and page design metadata means intent fields such as:
layout
routes
UI copy
spacing
decoration
collection selection
other presentation-oriented page/site configuration
Do not keep local article or product payloads as implied source-of-truth contract objects, except where they are explicitly transitional caches for static-site testing.
Any field that is content-domain truth belongs in the BFF contract and runtime behavior, not in scaffold-local content assumptions.

Product BFF must adopt one canonical Product object model and retire the false public Product versus Item split.
Site and page objects will eventually be promoted into persisted headless content managed through distinct BFF contracts as well.
Until then:
oves-sites remains the authority for site and page design intent
the live BFF remains the authority for content-domain objects

All future BFF contract work must follow:

That policy is now the required baseline for: