Inspiration
Grassroots gaming tournaments run on trust and a group chat. The organizer collects entry fees by transfer or cash, builds the bracket by hand, and settles results from screenshots posted in a thread. When two players post conflicting screenshots, or one is too blurry to read, the organizer becomes judge, cashier and referee at once. Winners wait days for a payout, and losers have little recourse.
We wanted to take the referee and the cashier out of that loop without taking the human out of it. Umpra is an AI umpire that reads the evidence, moves the bracket, and handles the money through PayPal, but it never moves money without the host's confirmation.
What it does
A host creates an 8-player single-elimination tournament, either with a form or by typing the setup in plain words, such as "8-player knockout, $5 entry, winner 70%, runner-up 30%". Both paths produce the same validated configuration, shown as a preview before anything is saved.
Players join and pay through a PayPal sandbox checkout, and their captured fees build a live prize pool. When all eight seats are filled, the bracket locks and the agent generates it.
Each player uploads a result screenshot. A vision model reads both images. If they agree, the agent confirms the winner and advances the bracket. If they disagree or are unreadable, it opens a dispute with a written summary for the host.
After the final, deterministic code computes the payout split. The host reviews the drafted payouts and confirms once, and only then does the agent send a PayPal Payouts batch. Every agent action is written to an audit log shown in the UI as the officials' report.
How we built it
- App: Next.js (App Router) and TypeScript in strict mode, with Tailwind CSS and shadcn/ui primitives themed to our own design tokens. Mobile-first, designed at 360px.
- Data: Drizzle ORM on Postgres (Supabase). Screenshots live in Supabase Storage.
- Umpire: An idempotent
tick(tournamentId)function rather than a long-running process. It takes a Postgres advisory lock, decides what state the tournament is in, and performs only the actions still needed. A sweep endpoint, called on a schedule, ticks every active tournament, so a crash cannot leave the bracket half-advanced. - AI: Google Gemini, behind a
VisionProviderinterface, reads the screenshots, writes dispute summaries and parses plain-language tournament setups. Its output is untrusted and validated with Zod. Malformed output gets up to two retries, then is marked unreadable and escalated to the host. - PayPal: Direct REST calls in a typed service layer. Orders and captures use deterministic
PayPal-Request-Idvalues, and payouts use a uniquesender_batch_id, so retries and double-clicks never charge or pay twice. Payment state comes from the PayPal API and verified webhooks, never from the client. - Money math: Amounts are integer cents. Each place's payout is
$$p_i = \left\lfloor \frac{P \cdot s_i}{10000} \right\rfloor \quad \text{for } i < n, \qquad p_n = P - \sum_{i<n} p_i$$
where $P$ is the pool in cents and $s_i$ is that place's share in basis points. The last place takes the remainder, so the payouts always sum to the pool exactly.
Challenges we ran into
- Double charges and double payouts. Players double-click, refresh return URLs, and receive duplicate webhooks. We made every money path a compare-and-set or a deduplicated key, and we tested each one.
- Unreliable evidence. A vision model can read a score confidently and be wrong. Instead of trying to make it perfect, we made disagreement and low confidence the default path to a human. The model extracts and summarizes. It never decides an amount or a payee.
- Crashes mid-step. A scheduled umpire can be killed between steps. Our tests inject crashes at each step and check that a rerun creates no duplicate audit rows, double advances or double payouts.
- Brackets on a phone. We drew the bracket as an SVG, with a round selector on small screens and a winner's line that draws in as each match is confirmed.
- Solo demos. Judges need to finish a whole tournament alone. Demo bots take seats and are labelled "simulated" everywhere. They are never counted as paid entries and add nothing to the pool.
- Swapping the AI provider late. We moved from one model provider to Gemini mid-build. Because every model call sits behind one interface and every output is validated, only the adapter changed.
Accomplishments that we're proud of
- The full flow is built end to end: plain-language setup, PayPal checkout with a live pool, AI-read results, disputes, a host-approved payout, and an audit trail.
- The money paths are guarded in code, not in prompts. The payout function refuses to run without host approval, and the split is frozen once a tournament opens.
- Unit and property tests cover the state machine, bracket generation, payout math, the agreement rule and crash recovery. A Playwright smoke test passes at 360px and 1280px.
What we learned
- The safest place for an AI in a money product is the part that reads and explains, never the part that computes or pays.
- A state-driven, idempotent loop is easier to reason about than an event-driven one, and it survives restarts without extra work.
- Most of the real effort went into edge cases such as late captures, refunds that fail halfway and no-shows. Writing the state machine first made those cases explicit.
What's next for UMPRA
- Support more formats and games, and move toward real payments through a licensed partner.
- Add an optional fully autonomous payout mode, off by default and audited loudly, for hosts who trust the umpire.
- Add more evidence checks, such as in-game match IDs, to make disputes rarer.
Built With
- bcryptjs
- drizzle-orm
- google-gemini-api
- gsap
- jose
- next.js
- node.js
- paypal-rest-api
- paypal-sandbox
- playwright
- postgres.js
- postgresql
- react
- render
- shadcn/ui
- supabase
- tailwind-css
- typescript
- vitest
- zod