phase-1: scaffold platform foundation structure and architecture governance

docs/architecture/foundation/Coding-Standards.md

@@ -0,0 +1,44 @@
+# Coding Standards
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Core Principles
+
+- Keep modules small and cohesive.
+- Prefer pure functions where possible.
+- Prefer composition over inheritance.
+- Prefer configuration over conditionals.
+- Avoid duplication; extract shared behavior above 70 percent overlap.
+
+## Type Safety
+
+- No any in domain and configuration contracts.
+- Strict typing for API payloads and configuration schemas.
+- Use discriminated unions for widget and section types.
+
+## Error Handling
+
+- Errors normalized at service/integration boundaries.
+- UI displays user-safe messages from facades/view models.
+- No unhandled promise rejections.
+
+## API and IO
+
+- IO is performed in services/integrations only.
+- Use facades to orchestrate calls and map outputs.
+- Keep presentation layer side-effect free.
+
+## Testing Expectations
+
+- Unit tests for facades, services, and mapping logic.
+- Contract tests for bootstrap schema compatibility.
+- Boundary tests for forbidden imports.
+
+## Review Checklist
+
+- Does this code violate layer boundaries?
+- Is tenant behavior configuration-driven?
+- Is logic duplicated and extractable?
+- Are auth/payment contracts unchanged?
+- Is the app still compilable?

docs/architecture/foundation/Component-Standards.md

@@ -0,0 +1,39 @@
+# Component Standards
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Component Categories
+
+- UI Component: presentational, reusable, stateless or locally visual state only.
+- Container Component: binds facades and maps view model to UI inputs.
+- Layout Component: structural composition of sections/widgets.
+
+## Reusable UI Rules
+
+A reusable component must:
+
+- Receive data via Inputs.
+- Emit user intent via Outputs.
+- Contain no HttpClient usage.
+- Contain no localStorage/sessionStorage usage.
+- Import no environment data.
+- Have no tenant-specific behavior.
+- Have no auth/payment/authorization logic.
+- Have no route navigation logic.
+
+## Container Rules
+
+- Orchestrate business behavior through facades.
+- Map facade state into UI-friendly view model.
+- Handle route and guard interactions.
+- Never leak domain internals to UI components.
+
+## Reuse and Duplication Rule
+
+- If two components share more than 70 percent behavior or template structure, extract reusable component.
+
+## Accessibility and UX
+
+- Components must provide semantic markup and keyboard support.
+- Outputs must represent intent, not implementation details.

docs/architecture/foundation/Configuration-Standards.md

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

docs/architecture/foundation/Dependency-Rules.md

@@ -0,0 +1,35 @@
+# Dependency Rules
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Rule Set
+
+1. One-way dependency direction only.
+2. No circular dependencies.
+3. No feature imports another feature directly.
+4. Shared is dependency-minimal and feature-agnostic.
+5. Core is platform base and does not consume feature modules.
+6. UI Library is pure presentation and cannot depend on facades/services with business behavior.
+7. Widgets depend on UI Library and contracts, not on feature internals.
+8. Pages compose layouts/widgets via contracts and facades.
+9. Facades depend on services/contracts, never on UI components.
+10. Integrations isolate external systems and expose stable interfaces.
+
+## Dependency Injection Rules
+
+- Depend on interfaces/tokens where replacement is expected.
+- Avoid direct concrete service references across bounded contexts.
+- Use adapter pattern for legacy stable modules.
+
+## Cross-Domain Communication
+
+- Allowed through contracts, events, and facade APIs.
+- Forbidden through direct state mutation across domains.
+
+## Forbidden Patterns
+
+- Component to HttpClient direct calls in reusable visual components.
+- Direct environment import in visual components.
+- Direct localStorage/sessionStorage usage in UI components.
+- Route navigation logic in UI library components.

docs/architecture/foundation/Folder-Blueprint.md

