AURUM Auctions
An online auction site for collectibles: proxy bidding, auctions that close on their own, orders, live prices and
notifications. Built with React, Express and PostgreSQL.
Live demo: https://online-auction-1-a3t4.onrender.com (free Render tier, the first load after idle takes about a minute)
API reference: https://online-auction-1-a3t4.onrender.com/api-docs.html (OpenAPI 3.1, try requests against the live API)
Log in as demo_buyer1, demo_buyer2 or demo_seller with password Passw0rd!demo. Open the same lot as two
buyers in two browsers to see proxy bidding and live price updates.
Payments are a manual receipt upload, a mock gateway, or card checkout through Stripe in test mode (card 4242 4242 4242 4242). No real money is involved.
Stack
- Frontend: React 19 with TypeScript, Vite, Tailwind CSS 4, React Router
- Backend: TypeScript on Node.js (run directly, no build step), Express, Drizzle ORM, PostgreSQL 16, a separate worker process
- Realtime: Server-Sent Events
- Tests:
node:test against a real PostgreSQL, Vitest, Playwright
- CI: GitHub Actions. Local setup: Docker Compose
How it works
flowchart LR
B[React SPA] -- REST --> A[Express API]
B -- SSE per lot --> A
A -- one transaction per command --> DB[(PostgreSQL)]
W[Worker] -- FOR UPDATE SKIP LOCKED --> DB
DB -- outbox --> W
W --> E[Email and in-app notifications]
PostgreSQL holds everything: state, idempotency keys, the outbox and the audit log. There is no Redis or message broker.
The parts that took the most care:
- Concurrent bids. Every bid locks the auction row (
SELECT ... FOR UPDATE) and checks the deadline against the
database clock after taking the lock. A test fires 50 concurrent bids at one lot and checks the result equals a
serial replay.
- Retries. Bids carry an
Idempotency-Key that is stored in the same transaction, so a retried request returns
the original result instead of bidding twice.
- Closing auctions. The worker picks due auctions with
FOR UPDATE SKIP LOCKED, so several workers can run at
once, and a unique constraint guarantees one order per auction. Tests kill the worker mid-settlement.
- Notifications. Events are written to an outbox table in the same transaction as the change, then delivered by
the worker with retries. A rolled-back bid never sends an email.
- Orders. All status changes go through one pure state-machine function.
- Money. Stored as
numeric(15,0) and handled as BigInt, never as floats.
On a laptop, 50 bidders on a single lot got p95 549 ms with no errors; spread over 20 lots it reached 146 req/s
(backend/scripts/loadtest.js).
More detail, including the design decisions and the alternatives I rejected: docs/architecture.md.
API reference: docs/api.md. Security notes: docs/security.md.
Running locally
With Docker only:
docker compose up
Open http://localhost:5173 once the api container is healthy. The seed also creates demo_admin (same password)
locally.
Or with Node 22.18+ and Docker for the database:
docker compose up -d db
cd backend
cp .env.example .env
npm ci
npm run db:migrate && npm run db:seed
npm run dev # API on :3000
npm run worker # second terminal
cd ../frontend
cp .env.example .env
npm ci
npm run dev # http://localhost:5173
Tests
cd backend && npm run lint && npm run test:unit && npm run test:integration # needs the db container
cd frontend && npm run lint && npm test && npm run build
cd frontend && npx playwright test # needs API, worker and Vite running
Integration tests only run against a database whose name ends in _test.
Not done yet
- Google/Facebook login tested with production credentials
- SSE fan-out across several API instances
