marketplaces/docs/architecture/foundation/Seller-Management.md

Seller Management — Capability Documentation

Status legend used throughout this document:

• Implemented — exists in source on feature/seller-management-foundation today, verified (tsc, arch:check, or live browser test).
• Planned — has a typed contract or explicit ADR decision, but no code reads/writes it yet.
• Future — a concept named in this document for roadmap completeness only. No shape, contract, or decision exists yet. Do not build against this section without a new ADR.

This document is the entry point. Detail lives in its companion docs: ADR-011 (decision), Seller-Management-Diagrams.md (hierarchy/bootstrap-gate diagrams), Seller-Management-Domain-Models.md (every type, field by field), Seller-Management-UX-Review.md (Phase 1 UI review).

1. Overview

Seller Management is an optional platform capability that would let one marketplace host multiple independent sellers, each with their own inventory/orders/branding, under one centralized administration. It is not another tenant — a seller is a child scope beneath exactly one marketplace (ADR-011).

Implemented today: typed contracts for the whole hierarchy, a disabled- by-default feature flag, one Backoffice page that explains the capability and collects interest ("Request Access" / "Learn More"). Nothing else — no CRUD, no backend, no seller-facing UI, no checkout/order behavior change.

2. Architecture & Hierarchy — Implemented (types only)

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

Full diagram set: Seller-Management-Diagrams.md.

Rules (ADR-011, enforced by review, not yet by any lint rule): Marketplace is the sole primary tenant. Seller is a child scope, never a sibling tier. The frontend never resolves seller identity itself — same rule as tenant resolution. All seller-aware behavior must check one capability flag, never scattered marketplace/seller conditionals.

3. Marketplace — Implemented (existing, unchanged)

The marketplace is the existing TenantConfig (shared/models/config/tenant.model.ts) — resolved by the backend from request Host, exactly as before this work started. Seller Management adds a new MarketplaceRef (core/sellers/models/marketplace-ref.model.ts): a minimal {id, slug, name} view of a marketplace as seen from a seller record, not a replacement for TenantConfig.

4. Seller — Implemented (types only)

Seller (core/sellers/models/seller.model.ts): id, marketplace: MarketplaceRef, name, slug, status: SellerStatus, optional branding: SellerBranding, createdAt/updatedAt. No repository, gateway, facade, or UI reads or writes this type yet — it exists so future CRUD work has a settled shape instead of inventing one ad hoc.

Planned: a SellerRepository/SellerGateway pair following the same mock↔API DI-token pattern every other admin domain already uses (BACKEND.md §8). Future: the actual CRUD screens, list/detail pages, onboarding flow.

5. Roles & Permissions — Implemented (types only)

SellerPermissionRole (core/sellers/models/seller-permissions.model.ts): four values — marketplaceOwner, seller, sellerStaff, platformAdmin. This is a separate vocabulary from the existing AdminRole (Owner/ Manager/Support/ReadOnly, core/auth/models/permission.model.ts) — not merged, not wired into any guard. No authentication or authorization change exists anywhere in this work.

Planned: once a real permission model is designed, these roles gate seller-scoped routes/actions the same way AdminRole gates admin routes today (ADR-009 capability-guard pattern). Future: the actual permission-to-action mapping, custom/finer-grained roles per marketplace.

6. Future Roadmap

Feature Flags — Implemented (contract), Planned (real use)

BootstrapConfig.modules.sellerManagement.enabled (shared/models/config/platform-modules.model.ts), default false (DEFAULT_PLATFORM_MODULES_CONFIG). Implemented as a typed contract read by the Phase 1 page (admin-seller-management-page.component.ts); no backend sets it to true anywhere today, so it is always false in practice.

Bootstrap — Implemented (contract), Planned (real data)

BootstrapConfig.modules? and BootstrapConfig.seller? (SellerConfig, shared/models/config/seller.model.ts) — both optional, both absent in every real bootstrap response today. When a backend eventually resolves a seller scope, it populates seller; until then this field simply doesn't exist on the wire.

Future API — Future

No endpoint exists. When built, it should follow BACKEND.md's existing mock↔API-gateway pattern (§8) rather than a new convention — this is a statement of intent, not a designed contract. No URL, DTO, or status-code behavior is decided.

Seller Storefronts — Future