@@ -0,0 +1,122 @@
+# Folder Blueprint
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Objective
+
+Define the target folder layout for the Foundation Phase and all subsequent phases.
+
+## Blueprint
+
+src
+- app
+  - core
+    - bootstrap
+      - providers
+      - loaders
+      - validators
+    - config
+      - application-config.token.ts
+      - config.service.ts
+      - feature-flag.service.ts
+    - runtime
+      - app-runtime.service.ts
+      - platform-context.service.ts
+    - guards
+    - interceptors
+    - error-handling
+  - shared
+    - models
+      - api
+      - config
+      - domain
+      - ui
+    - types
+    - enums
+    - contracts
+    - utils
+    - constants
+  - ui-library
+    - atoms
+    - molecules
+    - organisms
+    - directives
+    - pipes
+  - widgets
+    - registry
+    - contracts
+    - containers
+    - ui
+  - layouts
+    - shells
+    - sections
+    - containers
+  - pages
+    - public
+    - builder
+    - backoffice
+  - features
+    - website
+      - catalog
+      - product
+      - cart
+      - checkout
+    - builder
+      - theme-editor
+      - page-editor
+      - navigation-editor
+      - seo-editor
+      - feature-flag-editor
+    - backoffice
+      - products
+      - categories
+      - orders
+      - customers
+      - inventory
+      - media
+      - settings
+  - facades
+    - website
+    - builder
+    - backoffice
+    - platform
+  - integrations
+    - auth
+    - payment
+    - authorization
+  - theme
+    - tokens
+    - mappers
+    - runtime
+  - dynamic-renderer
+    - page-renderer
+    - section-renderer
+    - widget-host
+  - app.routes.ts
+  - app.config.ts
+  - app.ts
+  - app.html
+- assets
+  - mock
+    - bootstrap
+    - website
+    - builder
+    - backoffice
+
+## Foundation Phase Scope
+
+During Phase 1:
+
+- Create folder structure and placeholders only.
+- Do not create business feature implementations.
+- Keep app runnable and compilable.
+
+## Placement Rules
+
+- Contracts and interfaces go to shared models/contracts/types.
+- Pure visual components go to ui-library.
+- Configuration-driven blocks go to widgets.
+- Page composition logic goes to layouts and dynamic-renderer.
+- Domain orchestration belongs to facades.
+- Stable auth/payment integrations stay in integrations wrappers.

docs/architecture/foundation/Import-Boundary-Matrix.md

@@ -0,0 +1,38 @@
+# Import Boundary Matrix
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Allowed Import Matrix
+
+Legend:
+
+- Yes: Allowed
+- No: Forbidden
+- Limited: Allowed only via published contracts
+
+| From \ To | Core | Shared | UI Library | Widgets | Layouts | Pages | Features | Facades | Integrations |
+|---|---|---|---|---|---|---|---|---|---|
+| Core | Yes | Yes | No | No | No | No | No | No | Limited |
+| Shared | Yes | Yes | No | No | No | No | No | No | No |
+| UI Library | Shared only | Yes | Yes | No | No | No | No | No | No |
+| Widgets | Shared/Core contracts | Yes | Yes | Yes | No | No | No | Limited | No |
+| Layouts | Shared/Core contracts | Yes | Yes | Yes | Yes | No | No | Limited | No |
+| Pages | Shared/Core contracts | Yes | Yes | Yes | Yes | Yes | No | Yes | No |
+| Features | Shared/Core contracts | Yes | Yes | Yes | Yes | Yes | No direct feature-to-feature | Yes | Limited |
+| Facades | Shared/Core contracts | Yes | No | No | No | No | Limited | Yes | Yes |
+| Integrations | Shared/Core contracts | Yes | No | No | No | No | No | Limited | Yes |
+
+## Additional Constraints
+
+- Features cannot import other features directly.
+- Shared cannot import any feature, page, layout, widget, or UI layer.
+- UI Library cannot import facades, integrations, router, or HttpClient.
+- Core cannot import features.
+- Circular dependencies are forbidden in all directions.
+
+## Enforcement
+
+- Enforce with lint module boundaries.
+- Enforce with dependency graph checks in CI.
+- Merge blocked on violations.

docs/architecture/foundation/Naming-Conventions.md

