Sentinel
Merchant risk lifecycle workspace for a payment facilitator's risk team: underwriting, rules-based
monitoring, cases, controls and reserves, four-eyes approvals, offboarding, and a hash-chained audit
log. Every risk decision is deterministic and explained factor by factor; there is no AI or ML.
- Product spec: the PRD this was built from (phases F0-F10).
DESIGN.md: research, the design brief, and the question each screen answers.DECISIONS.md: assumptions and choices where the PRD left room, and what is not done.ROAST.md: a candid review against card-network rules, MATCH, sanctions practice and the market, and what changed because of it.
Run it
Requirements: Node 22, PostgreSQL 16 (or Docker).
npm install
cp .env.example .env # set AUTH_SECRET to 32 random bytes
make db # or use any local Postgres 16; set DATABASE_URL
npx prisma migrate deploy
npm run seed # resets the database, then seeds (~80 s)
npm run dev # http://localhost:3000
Sign in by choosing a persona. The demo runs on a simulated calendar starting 27 Oct 2026:
npm run demo:advance-day # simulate a day of trading and run every job
npm run demo:advance-day -- --days 30 # several days
npm run worker # the pg-boss worker with the real schedules
Demo mode: no database needed
Without DATABASE_URL, Sentinel runs on an embedded Postgres (PGlite, Postgres compiled to
WebAssembly) loaded from a snapshot of the seeded mock data: 200 fictional merchants, 120 days of
daily metrics, the last 45 days of raw transactions (~180k), disputes, fraud reports, cases,
alerts and an intact audit chain. Every service, rule, approval and audit check runs unchanged.
Changes live in memory and reset when the server restarts.
npm run mock:build # build .mock-db/sentinel.tar.gz (~100 s, 22 MB)
npm run dev:mock # or: SENTINEL_MOCK=1 next start
npm run test:demo # the demo journey end to end, with no database
The home page (/) is a landing page in Bahasa Indonesia (English on /?lang=en): the problem
a payment aggregator has, the flow of a card payment, what Sentinel does, real screenshots, the
people, the five stories and a short FAQ. The sign-in page leads with the five stories: each button signs in as the right person and opens
the screen where the work starts. The dashboard's demo guide tracks each story and hands the next
step to the next person ("Continue as Laura"). Next day in the sidebar simulates a day of
trading and runs every daily job.
Deploy to Vercel
Import the repository and deploy; no environment variables, no database, no settings. Verified
with vercel build from a clean checkout and no environment. The vercel-build script
builds the mock database snapshot when DATABASE_URL is absent, and the app starts in demo mode
(first request on a cold instance: about 1.5 s to load the snapshot).
For a real database instead, set SENTINEL_MODE=database, DATABASE_URL (hosted Postgres 16),
AUTH_SECRET (openssl rand -base64 32) and AUTH_TRUST_HOST=true; the build then runs
prisma migrate deploy. Without SENTINEL_MODE=database, a Vercel deployment stays in demo mode
and ignores any DATABASE_URL. Seed once from your machine with DATABASE_URL="<url>" npm run seed:only.
Limits of demo mode on serverless: each instance holds its own copy, so changes can differ
between instances under load and disappear on a cold start; merchant-portal uploads go to /tmp.
The five stories
| Merchant | Who | What to do |
|---|
| S1 | Lumen Travel Co. | Dimas (senior underwriter), then Laura | Underwriting · Enhanced → finish the checklist → approve with a 10% / 120-day rolling reserve from the impact preview → Laura approves it in Approvals |
| S2 | Brightside Electronics | Rina (analyst) | My work → the volume-spike case → request documents → open the portal link as the merchant and upload a PDF → add a daily limit → close the case |
| S3 | QuickTop Gift Cards | Rina, then Laura | Unassigned → the CRITICAL card-testing case → add a payout hold (four-eyes) → Laura approves |
| S4 | Glow Subscription Box | Laura, Dimas | Portfolio → network watchlist → Glow's dispute case → fixed reserve over $50,000 → Laura approves |
| S5 | Nimbus Supplements | Rina, then Ahmad (compliance) | The watchlist case → propose termination (compliance; the business and principals are listed) → Ahmad approves → npm run demo:advance-day -- --days 121 → terminated, reserve reconciled |
After the review (ROAST.md), three things also happen as the calendar moves:
- 1 Nov: a sanctions list update names the owner of Beacon Consulting; the monthly rescreen finds it and opens a critical watchlist case (
--days 5).
- 2-8 Nov: Thistle Flower Co.'s website starts selling prescription medicines and drops its refund policy; weekly website monitoring raises an alert (
--days 12).
- Any day: Portfolio shows the portfolio's Visa VAMP ratio against the acquirer tiers. In the seeded history, Alder Lodge raised a VAMP warning at 1.87% on 22 Oct while its blended chargeback ratio (0.63%) was under even the internal 0.75% line.
Tests
npm test # unit: scoring, rules DSL, VAMP/ECM, reserves, state machines, four-eyes, audit hash, monitors
npm run test:coverage # ≥ 90% on the pure engines
npm run seed:template # once: seeds the sentinel_tpl database the next two clone
npm run test:integration # preview vs. ledger after 30 days; rescreening, website monitoring, terminated list
npm run test:e2e # Playwright: S1-S5, RBAC, PII masking, audit tamper detection, axe
# (test runs clone sentinel_tpl and drop the clone afterwards)
Layout
app/(internal)/… staff screens app/(portal)/… merchant RFI portal
app/api/v1/… JSON API (Zod, RBAC) lib/domain/… engines and services
lib/sim/… transaction simulator jobs/… worker, advance-day, simulate
prisma/ schema, migrations, seed tests/ unit, integration, e2e
