marketplaces/docs/architecture/foundation/Configuration-Standards.md

Configuration Standards

Status: Mandatory Date: 2026-07-03

Source of Truth

• All runtime application configuration originates from bootstrap payload.
• ConfigService is the only component allowed to load configuration.
• No direct JSON loading outside ConfigService.

Provider Abstraction

• Configuration provider must be swappable.
• Mock and API providers must return identical schema.
• Consumer code remains unchanged when provider changes.

Bootstrap Contract Scope

Bootstrap includes at minimum:

• Tenant
• Branding
• Theme
• Company
• Feature flags
• Navigation
• Pages, sections, widgets
• Localization
• SEO
• Permissions and capability model
• Endpoint descriptors

Backend Compatibility

• Frontend calls GET /bootstrap.
• Backend resolves tenant from Host.
• Frontend does not send tenant id/project key.

Validation and Versioning

• Bootstrap payload must include schema version.
• Validate payload before applying to runtime.
• Invalid payload fails fast with controlled fallback.

Mock Rules

• Mock payloads must match future API responses exactly.
• No mock-only fields.
• No mock-only nesting conventions.

Sprint 11.5 Bootstrap Audit Addendum

• Every configurable website behavior must be representable in bootstrap contracts or widget metadata.
• Missing configuration must be documented before implementation work starts.
• Frontend teams must not implement backend contract changes in standardization sprints.

Current documented gaps:

• Widget role/permission enforcement requires richer auth session claims than currently available.
• Catalog popular-search defaults should move from facade constants into bootstrap catalog config.
• Optional override support for persistent-storage key prefixes is not yet represented in bootstrap schema.