# 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.