diff --git a/docs/architecture/foundation/Coding-Standards.md b/docs/architecture/foundation/Coding-Standards.md new file mode 100644 index 0000000..bb5e405 --- /dev/null +++ b/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? diff --git a/docs/architecture/foundation/Component-Standards.md b/docs/architecture/foundation/Component-Standards.md new file mode 100644 index 0000000..74a9bdd --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Configuration-Standards.md b/docs/architecture/foundation/Configuration-Standards.md new file mode 100644 index 0000000..7ce5208 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Dependency-Rules.md b/docs/architecture/foundation/Dependency-Rules.md new file mode 100644 index 0000000..236767c --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Folder-Blueprint.md b/docs/architecture/foundation/Folder-Blueprint.md new file mode 100644 index 0000000..f3df1af --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Import-Boundary-Matrix.md b/docs/architecture/foundation/Import-Boundary-Matrix.md new file mode 100644 index 0000000..2a31a73 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Naming-Conventions.md b/docs/architecture/foundation/Naming-Conventions.md new file mode 100644 index 0000000..9c92183 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/README.md b/docs/architecture/foundation/README.md new file mode 100644 index 0000000..6e3d2fc --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/Service-Standards.md b/docs/architecture/foundation/Service-Standards.md new file mode 100644 index 0000000..74b3136 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/State-Management-Standards.md b/docs/architecture/foundation/State-Management-Standards.md new file mode 100644 index 0000000..7628e05 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-001-platform-model.md b/docs/architecture/foundation/adr/ADR-001-platform-model.md new file mode 100644 index 0000000..87eb13a --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-002-layered-feature-architecture.md b/docs/architecture/foundation/adr/ADR-002-layered-feature-architecture.md new file mode 100644 index 0000000..7dccf6d --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-003-import-boundaries-and-dependency-direction.md b/docs/architecture/foundation/adr/ADR-003-import-boundaries-and-dependency-direction.md new file mode 100644 index 0000000..b027684 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-004-configuration-bootstrap-and-provider-abstraction.md b/docs/architecture/foundation/adr/ADR-004-configuration-bootstrap-and-provider-abstraction.md new file mode 100644 index 0000000..a678048 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-005-dynamic-page-section-widget-rendering.md b/docs/architecture/foundation/adr/ADR-005-dynamic-page-section-widget-rendering.md new file mode 100644 index 0000000..3abdbc3 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-006-ui-component-purity-and-container-facade-pattern.md b/docs/architecture/foundation/adr/ADR-006-ui-component-purity-and-container-facade-pattern.md new file mode 100644 index 0000000..b6e9f43 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-007-state-management-and-facade-boundaries.md b/docs/architecture/foundation/adr/ADR-007-state-management-and-facade-boundaries.md new file mode 100644 index 0000000..f01dc70 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-008-theme-engine-and-design-token-runtime.md b/docs/architecture/foundation/adr/ADR-008-theme-engine-and-design-token-runtime.md new file mode 100644 index 0000000..66c7d58 --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-009-feature-flags-and-capability-guards.md b/docs/architecture/foundation/adr/ADR-009-feature-flags-and-capability-guards.md new file mode 100644 index 0000000..db4c36d --- /dev/null +++ b/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. diff --git a/docs/architecture/foundation/adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md b/docs/architecture/foundation/adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md new file mode 100644 index 0000000..80c20e4 --- /dev/null +++ b/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. diff --git a/src/app/core/bootstrap/loaders/.gitkeep b/src/app/core/bootstrap/loaders/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/bootstrap/providers/.gitkeep b/src/app/core/bootstrap/providers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/bootstrap/validators/.gitkeep b/src/app/core/bootstrap/validators/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/config/.gitkeep b/src/app/core/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/error-handling/.gitkeep b/src/app/core/error-handling/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/guards/.gitkeep b/src/app/core/guards/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/interceptors/.gitkeep b/src/app/core/interceptors/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/core/runtime/.gitkeep b/src/app/core/runtime/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/dynamic-renderer/page-renderer/.gitkeep b/src/app/dynamic-renderer/page-renderer/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/dynamic-renderer/section-renderer/.gitkeep b/src/app/dynamic-renderer/section-renderer/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/dynamic-renderer/widget-host/.gitkeep b/src/app/dynamic-renderer/widget-host/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/facades/backoffice/.gitkeep b/src/app/facades/backoffice/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/facades/builder/.gitkeep b/src/app/facades/builder/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/facades/platform/.gitkeep b/src/app/facades/platform/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/facades/website/.gitkeep b/src/app/facades/website/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/categories/.gitkeep b/src/app/features/backoffice/categories/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/customers/.gitkeep b/src/app/features/backoffice/customers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/inventory/.gitkeep b/src/app/features/backoffice/inventory/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/media/.gitkeep b/src/app/features/backoffice/media/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/orders/.gitkeep b/src/app/features/backoffice/orders/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/products/.gitkeep b/src/app/features/backoffice/products/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/backoffice/settings/.gitkeep b/src/app/features/backoffice/settings/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/builder/feature-flag-editor/.gitkeep b/src/app/features/builder/feature-flag-editor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/builder/navigation-editor/.gitkeep b/src/app/features/builder/navigation-editor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/builder/page-editor/.gitkeep b/src/app/features/builder/page-editor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/builder/seo-editor/.gitkeep b/src/app/features/builder/seo-editor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/builder/theme-editor/.gitkeep b/src/app/features/builder/theme-editor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/website/cart/.gitkeep b/src/app/features/website/cart/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/website/catalog/.gitkeep b/src/app/features/website/catalog/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/website/checkout/.gitkeep b/src/app/features/website/checkout/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/features/website/product/.gitkeep b/src/app/features/website/product/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/integrations/auth/.gitkeep b/src/app/integrations/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/integrations/authorization/.gitkeep b/src/app/integrations/authorization/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/integrations/payment/.gitkeep b/src/app/integrations/payment/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/layouts/containers/.gitkeep b/src/app/layouts/containers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/layouts/sections/.gitkeep b/src/app/layouts/sections/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/layouts/shells/.gitkeep b/src/app/layouts/shells/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/pages/backoffice/.gitkeep b/src/app/pages/backoffice/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/pages/builder/.gitkeep b/src/app/pages/builder/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/pages/public/.gitkeep b/src/app/pages/public/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/constants/.gitkeep b/src/app/shared/constants/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/contracts/.gitkeep b/src/app/shared/contracts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/enums/.gitkeep b/src/app/shared/enums/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/models/api/.gitkeep b/src/app/shared/models/api/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/models/config/.gitkeep b/src/app/shared/models/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/models/domain/.gitkeep b/src/app/shared/models/domain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/models/ui/.gitkeep b/src/app/shared/models/ui/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/types/.gitkeep b/src/app/shared/types/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/shared/utils/.gitkeep b/src/app/shared/utils/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/theme/mappers/.gitkeep b/src/app/theme/mappers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/theme/runtime/.gitkeep b/src/app/theme/runtime/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/theme/tokens/.gitkeep b/src/app/theme/tokens/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/ui-library/atoms/.gitkeep b/src/app/ui-library/atoms/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/ui-library/directives/.gitkeep b/src/app/ui-library/directives/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/ui-library/molecules/.gitkeep b/src/app/ui-library/molecules/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/ui-library/organisms/.gitkeep b/src/app/ui-library/organisms/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/ui-library/pipes/.gitkeep b/src/app/ui-library/pipes/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/widgets/containers/.gitkeep b/src/app/widgets/containers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/widgets/contracts/.gitkeep b/src/app/widgets/contracts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/widgets/registry/.gitkeep b/src/app/widgets/registry/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app/widgets/ui/.gitkeep b/src/app/widgets/ui/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/assets/mock/backoffice/.gitkeep b/src/assets/mock/backoffice/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/assets/mock/bootstrap/.gitkeep b/src/assets/mock/bootstrap/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/assets/mock/builder/.gitkeep b/src/assets/mock/builder/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/assets/mock/website/.gitkeep b/src/assets/mock/website/.gitkeep new file mode 100644 index 0000000..e69de29