docs(backend): consolidate all backend contracts into one file
Some checks failed
Architecture Governance / architecture (push) Has been cancelled

Collapses the entire docs/backend/ set - Phase 1-10, Track A/S, the
partner API, the two handoffs, the frontend surface inventory, and the
harvest requirements - into a single source of truth,
docs/backend/BACKEND-INTEGRATION.md.

Every contract's entities, endpoints, and invariants are preserved,
reorganised by domain rather than by sprint. The nine release
invariants, the FH-* harvest mechanisms, the RBAC/audit/secrets
cross-cutting rules, the tenant-routing infra contract, the 15
acceptance tests, build order, dev setup, and open decisions are all in
the one file, with a change log (§14) at the bottom.

The file opens with the maintenance rule: any new backend need, contract
change, or shipped item updates this file in the same change - the
affected section and the change log. No new backend .md files.

Inbound links from BACKEND-API-REFERENCE, the ADRs, the fork docs,
DEPLOYMENT, PACKAGES-USAGE, the delivery plan, and e2e/README are
repointed at the single doc (section anchors collapse to the file; the
prose section refs remain as context). Also recorded the rule in the
repo CLAUDE.md.

17 backend docs removed, 1 added. No implementation changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
sdarbinyan
2026-08-22 16:15:58 +04:00
parent 52fb52888f
commit d44565fae9
29 changed files with 522 additions and 3146 deletions

View File

@@ -17,13 +17,13 @@ Their request arrived written in their own vocabulary. Building against that voc
Three facts about our current model made the ask non-trivial:
1. Nothing exists above `Marketplace` ([Phase 9](../../backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)). No company, no project.
2. Payments carry no store dimension ([Phase 1](../../backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §6). Reconciliation can reconstruct *why* an amount was charged but not *who for*.
3. We have no partner-facing write API at all. [Phase 4](../../backend/PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md) is outbound/ingest — the opposite direction.
1. Nothing exists above `Marketplace` ([Phase 9](../../backend/BACKEND-INTEGRATION.md)). No company, no project.
2. Payments carry no store dimension ([Phase 1](../../backend/BACKEND-INTEGRATION.md) §6). Reconciliation can reconstruct *why* an amount was charged but not *who for*.
3. We have no partner-facing write API at all. [Phase 4](../../backend/BACKEND-INTEGRATION.md) is outbound/ingest — the opposite direction.
## Decision
Build one generic partner provisioning API. Contract: [PARTNER-PROVISIONING-API-CONTRACT.md](../../backend/PARTNER-PROVISIONING-API-CONTRACT.md).
Build one generic partner provisioning API. Contract: [../../backend/BACKEND-INTEGRATION.md](../../backend/BACKEND-INTEGRATION.md).
### 1. Partner-specific behaviour is config, never schema
@@ -52,7 +52,7 @@ The partner asked us to choose between per-company, per-project, and per-store c
### 5. Seller is excluded from the hierarchy
`Seller` ([Phase 5](../../backend/PHASE-5-SELLER-PORTAL-CONTRACT.md)) is orthogonal. A payment routes to one payment point, is reconciled there, and only then splits across the sellers whose lines the order contains ([Phase 7](../../backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) §3.1). Putting `Seller` in the partner hierarchy would force every partner to model our multi-seller concept, which most do not have.
`Seller` ([Phase 5](../../backend/BACKEND-INTEGRATION.md)) is orthogonal. A payment routes to one payment point, is reconciled there, and only then splits across the sellers whose lines the order contains ([Phase 7](../../backend/BACKEND-INTEGRATION.md) §3.1). Putting `Seller` in the partner hierarchy would force every partner to model our multi-seller concept, which most do not have.
### 6. RoutingContext lands in Phase 1 before implementation, not after