f6045a07b2
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
- docs/backend/BACKEND-HANDOFF.md: single entry point for a backend dev - reading order, verified infrastructure state (nginx running, Postgres inactive, no API on :8080, no TLS, no DNS automation, no CI runner), auth surface, and the day-one setup that is still outstanding - docs/PACKAGES-USAGE.md: install, required DI providers, full exported API for both auth mechanisms, and how to ship a package change - PACKAGE-EXTRACTION.md now covers build/release/infra only and points at the usage guide; CI section reflects the two real workflows Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
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 |
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. SeeBACKEND-API-REFERENCE.mdfor 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 is still unanswered (Sprint 0.1). Every contract above is ready to hand to whoever builds it — that person/team just hasn't been named yet.