Portfolio case study / Transactional commerce

Slotline

A customer booking platform and merchant console built around one database invariant: held plus confirmed spots can never exceed capacity. Holds expire on the database clock, checkout confirms under the same lock, and the Contention Lab shows 100 buyers competing for three seats.

Independent buildCustomer product · Merchant consolePostgreSQL · Fastify · React
  • PostgreSQL
  • Fastify
  • React
  • TypeScript
  • Playwright
Slotline storefront with warm ceramics studio photography, a next-session card and live availability
Real capture Storefront · availability and session counts come from the API
49non-browser tests: 10 unit and 39 PostgreSQL integration
9Playwright browser flows passed
100 → 3concurrent holds accepted against a three-seat fixture
0errors or oversold seats in the measured contention runs

01 / The problem

A booking is an inventory transaction, not a form.

A checkout flow has to reserve a scarce thing before it takes payment, return it when the customer leaves, and never confirm it twice. Under concurrency, a read followed by a write is not enough: two customers can both see the last seat and both believe it is theirs.

Slotline puts every inventory change behind one row lock per session. Expiry, allocation, confirmation, cancellation, capacity changes and waitlist promotion all use the same transaction shape, so the invariant is enforced at commit time rather than trusted from a browser count.

02 / Customer experience

Customer experience

Slotline experience catalogue with three workshop cards and live spots remaining
Experience catalogue Published sessions, prices and real availability
Slotline experience detail with session picker, spot selector and capacity breakdown
Hold and checkout The server sets the deadline; the countdown is only a hint

What a customer can do

  • Browse published experiences with real sessions, prices and spots remaining.
  • Choose a session and quantity, then create a temporary hold that immediately reduces availability.
  • Complete a clearly labelled test-mode payment and receive a durable booking reference.
  • Open booking history, cancel inside the policy window, and see the refund recorded.
  • Join a sold-out session's waitlist and see a real queue position in their account.

What the browser cannot decide

  • Availability is derived from holds and bookings, not from a counter the client can edit.
  • An expired hold cannot be confirmed even if the cleanup worker has not run.
  • Confirmation is issued by the server when the transaction commits. A browser redirect never confirms a booking.
  • Sandbox money is labelled TEST MODE wherever a total or payment appears.

03 / Merchant console

Merchant console

The studio overview shows confirmed bookings, active holds, occupancy, upcoming sessions and sandbox gross, followed by booking activity, live reservations, upcoming capacity and an inventory integrity panel. The console also covers experiences, dated sessions, bookings, customers, payments and an append-only audit trail.

Creating a session converts a wall-clock time in the studio's IANA time zone to UTC, including DST gap and fold handling. Capacity edits are checked against committed spots, and staff accounts without the admin role cannot change capacity.

Slotline Studio overview with metrics, booking activity chart, next session and integrity status
Studio overview Metrics, activity and integrity checks from SQL aggregates

04 / The inventory transaction

One lock. One deadline. One commit.

Every operation that can change availability locks the same session_inventory row first. Expired holds are closed inside the locked transaction using the database clock, then the counters are recomputed from the hold and booking records. The operation itself is the last step before commit.

The CHECK constraint held_count + confirmed_count <= capacity is a backstop, not the primary check. Because counters are rebuilt under the lock, a crashed writer cannot leave a session permanently oversold. Availability reads also derive from the records, so a stale counter cannot advertise a seat that does not exist.

BEGIN
  SELECT ... FROM session_inventory
   WHERE session_id = $1
   FOR UPDATE;                         -- the canonical first lock

  UPDATE holds
     SET status = 'EXPIRED', closed_at = now()
   WHERE session_id = $1
     AND status = 'ACTIVE'
     AND expires_at <= now();          -- deadlines from the database clock

  -- held_count and confirmed_count are recomputed
  -- from holds and bookings under the lock

  INSERT INTO holds ...;               -- only if capacity remains
  UPDATE session_inventory ...;
COMMIT;                                -- this is the moment a seat is taken

PostgreSQL READ COMMITTED plus explicit row locking, not serializable retries. No ORM on the inventory path: the lock, expiry and recompute SQL stays visible and reviewable.

05 / Contention Lab

A hundred buyers. Three seats. No oversell.

The lab creates a fresh three-seat fixture in an isolated demo tenant, signs in synthetic buyers and fires a bounded burst of real POST /api/holds requests. Every attempt is persisted with its HTTP status and latency. The result is read back from the database, not from the browser.

