Architecture

BazaarFi is a three-tier system: an on-chain escrow program, a Postgres-backed indexer with WebSockets, and a Next.js frontend. The chain is the source of truth; everything else is a projection for discovery, search, and realtime UX.

Components

  • Anchor program — escrows assets in trade PDAs, enforces lifecycle, settles atomically. Emits events for every state change.
  • Indexer — polls program signatures every 3s, parses Anchor events, enriches with Helius DAS + Jupiter prices, writes to Postgres, broadcasts WebSocket events.
  • Web app — Next.js 15 with RSC for fast initial paint. API routes read Postgres. Client uses React Query + wallet adapter for transactions via @bazaarfi/sdk.
  • Shared packages — @bazaarfi/shared (types/schemas), @bazaarfi/sdk (tx building), @bazaarfi/db (Drizzle schema + queries).

Trade creation flow

  1. User signs create → deposit → activate via SDK (batched wallet prompt)
  2. Program emits TradeCreated, AssetDeposited, TradeActivated events
  3. Indexer parses logs, enriches assets, inserts trades + trade_assets
  4. WebSocket broadcasts trade.activated; Explore cache invalidates

Settlement flow

  1. Taker signs accept_trade (with optional ALT setup for large bundles)
  2. Program atomically transfers all assets; emits TradeAccepted
  3. Indexer updates status, records activity, notifies maker
  4. WebSocket broadcasts trade.accepted + stats.updated

Cluster awareness

NEXT_PUBLIC_CLUSTER drives RPC, Helius subdomain, and explorer links. Executable trades always use assets on the active cluster — mainnet metadata can power devnet discovery, but settlement only moves devnet assets when the program is on devnet.

Full technical reference: docs/architecture.md