@@ -0,0 +1,56 @@
+# Naming Conventions
+
+Status: Mandatory
+Date: 2026-07-03
+
+## General
+
+- Use clear domain-oriented names.
+- Prefer explicit names over abbreviations.
+- Keep naming consistent across Website, Builder, Backoffice.
+
+## Files and Folders
+
+- Folders: kebab-case.
+- TypeScript files: kebab-case with suffix.
+- Interfaces: PascalCase.
+- Types: PascalCase.
+- Enums: PascalCase.
+- Constants: UPPER_SNAKE_CASE for true constants.
+
+## Angular Artifacts
+
+- Component: name.component.ts
+- Container component: name.container.component.ts
+- Facade: name.facade.ts
+- Service: name.service.ts
+- Adapter: name.adapter.ts
+- Token: name.token.ts
+- Guard: name.guard.ts
+- Resolver: name.resolver.ts
+- Pipe: name.pipe.ts
+
+## Configuration Contracts
+
+- Bootstrap payload root: BootstrapConfig.
+- Domain segments named by function:
+  - TenantConfig
+  - BrandingConfig
+  - ThemeConfig
+  - FeatureFlagsConfig
+  - NavigationConfig
+  - PageConfig
+  - SectionConfig
+  - WidgetConfig
+
+## Event and Action Naming
+
+- Outputs: actionRequested, valueChanged, selectionChanged.
+- Facade commands: loadX, updateX, saveX, publishX.
+- Selectors/signals: xState, xViewModel, isXEnabled.
+
+## Prohibited Names
+
+- Generic names without domain meaning such as DataService or UtilsService.
+- Tenant-coded names in frontend source.
+- Brand-specific class names in reusable layers.

docs/architecture/foundation/README.md

@@ -0,0 +1,91 @@
+# Marketplace Platform Architecture Foundation
+
+Status: Approved
+Owner: Lead Software Architect
+Date: 2026-07-03
+
+## Purpose
+
+This folder defines the mandatory engineering governance for transforming this codebase into a reusable, configuration-driven, multi-tenant Marketplace Platform (Marketplace-as-a-Service).
+
+This repository is not treated as a single marketplace website.
+It is a platform runtime that must support unlimited tenants from one Angular application.
+
+## Platform Principles
+
+- One codebase, unlimited tenants.
+- Every tenant has three surfaces: Website, Builder, Backoffice.
+- Frontend contains no tenant-specific implementation code.
+- Tenant behavior is controlled by configuration loaded at bootstrap.
+- Authentication, payment, authorization behavior and contracts remain unchanged.
+- Prefer composition over inheritance.
+- Prefer configuration over conditionals.
+- No circular dependencies.
+- Shared and UI layers are feature-agnostic.
+
+## Non-Negotiable Constraints
+
+- Authentication behavior remains exactly as current implementation.
+- Payment API behavior remains exactly as current implementation.
+- Authorization behavior remains exactly as current implementation.
+- Existing authentication and payment API contracts cannot be changed.
+- Proven modules are reused, wrapped, and isolated, not redesigned.
+
+## Document Set
+
+### Architecture Decision Records
+
+- [ADR-001](adr/ADR-001-platform-model.md)
+- [ADR-002](adr/ADR-002-layered-feature-architecture.md)
+- [ADR-003](adr/ADR-003-import-boundaries-and-dependency-direction.md)
+- [ADR-004](adr/ADR-004-configuration-bootstrap-and-provider-abstraction.md)
+- [ADR-005](adr/ADR-005-dynamic-page-section-widget-rendering.md)
+- [ADR-006](adr/ADR-006-ui-component-purity-and-container-facade-pattern.md)
+- [ADR-007](adr/ADR-007-state-management-and-facade-boundaries.md)
+- [ADR-008](adr/ADR-008-theme-engine-and-design-token-runtime.md)
+- [ADR-009](adr/ADR-009-feature-flags-and-capability-guards.md)
+- [ADR-010](adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md)
+
+### Engineering Rule Documents
+
+- [Folder Blueprint](Folder-Blueprint.md)
+- [Import Boundary Matrix](Import-Boundary-Matrix.md)
+- [Dependency Rules](Dependency-Rules.md)
+- [Naming Conventions](Naming-Conventions.md)
+- [Coding Standards](Coding-Standards.md)
+- [Component Standards](Component-Standards.md)
+- [Service Standards](Service-Standards.md)
+- [Configuration Standards](Configuration-Standards.md)
+- [State Management Standards](State-Management-Standards.md)
+
+## Compliance
+
+All new work must comply with this foundation.
+If an implementation conflicts with these rules, implementation must be adjusted.
+If a rule must change, an ADR update is required first.
+
+## Mandatory Phase Order
+
+Implementation must proceed only in this order:
+
+1. Foundation structure only, app compiles.
+2. Shared interfaces and types only.
+3. Mocked configuration payloads only.
+4. ConfigService abstraction only.
+5. Theme engine.
+6. Dynamic rendering engine.
+7. Reusable widget library.
+8. Website from configuration.
+9. Builder from configuration domain.
+10. Backoffice from business domain.
+11. Backend documentation.
+
+For each phase:
+
+1. Explain what will be created.
+2. Explain why.
+3. List files to create.
+4. Explain dependencies.
+5. Implement only that phase.
+6. Verify build integrity.
+7. Stop and wait.

