phase-1: scaffold platform foundation structure and architecture governance

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.