Concept: a seller-branded storefront view within a marketplace (e.g. a seller's own product listing page reachable from the marketplace). Not designed. No route, component, or URL scheme exists or is decided.

Seller Branding — Implemented (types only), Future (usage)

SellerBranding (core/sellers/models/seller-branding.model.ts): logo, banner, description, contacts, address, theme overrides — every field optional. Implemented as a type only. Nothing renders it, nothing falls back from it to marketplace branding — that precedence logic is Future work, not yet designed.

Seller Ownership — Implemented (schema only), Future (logic)

sellerId?: string added to Item (storefront), AdminProduct, and AdminOrder — optional, absent means marketplace-owned (every existing product/order today). No code reads or writes this field anywhere. Ownership rules, transfer, and enforcement are Future work.

Checkout Modes — Future

Concept: how checkout behaves when a cart contains items from multiple sellers (e.g. single combined checkout vs. per-seller checkout flows). Not designed. No decision exists on this; today every product is marketplace-owned and checkout has exactly one flow, unchanged by this work.

Unified Orders / Split Orders — Future

Concept: whether one customer purchase spanning multiple sellers becomes one order record or splits into one order per seller. Not designed. This is a real business decision (payments, refunds, and reporting all depend on the answer) with no default assumed — explicitly listed as an open question for whenever Seller Management moves past preparation.

7. Migration & Compatibility

Why existing marketplaces remain unchanged

• modules.sellerManagement.enabled defaults to false and no backend sets it — every marketplace today gets identical behavior whether the field is present-and-false or entirely absent from its bootstrap response.
• BootstrapConfig.modules and BootstrapConfig.seller are optional fields; no existing field's type changed.
• sellerId? on Item/AdminProduct/AdminOrder is optional; no consumer of any of these three types needed updating, verified by tsc --noEmit staying clean after each change.
• Zero components, facades, services, or routes branch on marketplace or seller identity anywhere in this work (ADR-011 compliance requirement) — there is no conditional to accidentally trigger.
• Every commit in this line of work was verified with tsc --noEmit, arch:check (import boundaries + circular deps), and — for the UI commits — a live browser pass, specifically to confirm no regression to existing pages.

8. Developer Notes

• All seller domain types live in core/sellers/models/ (mirrors core/products/models, core/auth/models). Extend there, not ad hoc in feature folders.
• When real seller-aware behavior is eventually built, gate it behind modules.sellerManagement.enabled in one place (a capability guard, ADR-009's pattern) — never scattered if checks on tenant/seller identity.
• The Phase 1 page (features/admin/seller-management/) is disposable — it exists to communicate the capability to merchants, not as a foundation to extend. Real seller CRUD UI should be planned fresh once the backend contract exists, not bolted onto this page.

9. Builder Notes

The Project Editor / Marketplace Builder has zero seller-awareness today. Its draft/publish model (localStorage-only, no backend write path per BACKEND.md §1.10) is entirely marketplace-scoped. If/when a seller needs their own builder-like surface (branding, storefront layout), it must be designed as its own ADR — do not assume the existing builder can be reused as-is for a seller scope without that review, since its facades and schema (ADR-005, ADR-007) were built assuming exactly one config document per marketplace.

10. Backend Notes

No backend implementation exists for any part of Seller Management. When work begins, follow BACKEND.md's established pattern exactly: a SellerRepository/SellerGateway behind a DI token, MockSellerGateway first, ApiSellerGateway swapped in later, same convention every other admin domain in this codebase already uses (BACKEND.md §8). The typed models in core/sellers/models/ are the DTO shapes to implement against — treat them as the contract, not a suggestion to redesign.

Diagrams

graph LR
    A["Types & feature flag<br/>(this + prior 3 commits)"] -->|Implemented| B["Phase 1 UI<br/>(Partners > Seller Management page)"]
    B -->|Implemented| C["Backend contract decisions<br/>(BACKEND.md gaps, own ADR)"]
    C -->|Future| D["Seller CRUD + real gateway"]
    D -->|Future| E["Seller Branding rendering<br/>+ Storefronts"]
    E -->|Future| F["Checkout Modes +<br/>Unified/Split Orders"]

    classDef done fill:#2e7d3222,stroke:#2e7d32,color:inherit;
    classDef future fill:#6b728022,stroke:#6b7280,color:inherit;
    class A,B done;
    class C,D,E,F future;

Rollout is strictly left-to-right — no stage after "Phase 1 UI" has started. See Seller-Management-Diagrams.md for the hierarchy and bootstrap-gate diagrams (unchanged, still accurate).