Marketplace — two-sided commerce

Entities (5)

These are the persistent business objects. Field-level annotations (`phi`, `pci_scope`, `eu_pii`) drive the compliance overlay decisions.

Process flows (3)

Capabilities + integrations

• auth.universalproduction
• rbac.tier-2production
• search.fulltextproduction
• payment.orchestrationproduction
• workflow.sagaproduction
• audit.append_onlyproduction

Integrations: Stripe · Auth0 · SendGrid

Architecture brief

# Marketplace reference architecture — two-sided commerce

## Who this is for

Vertical marketplaces (legal services, freelance design, B2B
procurement), services-on-demand platforms, second-hand commerce.
Anyone matching buyers + sellers with payment escrow + dispute
resolution.

## What's in scope

- **Vendor onboarding** — business documents, KYC check via the
  payment processor, approve/reject decision, welcome email.
- **Listings + search** — Listing entity is `searchable: true` with
  `search_boost: {title: 2.5, body: 1.0}`. The G03 search infra
  generator wires up the FTS index with per-field weights baked in.
  Default provider is Postgres FTS; the genome can be edited to
  promote to Algolia / Typesense / Elasticsearch / Meilisearch when
  scale demands.
- **Synonyms** — `phone` / `mobile` / `cell` / `smartphone` map to
  the same query class so listing-search recall is high without the
  buyer needing to know the vendor's exact term.
- **Payment escrow saga** — `checkout_with_escrow` is modelled as a
  saga; failures during Stripe capture roll back the order.
- **Dispute resolution flow** — buyer files → vendor responds →
  operator decides → release or refund. Auditable end-to-end.
- **Ratings** — basic 5-star + comment, posted post-delivery.

## Compliance bundles produced

- **PCI-DSS** triggered by `pci_scope: cardholder` on Order.card_number
  / expiry_month: cardholder data scope inventory, control matrix,
  network segmentation Terraform, tokenization enforcement test,
  vulnerability scan config, incident response runbook with card-brand
  notification matrix.

## Build-time savings

| Build path | Time |
|---|---|
| Manual senior-eng team | 12-24 weeks |
| Stripe Connect docs + custom UI | 8-16 weeks (still no audit chain / saga compensators) |
| Archiet from this reference architecture | 5-15 minutes |

## How to use

1. Clone to your workspace.
2. Add your category-specific Listing fields (e.g. `condition`
   for second-hand commerce, `service_duration_minutes` for
   services-on-demand).
3. Adjust `search_synonyms` to your vertical's vocabulary.
4. Generate. The G03 search infra + G02 payment orchestration +
   G07 saga generators all fire from the genome declarations.

## What's NOT in this reference

- Vendor analytics dashboards — separate concern; layer with the
  G04 reporting/export generator if needed.
- Marketplace-specific UI polish (image upload, infinite scroll,
  sticky filters) — the generated Next.js app is functional but
  not visually polished. Most marketplaces invest 4-8 weeks of
  design work on top.