phase-1: scaffold platform foundation structure and architecture governance

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

@@ -0,0 +1,42 @@
+# 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.