Referral Tracker — partner attribution & commissions
Referral Tracker is a custom referral & commission management system: partners share a link carrying their code, every lead it produces is automatically attributed, tracked through its lifecycle, and turned into an auditable commission — with a separate read-only portal so each partner sees only their own pipeline.
Evidence class: internal project result and observed technical result. No client revenue or partner-adoption outcome is claimed.
Observed technical result: a single system attributes coded leads, records lifecycle stages, calculates commission state, and isolates each partner's read-only data server-side.
A partner's code attributes a lead the moment it comes in, and the raw code is stored verbatim alongside the resolved attribution — so the audit trail holds up even if a code changes later.
| Partner | Code | Lead | Stage | Commission |
|---|---|---|---|---|
| North Star Media | NSM-2026 | J. Alvarez | Won | $180.00 |
| Harbor Creative Co. | HCC-014 | R. Okafor | Qualified | $0.00 |
| Bright Path Consulting | BPC-7 | T. Nguyen | New | $0.00 |
| North Star Media | NSM-2026 | D. Fabbro | Won | $220.00 |
Tracking referrals in a spreadsheet breaks down fast: nobody agrees on who gets credit for a lead, commission math is manual and error-prone, and partners have no visibility into their own pipeline without exposing everyone else's. Referral Tracker replaces that with automatic attribution, a real lead lifecycle, and a commission engine — plus a portal partners can trust because it's provably scoped to their own data.
- Multi-tenant business accounts with user roles
- Referral partners each with unique referral code(s)
- Automatic attribution — an active code attributes a lead to its partner, and the raw typed code is always stored verbatim for audit
- Admin surface to create partners, issue codes, work the lead board through its statuses, and approve commissions
- Strictly read-only partner portal, scoped by server-side query projection rather than UI hiding
- Commission engine — flat (stored as cents) or percentage (whole points), with a per-partner override falling back to a business default
- Two intake paths — a public form and an authenticated POST /api/intake — run the same validation and attribution rules
- Duplicate or unattributed leads are recorded rather than silently dropped
- Prisma / PostgreSQL (Neon) — Business, User, ReferralPartner, ReferralCode, Client, Lead, Project, Payment, Commission
- Next.js 16 App Router — React 19 Server Components + Server Actions, TypeScript strict
- Hand-rolled JWT auth via jose, passwords hashed with bcryptjs
- Zod on every form + API boundary
- No third-party SaaS for attribution, commission, or access control — all first-party
- Vitest — 61 cases (49 run without a DB, 12 integration cases need a test Postgres)
Partner isolation is enforced by server-side query projection, not by hiding UI — a dedicated test proves a partner cannot read another partner's data. Attribution stores the raw typed code verbatim separately from the resolved attribution, so the audit trail survives even if a code is later changed or deactivated.
- Built for a single agency's referral program (Wilde Digital), not a public multi-tenant SaaS product
- Commission approval is a human step, not automated payout
- Requires a Postgres database to run
- Internal business software, shown here as a sanitized case study — not a live public portal
Relational business modelling, authentication and roles, workflow state, payment and commission logic, and Prisma/Postgres architecture with tested access-control isolation.