At 100 requests with 20 in flight, three holds are accepted and 97 receive a clean 409 INSUFFICIENT_CAPACITY. There are no timeouts, no 500s and no oversold seats. The first run includes connection-pool warm-up; the stabilised p50 is 35 to 52 ms at 20 in flight.

Slotline Contention Lab showing 3 accepted holds, 97 rejections, zero errors and a passed invariant
Measured result 100 requests · 20 in flight · 3 accepted · 97 rejected · 0 errors
Slotline contention benchmark results
RequestsIn flightAcceptedRejectedErrorsp50p95
101037093 ms116 ms
2520322042 ms131 ms
5020347027 ms47 ms
10020397022 ms33 ms
10040397038 ms52 ms

Environment: Node 26, Windows 11, AMD Ryzen 5 5600, PostgreSQL 18.6 local, Fastify inject transport and a 20-connection pool. Latency includes routing, authentication, rate limiting and the whole booking transaction. Read the table for the invariant, not as a production throughput claim.

06 / Waitlist

A freed seat becomes an offer, not a race.

Cancellation, expiry and capacity increases promote the oldest eligible waitlist entry inside the same transaction that frees the seat. The offer is itself a real hold, so every capacity rule applies unchanged.

Accepting converts the offer into a normal booking. Declining or letting it lapse returns the seat to the next entry, atomically. An entry that asks for more spots than are free is skipped without losing its position.

Slotline sold-out session with a Join the waitlist action and real queue position
Sold-out session Waitlist position is real, not a visual state

There is no email or SMS transport. An offer appears when the customer next loads the storefront or their bookings; a missed offer lapses and re-queues safely.

07 / Payments

Payments (sandbox)

The payment adapter and the checkout path are deliberately separated. The sandbox checkout records a payment and confirms the booking in one database transaction, so inventory never confirms without a payment row. The provider shape is implemented too: payment intent, raw-body signature verification, event-id dedupe, out-of-order handling, reconciliation and late-success compensation.

A success that arrives after the hold expired is never confirmed. It is marked as requiring reconciliation and compensated with an audited refund.

Slotline checkout with a countdown, hold summary and test-mode payment action
Checkout Hold summary, server deadline and test-mode payment
Slotline booking confirmation with a durable reference and sandbox payment status
Confirmation Issued by the server when the transaction commits

Not a completed Stripe integration. Stripe is registered as a provider but is explicitly unconfigured. There is no Stripe account, no credential, no network round trip, and Stripe-shaped events are refused. The provider boundary and its failure handling are tested against the demo provider, not against Stripe.

08 / Security and tenancy

Organization identity comes from membership.

Access boundaries

  • Passwords use scrypt; sessions are server-side and roles are enforced per route.
  • A client-supplied organization id or slug is only a selector. Authorization comes from verified memberships.
  • Cross-tenant reads return 404, not 403, so existence is not leaked.
  • Staff without the admin role cannot change capacity; mutating browser requests check the origin.

Demo boundaries

  • Destructive and load-generating actions require DEMO_MODE and a demo tenant.
  • The Contention Lab lives in its own organization so fixtures never pollute the Riverside studio.
  • Runs are bounded by configuration and rate limited; the lab is not a public load generator.
  • No real customer data, no card details, and no real money are involved.

09 / Testing and limits

Tests and limits

The test suite runs against real PostgreSQL transactions: 10 unit tests, 39 integration tests and 9 browser flows. It covers the 100-to-3 race, mixed quantities, expiry versus confirmation, idempotency, capacity reduction, restart, tenant isolation, nine waitlist promotion cases, catalog validation and seven payment-webhook cases.

  • Known limits: no email or SMS notifications, no merchant-initiated or partial refunds, no provider reconciliation poller, and no axe or screen-reader audit yet.
  • Not verified here: Docker Compose and the GitHub Actions workflow exist but were not executed on the build machine. Local tests use the embedded PostgreSQL path.

Build disclosure: Slotline was directed by a human technical lead and implemented largely by an AI coding agent. The repository records what was human, what was machine, and which claims were verified locally. The six experience photographs are AI-generated demo assets, not a real studio's photography. No public repository or hosted backend demo is published. The interactive preview is a browser simulation; the screenshots, tests and contention benchmark documented here are the evidence for the real backend.