Parkezy docs
How Parkezy works
Parkezy is a parking marketplace: drivers find and book a spot, hosts earn from driveways and garages, and the gate opens with a QR code or a PIN. These pages explain the system behind it, section by section, with the real code, diagrams and the numbers from our tests.
89
API routes in one stateless FastAPI service
282
automated backend tests on real Postgres + Redis
69,424
load-test requests, 0 wrong answers, 0 server errors
1 of 100
drivers wins when 100 book the same slot at once
The big picture#
Every phone and browser talks to one API over HTTPS. The API keeps no state of its own: anything that must survive goes to PostgreSQL (the source of truth), anything short-lived goes to Redis, and photos go straight from the phone to object storage. Work that can happen later, such as emails, push notifications, expiring unpaid holds and checking payments, runs in a background worker that reads from a transactional outbox.
Swipe sideways to see the whole figure.
Design principles#
The database enforces the rules that matter
Double booking and unbalanced money are impossible at the Postgres level, not just checked in Python.
Every retry is safe
Bookings take an Idempotency-Key, webhooks are de-duplicated, and every background handler can run twice without harm.
The server decides prices
The app shows what the API quotes; amounts are recomputed server-side with Decimal arithmetic, never trusted from the client.
Fail fast, degrade gracefully
Short timeouts return a clear 503 instead of hanging; if Redis is down, logins and bookings still work.
Read by section#
Start here
Architecture
Services, data stores, deployment and the life of a request
Start here
System design notes
Which classic system design ideas we used, and where
Core flows
Booking engine
State machine, zero double-booking and idempotent retries
Core flows
Proximity search
PostGIS, geohash cells and a cache nearby users share
Core flows
Payments & ledger
Razorpay, webhooks, reconciliation and double-entry accounting
Core flows
QR & PIN access
Contactless check-in with one-time QR tokens and offline PINs
Core flows
Outbox & notifications
Transactional outbox, workers, retries and email
Quality
Security
Passwords, sessions, rate limits and login abuse protection
Quality
Load tests & reliability
What we measured, what broke, and what we fixed
Clients
Mobile app & interfaces
The Expo app, its screens and how it talks to the API
Clients
API reference
Every endpoint group, the error contract and examples