marketplaces/docs/architecture/foundation/State-Management-Standards.md

State Management Standards

Status: Mandatory Date: 2026-07-03

Objectives

• Keep state predictable, scoped, and replaceable.
• Support Website, Builder, and Backoffice without coupling.

State Layers

• Platform State: bootstrap, feature flags, theme, localization, session status.
• Domain State: feature-specific bounded context state.
• UI State: ephemeral visual state local to component/container.

Facade Rules

• Every domain exposes state through facades.
• Facades expose readonly projections/selectors/signals.
• Mutations happen through explicit facade commands.

Isolation Rules

• No direct cross-domain state mutation.
• No component writes directly into service internals.
• Shared state contracts must be explicit and typed.

Persistence Rules

• Persisted state access must be centralized in approved services.
• UI components never access localStorage/sessionStorage directly.

Feature Flag Interaction

• State branches for optional capabilities must be capability-driven.
• Missing capability paths must return safe defaults.

Migration and Compatibility

• Existing auth/payment behavior remains intact while wrapped by facade boundaries.
• Refactoring must preserve observable behavior for critical flows.