docs/architecture/foundation/Service-Standards.md

@@ -0,0 +1,36 @@
+# Service Standards
+
+Status: Mandatory
+Date: 2026-07-03
+
+## Service Categories
+
+- Domain Service: business operations and rules.
+- Integration Service: external API/system communication.
+- Platform Service: cross-cutting platform concerns.
+
+## Rules
+
+- Services must have one clear responsibility.
+- Services should expose typed contracts only.
+- Services should avoid UI-specific formatting.
+- Services should not depend on component classes.
+- Shared services must not depend on feature modules.
+
+## Facade Interaction
+
+- Components call facades.
+- Facades call services.
+- Services do not call UI components.
+
+## Stable Module Protection
+
+- Existing authentication, payment, authorization services remain behavior-compatible.
+- Wrap legacy stable behavior with adapters where needed.
+- No contract changes for auth/payment APIs.
+
+## Storage and Runtime Access
+
+- Browser storage access allowed only in approved service boundaries.
+- Prefer abstraction interfaces for storage access.
+- Never use storage APIs in UI components.

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.

docs/architecture/foundation/adr/ADR-001-platform-model.md

@@ -0,0 +1,38 @@
+# ADR-001: Platform Model and Tenancy Strategy
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+The existing repository has evolved from marketplace website delivery.
+The target product is Marketplace-as-a-Service with unlimited tenants on one runtime.
+
+## Decision
+
+Adopt a platform runtime model:
+
+- One Angular application serves all tenants.
+- Tenant identity is resolved by backend from request Host.
+- Frontend does not pass tenant id or project key.
+- Frontend starts by requesting GET /bootstrap.
+- Tenant-specific website, builder, and backoffice behavior derives from bootstrap configuration.
+
+## Consequences
+
+Positive:
+
+- Tenant onboarding becomes configuration-driven.
+- Eliminates tenant forks and branch divergence.
+- Strong separation of platform engine and tenant data.
+
+Negative:
+
+- Requires strict discipline against tenant conditionals in UI code.
+- Requires robust bootstrap schema governance.
+
+## Compliance Requirements
+
+- No environment-based tenant branching in presentation logic.
+- No tenant-specific routes hardcoded in feature components.
+- Tenant behavior is represented in typed configuration contracts.

docs/architecture/foundation/adr/ADR-002-layered-feature-architecture.md

@@ -0,0 +1,43 @@
+# ADR-002: Layered Feature Architecture with Single Responsibility
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+The platform must support Website, Builder, and Backoffice while keeping shared capabilities reusable and independent.
+
+## Decision
+
+Adopt the following architecture layers and responsibilities:
+
+- Core: bootstrap, app wiring, global policies, base adapters.
+- Shared: pure contracts, pure utilities, generic primitives.
+- UI Library: reusable presentational components only.
+- Widgets: configurable functional blocks built from UI components.
+- Layouts: page section composition and structural orchestration.
+- Pages: route containers mapping configuration to layouts/widgets.
+- Website: public commerce experience.
+- Builder: configuration editing domain.
+- Backoffice: business data management domain.
+
+Single responsibility is mandatory for each layer.
+
+## Consequences
+
+Positive:
+
+- Predictable layering and ownership.
+- Higher reuse across Website, Builder, and Backoffice.
+- Reduced accidental coupling.
+
+Negative:
+
+- Requires import boundary enforcement.
+- Requires upfront contracts before feature implementation.
+
+## Compliance Requirements
+
+- Shared and UI layers cannot depend on feature layers.
+- Feature layers interact through contracts/facades, not direct imports.
+- New artifacts must be placed in the correct layer folder.

