TBBN.Merchant Platform docs
Architecturedocs/architecture/system-overview.md

System Overview

The dependency hierarchy

TBBN is built like Stripe, Twilio, Plaid, Shopify, and Segment were: Core Identity → Merchant Network → Event System → Exchange Engine → Orchestration → SDKs → Products, not Website → Dashboard → Marketplace → APIs. The consumer-facing product (TBBN Exchange) is built last because it consumes everything else.

                   TBBN EXCHANGE
                         ^
                         |
               TBBN SDKs / Widgets
                         ^
                         |
              TBBN Infrastructure APIs
                         ^
                         |
               TBBN Core Services
                         ^
                         |
               TBBN Platform Foundation

Six layers

Layer 1 — Identity Network. Marketplace member identity, attributed across merchants when merchant-fed (Phase 22 — see docs/business/conflict-resolution-log.md item 18). auth-service, seller-identity-service, event-service (OTP flows live in auth-service; linking/merge logic lives in seller-identity-service).

Layer 2 — Listing Exchange Network. Merchants sync listings; TBBN never authors them. listing-service, catalog-service, media-service, directory-service, search-service.

Layer 3 — Trade Intelligence Engine. Determines compatibility and value. trade-engine, matching-engine, recommendation-service, currency-service, localization-service.

Layer 4 — Offer Exchange Network. Manages negotiation and session state. offer-service, reservation-service, trade-session-service.

Layer 5 — Checkout Orchestration Network. Coordinates external (merchant-owned) checkouts. checkout-service, payment-status-service, plus billing-service — the one TBBN-owned payment flow (merchant SaaS billing only; TBBN does not currently charge an individual seller for anything, see docs/business/conflict-resolution-log.md items 14 and 17).

Layer 6 — Developer Platform. Serves merchants. api-gateway, docs-site, sandbox-service, SDK packages, merchant-dashboard, analytics-service.

Cutting across all six layers: notification-service, fraud-service, moderation-service, reputation-service, feature-service, audit-service, webhook-service.

Where merchants plug in

A merchant integrates at whichever layer matches their engineering capacity:

  • API-first merchants (large marketplaces with engineering teams) call Layer 2-5 APIs directly and build their own UI.
  • SDK merchants (React/RN/Next apps) use packages/sdk-react, sdk-next, etc. for typed clients + hooks over the same APIs.
  • Widget merchants (thin engineering teams) embed packages/widget-* components with a script tag or npm install — no API integration required beyond configuration.
  • Plugin merchants (Shopify/WooCommerce/Magento/BigCommerce merchants) install packages/plugin-shopify (and future plugins) — zero custom code.

All four paths ultimately call the same OpenAPI-defined surface (packages/openapi-spec), so a merchant can start on widgets and graduate to raw API calls without switching platforms.

What TBBN Exchange is, precisely

apps/Landing-page (renamed from exchange-web in Phase 37) is a read-surface + interaction layer over merchant-synced data. It has zero listing-creation UI — a seller cannot originate a listing on TBBN. It offers: the global trade directory, offer creation/negotiation, and trade-session tracking/notifications. Every write it performs ultimately calls the same merchant-facing APIs a merchant's own integration would call — it is not a special, privileged client. It does not currently charge a seller for anything (see docs/business/conflict-resolution-log.md items 14 and 17).