Skip to content

~/work/stranger-club

System 01 of 03 · Full-stack application

Stranger Club

A cricket-match registration platform that replaced a Google Form, a UPI QR code, and WhatsApp screenshots with one system that handles live slot availability, a FIFO waitlist, and organiser-reviewed payments.

React · Vite · FastAPI · Python · SQLite · SQLAlchemy · Server-Sent Events · Docker

Problem

Weekly cricket matches were being organised through a Google Form for registration, a UPI QR code for payment, a manual screenshot as proof, and WhatsApp messages to confirm who actually made it in. Every step depended on someone manually cross-referencing a spreadsheet against a chat thread, and there was no real way to enforce a fair waitlist once a match filled up. Stranger Club replaces that chain with one system: players register and pay through it, the organiser reviews and confirms from one dashboard, and slot availability is accurate in real time for everyone looking at it.

Architecture

A Vite-built React frontend talks to a single FastAPI backend over two API surfaces — a public one that needs no account, and a protected one behind organiser authentication. Both sit in front of the same SQLite database. State changes are published to any browser tab currently viewing that event over Server-Sent Events, so slot counts update live without polling.

Fig. 01: System flow

Architecture diagram with 8 layers. Clients: Player (no account) and Organiser (session and CSRF). These connect to API surface: Public API and Protected API. These connect to Application: FastAPI. This connects to Domain services: Events, Registrations and Payments. These connect to Persistence: SQLite (BEGIN IMMEDIATE on capacity-sensitive writes). This connects to Live updates: Domain state change. This connects to Transport: SSE. This connects to Clients: Connected browser tabs.

Decisions

01

SQLite, not PostgreSQL

Decision
The application runs on SQLite for this MVP.
Reason
The real load is one organiser running weekly events at a fixed capacity — nowhere near what would justify operating a separate database service.
Tradeoff
There's a comment right next to the capacity-check transaction noting that PostgreSQL's SELECT ... FOR UPDATE would replace BEGIN IMMEDIATE without touching anything else in the service layer. I wrote that in on purpose, so switching later is a known, small change.
02

Concurrency: BEGIN IMMEDIATE on capacity-sensitive writes

Decision
Registering a player, confirming a payment, and promoting a waitlisted player each open their transaction with BEGIN IMMEDIATE, taking SQLite's write lock up front instead of discovering a conflict after the fact.
Reason
Without it, two players could both be confirmed into the same last open slot if their requests landed close together.
Tradeoff
This has nothing to do with performance. It's the one place in the system where getting the write order right is what stops the match from being oversold.
03

Registration and payment as two separate state machines

Decision
A registration's status and its payment's status are tracked independently rather than collapsed into one "booking status" field.
Reason
A player is validly registered before they've paid, and a payment can be rejected without unregistering them — forcing both into a single status would mean representing states that don't actually make sense together.
04

FIFO waitlist, enforced server-side

Decision
Promoting a waitlisted player checks that they're genuinely first in the queue by creation time, and re-checks capacity at the moment of promotion, not when they first registered.
Reason
A payment can arrive late, after the event has already filled from other confirmed players. When that happens, the registration gets demoted back to waitlisted instead of double-booking the event or silently dropping the payment.
05

Session-cookie authentication, not JWT

Decision
The organiser — the only role that ever authenticates — gets a server-side session with an httpOnly cookie, a CSRF token required on every mutating request, Argon2-hashed passwords, and login rate limiting.
Reason
There's exactly one class of authenticated user, and no third-party or mobile client consuming the API. A server-side session is simpler to reason about and revoke than a token scheme built for an audience this project doesn't have. Players never authenticate at all — registering by phone number, not an account, is deliberate.
06

What "payments" actually means here

Decision
There is no payment gateway integration. A player pays the organiser directly by UPI, uploads a screenshot as proof, and the organiser confirms or rejects it from the dashboard.
Reason
The system's job is tracking and verifying that proof correctly, not processing money.

Deployment

A single Docker container, built from the repo's own Dockerfile, with a named volume mounting /data for the SQLite database file and uploaded payment screenshots so both survive a container restart. /health and /ready endpoints exist for exactly the kind of external check a reverse proxy or process supervisor would run.

Constraints

  • Single organiser login model — no multi-organiser support.
  • No player accounts — registration is per-event, by phone number.
  • No payment gateway — proof-of-payment review only.
  • This is the MVP scope from the project's own roadmap, decided up front.

Result

Built and tested against a real cricket match. Registration, waitlist handling, and payment verification all worked with real players rather than local test data. I haven't run it as an ongoing service beyond that one match. It's built and proven, not something I operate day to day.

Lessons

Picking SQLite over Postgres mattered less than making that choice reversible. I left the exact swap point documented in the code instead of treating the database as permanent. The payment flow needs the same treatment next: proof-of-payment review works fine at one-organiser, weekly-event volume, but it won't scale past that without real payment integration.