marketplaces/docs/architecture/foundation/adr/ADR-011-optional-seller-management-module.md

ADR-011: Optional Seller Management Module

Status: Accepted Date: 2026-07-26

Context

The platform today has a two-level hierarchy: Platform → Marketplace (tenant), per ADR-001. Some marketplaces will eventually need a third, optional level: individual Sellers operating storefronts within one marketplace (a marketplace-of-marketplaces / multi-vendor model). Not every marketplace needs this — most tenants today have none.

Seller Management must not become a second tenancy model. ADR-001 already established that tenant identity is backend-resolved from request Host and the frontend never passes or resolves tenant identity itself. Introducing sellers must not weaken that discipline or introduce a second, parallel resolution mechanism the frontend has to reason about.

Decision

Seller Management is an optional platform capability module, not a new tenancy tier equal to Marketplace:

Platform
  └── Marketplace (tenant)      — always present, resolved by backend (ADR-001)
        └── Seller (optional)   — 0..N per marketplace, resolved by backend

• Marketplace remains the sole primary tenant. A seller is a child scope of exactly one marketplace, never a sibling of Marketplace and never resolved independently of it.
• The frontend never resolves seller identity itself — same rule as tenant resolution (ADR-001). The backend decides whether the current request scope is marketplace-level or seller-level and reflects that decision in the bootstrap response.
• The frontend consumes bootstrap only. No new endpoint, header, or client-side resolution logic is introduced by this ADR. If a seller scope applies, BootstrapConfig.seller (see SellerConfig) is present; if not, it's absent. There is no other channel.
• Gated by a module flag, not scattered conditionals. The capability is controlled by one typed flag — BootstrapConfig.modules.sellerManagement. enabled (see PlatformModulesConfig) — checked in one place if/when seller-aware behavior is built, never as ad hoc if (tenant.id === 'x') or similar marketplace-specific conditionals anywhere in feature code. This follows the same capability-guard discipline ADR-009 already established for feature flags.

Backward Compatibility (non-negotiable)

• modules and seller are both optional fields on BootstrapConfig. Existing marketplaces whose bootstrap response never includes them are unaffected — untyped-absent is not a special case to handle, it's the default.
• DEFAULT_PLATFORM_MODULES_CONFIG defaults sellerManagement.enabled to false. A marketplace that has never heard of this feature, and a marketplace where the backend explicitly disables it, behave identically: no new routes, no new menu entries, no new API calls, no visual change.
• No existing BootstrapConfig field, route, guard, or component changes as a result of this ADR. This ADR adds types; it changes nothing that already runs.

Scope of this ADR

This ADR and its accompanying typed contracts (PlatformModulesConfig, SellerManagementModuleConfig, SellerConfig) are architecture only:

• No UI is introduced — no seller-facing pages, no admin seller-management screens, no navigation entries.
• No backend is implemented — no endpoints, no seller data model, no resolution logic.
• No business logic is introduced — no seller CRUD, no seller-scoped permissions, no seller onboarding flow.

Those are all future work, gated behind modules.sellerManagement.enabled, and each will need its own ADR/implementation pass once the module is actually being built out (routing strategy under a seller scope, admin UI, backend data model and resolution, permission model for seller-level roles). This ADR exists so that future work has a typed foundation to build on without retrofitting the platform/marketplace hierarchy after the fact.

Consequences

Positive:

• Marketplaces that don't need multi-vendor support pay zero cost — no new code path executes, no new field is even present in their bootstrap response.
• Future Seller Management work has a settled hierarchy and typed contract to build against instead of ad hoc per-feature decisions about where "seller" fits.
• Consistent with the platform's existing capability-guard discipline (ADR-009) — one flag, checked in one place, not scattered conditionals.

Negative:

• Adds two optional fields to BootstrapConfig that most of the codebase will never populate — acceptable, matches the existing pattern of several other optional bootstrap fields (header?, catalog?, layout?, etc.).
• Defers real design decisions (seller-scoped routing, seller admin permissions, seller data ownership) to whenever the module is actually implemented — intentional; this ADR does not pre-invent that design.

Compliance Requirements

• No component, facade, or service may branch on marketplace identity or seller identity directly. All seller-aware behavior, once built, must check modules.sellerManagement.enabled (or a capability-guard built on top of it) as the single gate.
• No frontend code may attempt to resolve which seller is active by itself (URL parsing, local storage, guessed convention, etc.) — that information only ever comes from BootstrapConfig.seller, backend-resolved, exactly like tenant resolution today.
• Any future work that adds seller-facing routes, UI, or backend calls must keep all of it inert and unreachable while modules.sellerManagement. enabled is false, with no exception.