Buyer Hub
An escrow platform between media buyers, Meta agencies and sellers: ad accounts, spend caps and money under a double-entry ledger.
- Marketplace / escrow platform
- Next.js / TypeScript / Turborepo / PostgreSQL 16 / Drizzle ORM / Redis + BullMQ / Meta Graph API / USDT TRC20 / better-auth / Chrome Extension (MV3) / Vitest + Playwright
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
- 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
- Request inbox: accept, reject, issue an account
- Offers: create and edit
- Meta System User token with validity checks
- Payouts, reviews, profile
Owner
- 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
- Products by category
- Orders to deliver, with a deadline
- Payouts and reviews
Platform Admin
- 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
Need something similar?
Start a project