docs/architecture/foundation/adr/ADR-003-import-boundaries-and-dependency-direction.md

@@ -0,0 +1,39 @@
+# ADR-003: Import Boundaries and Dependency Direction
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Without strict dependency direction, large Angular codebases accumulate circular dependencies and feature coupling that block reuse.
+
+## Decision
+
+Enforce one-way dependency flow:
+
+Website/Builder/Backoffice -> Pages -> Layouts -> Widgets -> UI Library -> Shared -> Core
+
+Additional constraints:
+
+- No circular dependencies.
+- No feature importing another feature directly.
+- Core does not depend on any feature.
+- Shared does not depend on features.
+- UI Library does not depend on features.
+
+## Consequences
+
+Positive:
+
+- Stable architecture evolution.
+- Easier testability and extraction.
+- Faster onboarding with clear module contracts.
+
+Negative:
+
+- Some existing direct imports must be replaced by contracts.
+
+## Compliance Requirements
+
+- Enforce via lint boundaries and dependency checks.
+- Violations block merge.

docs/architecture/foundation/adr/ADR-004-configuration-bootstrap-and-provider-abstraction.md

@@ -0,0 +1,36 @@
+# ADR-004: Configuration Bootstrap and Provider Abstraction
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Configuration must initially come from mock JSON and later from backend API without changing consumers.
+
+## Decision
+
+Introduce configuration provider abstraction behind ConfigService.
+
+- ConfigService is the only configuration entrypoint.
+- Consumers depend on typed ConfigService selectors only.
+- Provider implementation is swappable:
+  - MockBootstrapProvider
+  - ApiBootstrapProvider
+- Frontend calls GET /bootstrap when API provider is enabled.
+- Frontend does not pass tenant id.
+
+## Consequences
+
+Positive:
+
+- Source-agnostic configuration usage.
+- Mock-to-backend transition with minimal change surface.
+
+Negative:
+
+- Requires strict prohibition of direct JSON imports in components/services.
+
+## Compliance Requirements
+
+- No code outside ConfigService may load bootstrap JSON.
+- No page/widget/component may access configuration files directly.

docs/architecture/foundation/adr/ADR-005-dynamic-page-section-widget-rendering.md

@@ -0,0 +1,35 @@
+# ADR-005: Dynamic Page, Section, and Widget Rendering
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Platform websites must be generated from configuration. Hardcoded page composition blocks tenant scalability.
+
+## Decision
+
+Adopt dynamic rendering engine:
+
+- A page definition contains ordered sections.
+- A section contains ordered widgets.
+- WidgetHost resolves widget type through registry.
+- Registry-based resolution avoids renderer edits for every new widget.
+- Hero, Carousel, Header, Footer, and other blocks are widgets/layout entries from configuration.
+
+## Consequences
+
+Positive:
+
+- New tenant pages created by configuration.
+- Supports Builder-driven composition.
+
+Negative:
+
+- Requires robust schema validation.
+- Requires widget compatibility and versioning discipline.
+
+## Compliance Requirements
+
+- Page templates must not hardcode specific widget combinations.
+- Widget rendering must be data-driven from configuration contracts.

docs/architecture/foundation/adr/ADR-006-ui-component-purity-and-container-facade-pattern.md

@@ -0,0 +1,42 @@
+# ADR-006: UI Component Purity and Container-Facade Pattern
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Reusable platform components cannot contain business and integration concerns.
+
+## Decision
+
+Separate visual and business responsibilities:
+
+- UI components are presentational only.
+- Container components connect facades to UI components.
+- Facades own orchestration and use services.
+- Services handle IO and integration.
+
+UI component restrictions:
+
+- No HttpClient.
+- No localStorage/sessionStorage access.
+- No environment import.
+- No tenant awareness.
+- No authentication/payment logic.
+- No route logic.
+
+## Consequences
+
+Positive:
+
+- Maximum reuse and testability.
+- Supports widget library portability.
+
+Negative:
+
+- Requires refactoring of mixed legacy components.
+
+## Compliance Requirements
+
+- Components must use Inputs for data and Outputs for events.
+- Business behavior belongs to facades/containers only.

