Skip to content
Start a project
All work

Buyer Hub

An escrow platform between media buyers, Meta agencies and sellers: ad accounts, spend caps and money under a double-entry ledger.

Type
Marketplace / escrow platform
Stack
Next.js / TypeScript / Turborepo / PostgreSQL 16 / Drizzle ORM / Redis + BullMQ / Meta Graph API / USDT TRC20 / better-auth / Chrome Extension (MV3) / Vitest + Playwright

Interface recreation, fictional data

Problem

A buyer pays an agency for an ad account up front without knowing it will arrive. An agency issues the account without knowing the spend will be paid. Both sides risk money on trust.

Solution

The platform holds the money. When an account is issued, the cap plus both fees is put on hold, Meta spend is billed from the hold in deltas, and the remainder returns only after the account is closed.

5
roles
138
screens
92
tables
25
database migrations
~25
background jobs
4
BullMQ queues
192
test files
7
e2e specs

Roles

Every role has its own menu, its own slice of data and its own limits. Here is what was built for each.

  • Buyer

    01
    • Dashboard: balance, 24-hour and 7-day spend, an attention list
    • Offer marketplace with filters and account requests
    • Accounts: raise or lower the cap, close
    • Shop purchases
  • Agency

    02
    • Request inbox: accept, reject, issue an account
    • Offers: create and edit
    • Meta System User token with validity checks
    • Payouts, reviews, profile
  • Owner

    03
    • USDT TRC20 top-ups with step-by-step status
    • Allocating money to buyers and revoking it
    • A “where the money is now” split
    • Buyer invites and workspace modules
  • Seller

    04
    • Products by category
    • Orders to deliver, with a deadline
    • Payouts and reviews
  • Platform Admin

    05
    • Top-up approval and deposit oversight
    • Payouts to agencies and sellers
    • Ledger viewer and forced status transitions with a mandatory reason
    • Disputes, review moderation, a failed-jobs page

Modules

Ad accounts
Request, accept, issue, cap, spend sync, close. A state machine: pending → accepted → issued → active ⇄ limited → closing → closed
Wallet
Double entry, holds, agency and platform fees, allocation to buyers, payouts, hourly balance reconciliation
Deposits
A separate address per top-up, TRON transfer watching, block confirmations, crediting
Shop
Seller products, orders moving paid → delivered → completed, disputes, auto-completion and SLA refunds

Integrations

Meta Graph API v21
Token checks, batched account reads of 50, writing the spend cap
TRON / USDT TRC20
Addresses derived from an xpub, TronGrid watches transfers, Tronscan cross-checks them
Meta, TikTok, Google OAuth
Ad source connections in the traffic module, tokens encrypted
Telegram Bot
Notifications, account linking, password reset
better-auth
Invite-only sign-up, rate limits stored in Postgres
Sentry / GlitchTip
Errors and structured logs
S3
Database backups with a restore drill
Chrome Extension (MV3)
Extracts the token and session from the user's own browser; stores and sends nothing

Architecture

  • A Turborepo monorepo: web, worker, shared core and db packages
  • PostgreSQL 16 and Drizzle ORM: 92 tables, 25 migrations, amounts as bigint cents
  • A double-entry ledger: CHECK constraints on balances and triggers that make entries append-only
  • SERIALIZABLE transactions with retry, account rows locked in sorted order to avoid deadlocks
  • BullMQ on Redis: four queues, jobs for issuing, caps, spend sync and closing
  • A Meta adapter with two backends: the real Graph API and a simulator for tests
  • Docker Compose on a VPS: caddy, web, worker, migrate, backup, postgres, redis
  • CI: typecheck, lint, tests, build, Docker images, plus e2e in Chromium and WebKit

Engineering decisions

  • The database itself guarantees an append-only ledger: triggers and CHECK constraints, not application code
  • A hold instead of prepayment: the cap and both fees are locked at issue, spend is billed in deltas
  • The closing status exists on purpose: money Meta may still spend is never released early
  • A transition table per actor; terminal states have no way out, even for the admin
  • A per-agency rate gate for Meta calls and retries that honour retry-after
  • One-in-flight job dedup instead of a fixed jobId, which silently dropped later cap changes

What was delivered

  • 5 roles with separate consoles
  • Offer marketplace
  • Ad-account state machine
  • Double-entry ledger
  • USDT TRC20 deposits
  • Meta spend sync
  • Shop with disputes
  • Telegram notifications
  • Meta simulator
  • Chrome extension
  • CI with e2e in two browsers
Next case studyEsports Prediction Platform

Need something similar?

Start a project