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.