PriorityPay Simple

A real, deployable Next.js app: Supabase for auth + database, Plaid for read-only bank account linking. PriorityPay calculates a percentage-based split for every deposit and shows you a checklist of what to send where -- you complete every transfer yourself, in your own bank's app (that's manual_approval mode, the default -- see lib/executionMode.js). Real money movement via Dwolla exists in the codebase as an opt-in mode (TRANSFER_EXECUTION_MODE=dwolla_auto) for later, but isn't required to run or deploy the app today. Runs in sandbox mode end-to-end for Plaid until you're approved for Plaid production access (see "Going to production" below) -- there's no real money at risk either way, since PriorityPay never touches it regardless of Plaid's environment.

Verified to build clean (next build, no errors) before this was handed to you.

New to this project? Start with PROJECT_HANDOFF.md first. This README covers how to run and deploy the app; PROJECT_HANDOFF.md covers the product model, the decisions behind it, and a list of specific gotchas that will otherwise cost you real debugging time.

Architecture in one paragraph

Next.js App Router, deployed on Vercel. Supabase Auth handles sign-up/login; Supabase Postgres (with row-level security) holds everything else. The browser never talks to Plaid, Dwolla, or the database directly — every sensitive action goes through a Next.js API route (app/api/**) running server-side, where PLAID_SECRET, DWOLLA_SECRET, PLAID_TOKEN_ENCRYPTION_KEY, and the Supabase service-role key actually live. See lib/supabaseServer.js for why it's built this way, and lib/executionMode.js for the manual-vs-automatic transfer switch mentioned above.

---

Part 1 — Create your accounts (~15 minutes)

You'll need three free accounts to run the app as it actually works today. A fourth (Dwolla) is optional -- only needed if you plan to test or enable automatic transfer execution later.

1. Supabase (database + auth)

1. Go to supabase.com → sign up → New project.
2. Name it prioritypay, set a database password (save it somewhere), pick a region close to you.
3. Once it's provisioned: SQL Editor → New query → paste the full contents of supabase/schema.sql from this repo → Run.
4. Project Settings → API — copy three values, you'll need them in Part 2:
   • Project URL → NEXT_PUBLIC_SUPABASE_URL
   • anon public key → NEXT_PUBLIC_SUPABASE_ANON_KEY
   • service_role secret key → SUPABASE_SERVICE_ROLE_KEY (never expose this one to a browser)
5. Authentication → Providers → Email — confirm it's enabled (it is by default). Optionally turn off "Confirm email" under Authentication → Settings while you're testing, so sign-up doesn't require clicking an email link.

2. Plaid (bank linking)

1. Go to dashboard.plaid.com/signup → sign up. Sandbox access is instant, no approval needed.
2. Team Settings → Keys — copy:
   • client_id → PLAID_CLIENT_ID
   • Sandbox secret → PLAID_SECRET
3. Leave PLAID_ENV=sandbox for now.

3. Dwolla (optional -- money movement, only if going automatic)

Skip this entirely for now unless you specifically want to test automatic transfer execution. The default manual_approval mode never calls Dwolla, so DWOLLA_KEY/DWOLLA_SECRET can stay blank in .env.local and nothing breaks (lib/dwolla.js builds its client lazily, only when actually called).

If you do want to test it: go to dashboard-sandbox.dwolla.com → sign up for a sandbox account → Applications → default app → copy the Key and Secret → DWOLLA_KEY / DWOLLA_SECRET → leave DWOLLA_ENV=sandbox → set TRANSFER_EXECUTION_MODE=dwolla_auto. Note that identity verification (collecting each user's SSN before Dwolla will move their money) was removed from onboarding when manual-approval mode became the default -- re-adding that flow is required before dwolla_auto mode is usable with real users, not just a config flip.

4. Vercel (hosting)

1. Go to vercel.com/signup → sign up (GitHub login is easiest, but email works too).
2. Nothing else to do here yet — Part 3 covers deploying.

---

Part 2 — Configure the app

1. In this folder, copy .env.example to .env.local and fill in every value you collected above.
2. Generate an encryption key for stored Plaid access tokens: openssl rand -hex 32 → PLAID_TOKEN_ENCRYPTION_KEY.
3. Test it locally: npm install, then npm run dev, then open http://localhost:3000.
4. Walk through: sign up → onboarding (Business → Connect Accounts, using Plaid's test institution search for "Chase", username user_good, password pass_good → Percentage Splits → Review) → land on the Dashboard → seed a test deposit (see app/api/dev/seed-history for the sandbox-only tooling that backfills realistic mock deposits) → check Accounts or the Dashboard's "Transfers waiting on you" section for the checklist PriorityPay generated. There's nothing to check in a Dwolla dashboard -- nothing was sent anywhere, by design.

If anything errors, the browser network tab + your terminal (npm run dev logs) will show which API route failed and why — almost always a missing or mistyped env var.

---

Part 3 — Deploy to prioritypay.co

No GitHub repo needed for this — deploying straight from your machine via the Vercel CLI:

npm install -g vercel
vercel login
cd prioritypay-simple
vercel        # first run: creates the project, links this folder to it

Then add every env var from .env.local to the Vercel project — either:

• Dashboard: your new project → Settings → Environment Variables → add each one (Production + Preview), or
• CLI: vercel env add PLAID_CLIENT_ID production (repeat per variable)

This is the beginning of the README. Read the rest at the original. Read the full README ↗