Files

Architecture Governance / architecture (push) Has been cancelled

Details

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

5.9 KiB

Raw Blame History

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

Seller Management (optional, in preparation — not built)

Seller-Management.md — capability overview, start here
ADR-011 — decision record
Seller-Management-Diagrams.md — hierarchy, bootstrap gate, type diagram
Seller-Management-Domain-Models.md — typed models, optional sellerId fields
Seller-Management-UX-Review.md — UX/accessibility review of the Phase 1 UI
Seller-Management-Backoffice-Readiness-Audit.md — per-module scoping/permissions readiness audit
Seller-Management-Storefront-Audit.md — market.com/seller.market.com storefront readiness audit
Seller-Management-Backend-Migration-Plan.md — full backend migration plan, module-by-module, phased
Seller-Management-Final-Design-Review.md — principal-architect review, findings, verdict

Engineering Rule Documents

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.

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.

Mandatory Phase Order

Implementation must proceed only in this order:

Foundation structure only, app compiles.
Shared interfaces and types only.
Mocked configuration payloads only.
ConfigService abstraction only.
Theme engine.
Dynamic rendering engine.
Reusable widget library.
Website from configuration.
Builder from configuration domain.
Backoffice from business domain.
Backend documentation.

For each phase:

Explain what will be created.
Explain why.
List files to create.
Explain dependencies.
Implement only that phase.
Verify build integrity.
Stop and wait.

5.9 KiB Raw Blame History