marketplaces/docs/backend

Backend Contracts Index — Product Plan v3.1

New here? Start with BACKEND-HANDOFF.md — reading order, current infrastructure state, auth surface, and what a working dev environment still needs.

Implementing tenant routing/nginx? TENANT-API-DOMAIN-HANDOFF.md is the final host normalization, CORS, TLS, reverse-proxy, CI-secret, and acceptance contract.

Want every endpoint in one place? FRONTEND-API-SURFACE-COMPLETE.md — the final handoff doc. Generated directly from source, all 90 endpoints the frontend currently calls plus 3 response-shape additions on existing endpoints, marked Specified / Inferred / Undocumented against the contracts below. Use it to see gaps across all contracts at once; use the individual Phase/Track docs for full entity shapes and invariants.

This directory is the complete set of wire contracts for building the backend behind Product Plan v3.1. Each doc specifies entities, endpoints, and invariants only — never DB schema or service boundaries, which stay backend's own call.

Read order matches build order. Every doc after Phase 1 depends on the ones before it (noted at the top of each). All Sprint 0.1 decisions referenced throughout were answered 2026-08-17 — see PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md Sprint 0.1 for the full record.

Launch-gate phases (P0 — required before production)

Doc	Covers	Status
PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md	Money model, FX quote, price snapshot, server-authoritative checkout amount, payment state machine	Ready
PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md	Canonical Order/OrderLine/Fulfillment (unified multi-seller), event bus, Notification Center	Ready
PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md	Product/Offer split, inventory/reservations, publish-time executability	Ready
PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md	Generic external-order connector framework (no fixed marketplace list)	Ready

Post-launch-gate phases (P1/P2)

Doc	Covers	Status
PHASE-5-SELLER-PORTAL-CONTRACT.md	Seller org/user/membership, seller-scoped order/fulfillment views	Ready
PHASE-6-CART-CHECKOUT-CONTRACT.md	Server-owned cart, checkout session	Ready
PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md	Refunds, reconciliation, settlements	Ready
PHASE-8-IDENTITY-MESSAGING-CONTRACT.md	Customer identity, VK ID (built first), OTP, MAX/Telegram bots, Notification Orchestrator	Ready
PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md	Marketplace registry, Hostinger DNS automation, publish/revision model	Ready
PHASE-10-CONTENT-MODULES-CONTRACT.md	Gorbushka-class mall/directory content entities	Ready, lowest priority

Cross-cutting tracks

Doc	Covers	Status
TRACK-A-ANALYTICS-CONTRACT.md	Event pipeline, funnel, operational/quality metrics, synthetic-traffic separation	Ready — start alongside Phase 1, longest lead time
TRACK-S-SECURITY-RBAC-CONTRACT.md	17 roles/3 scopes, enforcement, audit log, secrets, rate limiting, step-up auth	Ready — gates the launch
PARTNER-PROVISIONING-API-CONTRACT.md	Inbound partner API: merchant hierarchy provisioning, idempotency, public-key credentials, payment routing context	Draft — mapping decided, needs Company/Project entities

What is deliberately not in this directory

• API namespace migration — Sprint 0.1 decision: new endpoints only use /api/v2/... etc; legacy endpoints (/cart, /orders, /items) are not being migrated as part of this contract set. See BACKEND-API-REFERENCE.md for the current live surface.
• Per-connector adapters (Ozon, Wildberries, etc.) — Sprint 0.1 decision: no fixed list. Phase 4 §8 is the onboarding runbook; each partner's adapter is written when that partner is actually onboarded.
• Additional payment providers (wallets, BNPL) — open business decision, not yet made. Phase 7 §4.

One open item across all of these

Backend ownership — answered 2026-08-18. A separate backend developer implements against these contracts. This repository's team owns the frontend and owns this contract set — the docs here are the handoff surface between the two, so a change to any contract is a change both sides must see. Keep them current; they are not a one-time deliverable.