Marketplace Architecture

HeritagePay marketplace is a contract-backed value-chain execution layer. It is not a generic listing catalogue and it is not a standalone mobile tab.

Architecture decision

Build the first marketplace version as a bounded context inside the existing backend. That keeps it close to Plane B auth, wallet identity, audit, document storage, webhooks, and Blnk-backed payment controls.

Keep these replaceable:

• Extraction worker.
• Proof anchoring adapter.
• Public marketplace portal.

Bounded contexts

Core flow

Code
flowchart TD
  A["Create programme"] --> B["Create opportunity"]
  B --> C["Assign supplier or contractor"]
  C --> D["Create structured contract"]
  D --> E{"Signed?"}
  E -- "No" --> F["Wait for signature"]
  E -- "Yes" --> G["Store version + hash"]
  G --> H["Open milestone ledger"]
  H --> I["Submit evidence"]
  I --> J{"Approved?"}
  J -- "No" --> K["Reject with reason"]
  K --> I
  J -- "Yes" --> L{"Payment rule?"}
  L -- "No" --> M["Milestone approved"]
  L -- "Yes" --> N["Create payment control"]
  N --> O["Record provider execution attempt"]
  O --> P["Gateway/provider callback or manual settlement"]

Definition of integrated

Marketplace is integrated at spine level when an operator can create a wallet-linked contract, assign programme/opportunity context, set participant role, track milestone progress like 0/5, and set payment-control state while the mobile user can see their assigned obligations.

The current product now has the first contract-vault spine plus a first marketplace registry and assignment path:

• GET /internal/marketplace/programmes
• POST /internal/marketplace/programmes
• GET /internal/marketplace/opportunities
• POST /internal/marketplace/opportunities
• GET /internal/marketplace/participants
• POST /internal/marketplace/participants
• GET /internal/marketplace/assignments
• POST /internal/marketplace/assignments
• GET /internal/marketplace/milestones
• POST /internal/marketplace/milestones
• GET /internal/marketplace/evidence
• POST /internal/marketplace/evidence
• GET /internal/marketplace/payment-controls
• POST /internal/marketplace/payment-controls
• GET /internal/marketplace/payment-executions
• POST /internal/marketplace/payment-executions
• POST /internal/marketplace/payment-executions/provider-events
• GET /internal/contract-vault/versions
• POST /internal/contract-vault/versions
• POST /internal/contract-vault/versions/anchor-events
• GET /internal/contract-vault/signatures
• POST /internal/contract-vault/signatures
• POST /internal/contract-vault/signature-requests/provider-events
• GET /internal/contract-vault/commitments
• POST /internal/contract-vault/commitments
• GET /internal/contract-vault/events
• POST /internal/contract-vault/events
• GET /internal/contract-vault/extractions
• POST /internal/contract-vault/extractions
• POST /internal/contract-vault/extractions/decisions

Operators can create programmes, opportunities, participants, and participant assignments in backoffice, then link contracts to those references from Contract Vault. Operators can also create structured milestones with progress such as 0/5 against an opportunity and optional contract reference, then add or review evidence rows against those milestones. Evidence rows now include attachment policy metadata such as provider, object key, byte size, attachment status, visibility, retention policy, and verification timestamp; approved file evidence requires a URI and SHA-256 checksum. Approved evidence can now be linked to payment-control instructions, which record release eligibility and operator approval without executing a money transfer by themselves. Approved payment controls can now be followed by payment execution attempts, which store the replaceable provider class, provider execution reference, attempt number, status, timestamps, and safe response detail. Provider callbacks or reconciliation runs can update those existing executions through the provider-events endpoint. Backoffice exposes this from the Marketplace page as a manual provider-event workflow, so operators can reconcile a gateway callback by provider execution reference without starting a second payment. When the linked payment control has a contract reference, each execution state also appends a contract history event. This gives the marketplace a traceable handoff trail without locking the product to one gateway or claiming automatic settlement before a concrete provider-specific adapter exists. Signature request provider-events follow the same rule for contract signing: the core receives provider-neutral callbacks by provider request reference, records the signer receipt, rolls version status forward, and keeps the concrete signature vendor replaceable. Backoffice can apply the same provider-event contract manually from Contract Vault for operational reconciliation, without making the signature vendor a hard dependency of the core module. Contract version anchor-events do the same for proof anchoring: the core records the proof hash, provider reference, vault/chain references, and contract anchoring status without owning the eventual chain or vault adapter. Backoffice operators can record and review those anchor receipts from Contract Vault, so the external writer can remain modular while the operator surface still shows what has been anchored.

The next marketplace layer is not another listing screen. It is the structured contract workspace. Three pieces are now present: contract versions, which store the exact SHA-256 proof for a draft or signed contract version; signature requests, which create a provider-neutral ceremony boundary before any provider callback exists; signature provider-events, which reconcile callbacks from a replaceable provider into signer receipts; signature receipts, which roll up signer-by-signer ceremony state onto the version; and contract commitments, which store measurable points such as 0 / 5 restaurants that can be created manually or posted by an extractor service. Extraction runs now provide the side-service intake boundary: the core stores the run and proposed commitments, while the extractor remains replaceable. Operators can accept or reject extraction runs after review, which turns the proposed points into an explicit follow-up set without giving the extractor ownership of the contract record. The remaining pieces are concrete signature provider verification adapters, an external anchoring worker, and external gateway verification adapters for payment executions. Contract events are the append-only bridge for those modules: extractor runs, signatures, evidence receipts, payment-control decisions, and payment executions already append timeline entries without mutating the contract proof itself. Anchors and concrete provider callbacks should use the same event spine.