phase-1: scaffold platform foundation structure and architecture governance

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.