2026-07-03 01:26:30 +04:00
# 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 )
2026-07-26 20:15:40 +04:00
- [ADR-011 ](adr/ADR-011-optional-seller-management-module.md )
2026-07-03 01:26:30 +04:00
feat(sellers): typed domain models for future Seller Management - no logic, no API, no auth changes
Typed models only, per mission. Nothing outside the new files reads
or writes any of this yet.
New core/sellers/models/ (mirrors core/products/models,
core/auth/models convention):
- MarketplaceRef - minimal {id,slug,name} reference from a seller
back to its marketplace, distinct from bootstrap's TenantConfig.
- SellerStatus - 'pending'|'active'|'suspended'|'disabled', no
transition logic.
- SellerScope - {sellerId, marketplaceId}, domain-level counterpart
to BootstrapConfig.seller (SellerConfig from the ADR-011 pass).
- SellerBranding (+SellerContact/SellerAddress/SellerThemeOverrides)
- logo/banner/description/contacts/address/theme overrides, every
field optional. Marketplace branding/theme remain default;
nothing consumes this yet.
- SellerPermissionRole/SellerPermissions - marketplaceOwner/seller/
sellerStaff/platformAdmin. Separate vocabulary from the existing
AdminRole (core/auth/models/permission.model.ts) - not merged, not
wired into any guard, zero auth behavior change.
- Seller - the eventual entity, composed from the above.
Changed (optional-only, verified backward compatible):
- Item (models/item.model.ts) gained sellerId?: string
- AdminProduct (features/admin/products/models/) gained
sellerId?: string
- AdminOrder (features/admin/orders/models/) gained sellerId?: string
Absent means marketplace-owned in every case, exactly like every
existing product/order today. No consumer of any of these three
models needed updating. AdminOrderItem (per-line-item ownership) and
the existing PermissionsConfig/AdminRole system were deliberately not
touched - out of scope for this pass.
Added docs/architecture/foundation/Seller-Management-Domain-Models.md
documenting every new type, every changed field, and the explicit
non-goals list. Linked from the foundation README alongside ADR-011
and the diagrams doc.
tsc --noEmit clean, arch:check (boundaries + cycles) clean.
2026-07-26 21:55:11 +04:00
### Seller Management (optional, in preparation — not built)
- [ADR-011 ](adr/ADR-011-optional-seller-management-module.md ) — decision record
- [Seller-Management-Diagrams.md ](Seller-Management-Diagrams.md ) — hierarchy, bootstrap gate, type diagram
- [Seller-Management-Domain-Models.md ](Seller-Management-Domain-Models.md ) — typed models, optional sellerId fields
fix(admin): Seller Management UX review - a11y label fix, icon list, review doc
Reviewed the Phase 1 UI against every other Backoffice page. Found and
fixed 2 real issues; everything else verified already consistent
(built entirely from shared components, so hover/focus/dialog-a11y/
dark-readiness/contrast come from those components, not reinvented).
Fixed:
- Message textarea had no id/aria-describedby wiring (app-input
self-wires this via injected FormFieldContext; the raw textarea -
no dedicated textarea component exists yet - never got it, so the
visible label's `for` pointed nowhere). Added explicit aria-label
bound to the same translation key as the visible label.
- Learn More dialog's feature list would render native browser
bullets (no global list-style reset exists outside details>summary
in styles.scss). Replaced with checkCircle icon + text rows,
consistent with how the rest of the app pairs icons with list/status
meaning.
Added docs/architecture/foundation/Seller-Management-UX-Review.md
documenting both fixes plus everything checked and confirmed already
consistent (empty-state usage, icon reuse, translations completeness
across en/ru/hy, responsive at 1280px/375px, dialog a11y verified via
accessibility tree not assumed).
tsc --noEmit clean, arch:check (boundaries + cycles) clean. Live-
verified: Learn More dialog shows all 6 items each with an icon
(confirmed via DOM query), textarea aria-label confirmed
"Сообщение", no console errors.
2026-07-26 22:07:14 +04:00
- [Seller-Management-UX-Review.md ](Seller-Management-UX-Review.md ) — UX/accessibility review of the Phase 1 UI
feat(sellers): typed domain models for future Seller Management - no logic, no API, no auth changes
Typed models only, per mission. Nothing outside the new files reads
or writes any of this yet.
New core/sellers/models/ (mirrors core/products/models,
core/auth/models convention):
- MarketplaceRef - minimal {id,slug,name} reference from a seller
back to its marketplace, distinct from bootstrap's TenantConfig.
- SellerStatus - 'pending'|'active'|'suspended'|'disabled', no
transition logic.
- SellerScope - {sellerId, marketplaceId}, domain-level counterpart
to BootstrapConfig.seller (SellerConfig from the ADR-011 pass).
- SellerBranding (+SellerContact/SellerAddress/SellerThemeOverrides)
- logo/banner/description/contacts/address/theme overrides, every
field optional. Marketplace branding/theme remain default;
nothing consumes this yet.
- SellerPermissionRole/SellerPermissions - marketplaceOwner/seller/
sellerStaff/platformAdmin. Separate vocabulary from the existing
AdminRole (core/auth/models/permission.model.ts) - not merged, not
wired into any guard, zero auth behavior change.
- Seller - the eventual entity, composed from the above.
Changed (optional-only, verified backward compatible):
- Item (models/item.model.ts) gained sellerId?: string
- AdminProduct (features/admin/products/models/) gained
sellerId?: string
- AdminOrder (features/admin/orders/models/) gained sellerId?: string
Absent means marketplace-owned in every case, exactly like every
existing product/order today. No consumer of any of these three
models needed updating. AdminOrderItem (per-line-item ownership) and
the existing PermissionsConfig/AdminRole system were deliberately not
touched - out of scope for this pass.
Added docs/architecture/foundation/Seller-Management-Domain-Models.md
documenting every new type, every changed field, and the explicit
non-goals list. Linked from the foundation README alongside ADR-011
and the diagrams doc.
tsc --noEmit clean, arch:check (boundaries + cycles) clean.
2026-07-26 21:55:11 +04:00
2026-07-03 01:26:30 +04:00
### 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.
2026-07-09 02:29:12 +04:00
## Sprint 11.5 Standardization Audit (2026-07-09)
Platform-wide standardization was executed before Admin Platform work.
### Completed Standardization
- Verified and enforced container/facade/domain/infrastructure boundaries across active website features.
- Removed remaining legacy variant naming in application-layer templates/styles.
- Removed duplicate legacy search-history implementation in catalog feature module.
- Standardized design-token surface with explicit spacing, radius, shadow, and transition tokens.
- Added widget metadata support for title/subtitle/visibility/layout/animation/style/permissions in shared contracts and dynamic rendering path.
- Converted remaining identified hardcoded UI strings in audited runtime pages/components to translation keys.
### Bootstrap/Configuration Gaps Identified
- Widget permission model supports auth gating but role/permission enforcement is limited by current auth session shape (no role list in session model).
- Popular search defaults are currently facade-local and should be moved to bootstrap-configurable catalog search settings.
- Storage key naming conventions for local persistence are platform-scoped but still static constants; optional bootstrap override could improve tenant isolation.
### Validation Baseline
- Build and architecture checks are required for acceptance of this sprint.
- Final details and file-level changes are tracked in `Platform-Standardization-Report.md` .
2026-07-03 01:26:30 +04:00
## 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.
