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)
docs: Seller Management capability documentation - Implemented/Planned/Future
Master entry-point doc (Seller-Management.md) consolidating everything
built across the prior 4 commits (ADR-011, domain models, Phase 1 UI,
UX review) plus the full roadmap, with every section explicitly
tagged Implemented / Planned / Future so nothing reads as built that
isn't.
Covers: Overview, Architecture & Hierarchy, Marketplace, Seller,
Roles & Permissions, Feature Flags, Bootstrap, Future API, Seller
Storefronts, Seller Branding, Seller Ownership, Checkout Modes,
Unified/Split Orders, Migration & Compatibility (why existing
marketplaces stay unchanged, with the concrete verification evidence
for each claim), Developer Notes, Builder Notes, Backend Notes.
Explicitly marked Future (not designed, no shape decided) rather than
documented as if real: the API surface, seller storefronts, checkout
modes, and the unified-vs-split-order decision - none of these have
any code or ADR behind them yet, unlike the typed models/feature flag/
Phase 1 UI which are genuinely Implemented.
Added a rollout-stage diagram (types+flag -> Phase 1 UI -> backend
decisions -> CRUD -> branding/storefronts -> checkout modes) showing
work stops after "Phase 1 UI" today. Linked as the entry point from
docs/architecture/foundation/README.md and docs/PROJECT_INDEX.md,
ahead of ADR-011/diagrams/domain-models/UX-review which stay as
detail references.
No code changed.
2026-07-26 22:13:15 +04:00
- [Seller-Management.md ](Seller-Management.md ) — capability overview, start here
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
- [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
docs: Backoffice readiness audit for future Seller Management
Audit only, no code changed - every fact gathered by reading current
facades/gateways/components on this branch, not assumed. Covers all
13 admin modules (Dashboard, Products, Categories, Orders, Customers,
Users, Analytics, Reviews/Moderation, Media, CMS, Builder, Settings,
Monitoring, Transactions).
Per module: answers the 3 readiness questions (does Marketplace Owner
see everything / would Seller see only their own / would Seller Staff
be limited), documents where a future scope would be injected (an
existing method/interface parameter to extend - no "if seller" checks
introduced anywhere), lists components that currently assume global
ownership, and classifies Ready / Needs scope / Needs permissions /
Needs API change.
Key findings:
- Only 3 of 13 gateways (Categories, Dashboard-metrics, Media) are
DI-token-swappable today; everything else needs that seam added
first, independent of seller scoping.
- Orders is the load-bearing blocker: Customers, Transactions, and
half of Analytics all derive from its same unscoped full-fetch order
list, and AdminOrderItem has no per-item seller attribution at all -
the concrete gap behind Seller-Management.md's open Unified-vs-Split-
Orders question.
- Users already carries an AdminUserScope/AdminRole concept (label-
only today) - the natural future home for the Marketplace Owner/
Seller/Seller Staff/Platform Admin role vocabulary.
- CMS/Static Pages and Builder/Project Editor are structurally not
about data scoping at all (marketplace-wide content, single global
config document respectively) - seller-level work there is new
product surface, not an extension.
- No admin module anywhere does role-based hiding of buttons or data
today - confirmed, not assumed.
Linked from docs/architecture/foundation/README.md alongside the
other Seller Management docs.
2026-07-26 22:22:22 +04:00
- [Seller-Management-Backoffice-Readiness-Audit.md ](Seller-Management-Backoffice-Readiness-Audit.md ) — per-module scoping/permissions readiness audit
docs: Storefront audit for market.com/seller.market.com compatibility
Audit only, no code changed - facts gathered by reading current
source (routes, containers, header/footer, SeoService), not assumed.
Covers Homepage, Categories, Products, Search, Favorites, Cart,
Checkout, Reviews, SEO, Breadcrumbs, Header, Footer.
Core finding: tenant resolution is already entirely backend-side by
request Host (ADR-001) - the frontend just consumes whatever bootstrap
comes back for whatever hostname it's running on. A seller subdomain
is architecturally closer to already working than any part of the
Backoffice audit found; the real gaps are all about whether the
*data* rendered carries a seller-aware value, not about routing/
hosting.
Key findings:
- Canonical URLs already correct today - SeoService.siteUrl derives
from location.origin dynamically, not hardcoded. Nothing to change.
- Header/Footer/SEO branding all read through one shared facade
(UiRuntimeFacade.reloadFromBootstrap()) - a single future injection
point that would cascade to all three for free, rather than three
separate fixes.
- SeoService.setItemMeta() (per-product OG/canonical tags) is defined
but never called anywhere in the codebase today - a pre-existing
dead hook, unrelated to seller-scoping but blocking any future
per-product/per-seller SEO work until wired.
- No dedicated breadcrumb component/service exists anywhere in the
storefront - the only breadcrumb logic in the app is one local
signal in catalog-container.component.ts.
- Checkout is not a separate route - it's an inline popup flow in
cart.component.ts, with no multi-vendor/multi-seller cart concept
at all. This is where Checkout Modes and Unified/Split Orders (both
marked Future in Seller-Management.md) would actually need to land.
- Structured data (JSON-LD) and sitemap generation don't exist for
anyone today, marketplace or seller - net-new work either way, not
seller-specific gaps.
- One pre-existing, unrelated issue noted in passing: og:locale is
hardcoded 'ru_RU' in SeoService - flagged, not fixed (out of scope).
Linked from docs/architecture/foundation/README.md alongside the
other Seller Management docs.
2026-07-26 22:32:41 +04:00
- [Seller-Management-Storefront-Audit.md ](Seller-Management-Storefront-Audit.md ) — `market.com` /`seller.market.com` storefront readiness audit
docs: Backend Migration Plan for Seller Management
Documentation only, no code. Synthesizes the 3 prior audits
(Seller-Management.md, the Backoffice readiness audit, the Storefront
audit) plus BACKEND.md SS11 into one migration plan covering all 17
requested modules: Authentication, Authorization, Bootstrap, Products,
Categories, Orders, Payments, Transactions, Reviews, Analytics, Media,
Search, CMS, Builder, Settings, Notifications, Emails, Audit Logs.
Per module: current behavior, future behavior, migration strategy,
backward compatibility, risk, effort, and an endpoint classification
(No change / Minor change / Major change / New endpoint) grounded in
facts already established in the prior audits - no new exploration,
no invented specifics.
Headline finding: Orders (the Unified-vs-Split-Orders decision) is the
single highest-risk, most consequential item in the whole plan -
payments/refunds/reporting all depend on it, and it can't be resolved
by an additive field the way every other domain's seller-scoping can.
Payments stays untouched (ADR-010, frozen) under the Unified path;
only Split Orders would ever touch the payment flow, and only then
with the same scrutiny the original frozen implementation got.
Cross-cutting sections included per mission: Database changes
(one nullable seller_id column touches existing tables, everything
else is new tables - no NOT NULL migration ever required), Permission
changes, Caching (bootstrap cache key must include resolved seller
identity), Indexes, Security (seller-to-seller isolation treated with
tenant-isolation rigor), Performance, API Versioning (ties to the
already-open BACKEND.md SS2.10 decision), Migration order (14 numbered
dependency steps), and 6 recommended implementation phases (A:
Foundation through F: Operational polish).
Every phase explicitly re-asserts the non-negotiable constraint:
modules.sellerManagement.enabled=false must show zero behavioral
difference before/after each phase ships.
Linked from docs/architecture/foundation/README.md alongside the
other Seller Management docs.
2026-07-26 22:49:07 +04:00
- [Seller-Management-Backend-Migration-Plan.md ](Seller-Management-Backend-Migration-Plan.md ) — full backend migration plan, module-by-module, phased
docs+fix: Final design review of Seller Management - one real bug found and fixed
Principal-architect-level review of the entire Seller Management body
of work (7 prior docs + all touched code), verified against fresh
tsc --noEmit and arch:check runs, not recalled from memory.
Real bug found and fixed (in scope per this mission's "unless
absolutely required" carve-out - a one-line correctness fix to
already-committed code, not new feature work):
AdminSellerManagementPageComponent.sellerManagementEnabled read the
bootstrap snapshot once via a plain signal() at construction, not
reactively via bootstrapRevision() the way UiRuntimeFacade/SeoService
both correctly do elsewhere in this codebase. Fixed to computed() keyed
on bootstrapRevision(). Currently invisible (flag is always false,
signal was never even read in the template) but would have gone stale
the moment bootstrap ever reloaded with the flag true. tsc clean after
the fix.
Findings documented in Seller-Management-Final-Design-Review.md (no
Critical/High severity found anywhere):
- Medium: SellerConfig (bootstrap wire shape) and Seller/SellerBranding
(domain entity) are two unreconciled type hierarchies for the same
concept - self-flagged already in BACKEND.md SS11.6, restated here as
an independently-confirmed finding rather than letting it drift.
- Medium: no reusable capability-guard abstraction exists anywhere in
the codebase, despite ADR-009/ADR-011 both prescribing "check the
flag in one place" - ADR-009's own described FeatureFlagService was
never built. Fine with one consumer, a real drift risk the moment a
second one needs the same check.
- Medium: the flag's true branch has never been exercised, even
manually - every verification claim in this whole body of work was
tested at the flag's real value (false).
- Low/nice-to-have: sellerId typed as bare string instead of the UUID
alias used everywhere else in the new sellers domain; MarketplaceRef
vs TenantConfig overlap (deliberate, documented, but worth watching);
documentation-to-code ratio (8 docs, zero backend bytes) carries a
consolidation-burden risk, especially the Unified/Split-Orders
question restated independently in 4 different docs.
- Explicitly checked for and did NOT find: circular dependencies,
scattered tenant/seller conditionals, over-engineering relative to
the typed-models-only mandate, or any auth/payment code touched.
Verdict: not an unqualified "ready for implementation" - two Medium
findings should be resolved by decision/small build before real
backend work starts, not because they block anything today but
because both compound in cost the longer they're left unresolved.
Everything actually built (typed foundation, disabled-by-default flag,
Phase 1 UI, plus the bug this review fixed) is solid and ready to
stay exactly as-is. No Critical or High-severity issue found anywhere.
2026-07-26 22:56:40 +04:00
- [Seller-Management-Final-Design-Review.md ](Seller-Management-Final-Design-Review.md ) — principal-architect review, findings, verdict
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.