docs/architecture/foundation/adr/ADR-007-state-management-and-facade-boundaries.md

@@ -0,0 +1,33 @@
+# ADR-007: State Management and Facade Boundaries
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+State must be predictable and isolated by domain to support Website, Builder, and Backoffice without cross-domain leakage.
+
+## Decision
+
+Use facade-centered state management by bounded context:
+
+- Each feature domain exposes one or more facades.
+- Facades expose read models and command methods.
+- State is local to domain and projected as readonly selectors/signals.
+- Shared/global state is limited to platform concerns (configuration, theme, localization, session status).
+
+## Consequences
+
+Positive:
+
+- Clear ownership of state transitions.
+- Improved maintainability and testability.
+
+Negative:
+
+- Requires disciplined facade boundaries.
+
+## Compliance Requirements
+
+- Components do not mutate service internals directly.
+- Cross-domain communication is contract-based, not direct state access.

docs/architecture/foundation/adr/ADR-008-theme-engine-and-design-token-runtime.md

@@ -0,0 +1,32 @@
+# ADR-008: Theme Engine and Runtime Design Tokens
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Tenant branding must be configuration-driven and must not require tenant-specific code branches.
+
+## Decision
+
+Introduce theme engine based on runtime design tokens:
+
+- Branding, color palette, typography, spacing, icons, logos, favicon derive from configuration.
+- Theme tokens are applied at runtime through token service and CSS variable mapping.
+- Feature code consumes semantic tokens, not tenant constants.
+
+## Consequences
+
+Positive:
+
+- Tenant branding changes are configuration-only.
+- Removes environment-based visual branching.
+
+Negative:
+
+- Requires token schema governance and fallback policy.
+
+## Compliance Requirements
+
+- No tenant-specific style imports in feature components.
+- UI styling must resolve through semantic token set.

docs/architecture/foundation/adr/ADR-009-feature-flags-and-capability-guards.md

@@ -0,0 +1,32 @@
+# ADR-009: Feature Flags and Capability Guards
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Platform tenants have optional capabilities. Features cannot be assumed always present.
+
+## Decision
+
+Introduce capability model backed by bootstrap feature flags:
+
+- FeatureFlagService exposes tenant capabilities.
+- Routes, widgets, and actions are guarded by capability checks.
+- Missing capability must degrade gracefully with fallback behavior.
+
+## Consequences
+
+Positive:
+
+- One runtime supports variable tenant feature sets.
+- Reduces tenant branching and dead code.
+
+Negative:
+
+- Requires explicit defaults and fallback UX.
+
+## Compliance Requirements
+
+- Components and pages cannot assume optional feature availability.
+- Capability checks must be centralized, not scattered conditionals.

docs/architecture/foundation/adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md

@@ -0,0 +1,35 @@
+# ADR-010: Backward Compatibility for Authentication, Payment, and Authorization
+
+Status: Accepted
+Date: 2026-07-03
+
+## Context
+
+Authentication and payment flows are proven and contract-sensitive. Platform refactoring must not break existing integrations.
+
+## Decision
+
+Freeze behavior and contracts for:
+
+- Authentication flow.
+- Payment API interactions.
+- Authorization logic.
+
+Allow only encapsulation and integration-layer isolation, not contract redesign.
+
+## Consequences
+
+Positive:
+
+- Prevents regressions in critical commerce and access flows.
+- Enables architecture modernization around stable core behavior.
+
+Negative:
+
+- Some suboptimal legacy internals may remain until controlled replacement strategy is approved.
+
+## Compliance Requirements
+
+- Existing auth/payment request/response contracts remain unchanged.
+- Behavior-equivalent wrappers/adapters are allowed.
+- Any change requires explicit ADR and compatibility test evidence.