Requirements

Functional Requirements:

• users can reserve a spot on line by lot, vehicle type and time window
• users need to be able to pay for parking
• there must be a check-in check-out system at the gates
• if the system is not available, users should be able to leave the parking
• reservations must be strongly consistent to prevent double-booking
• handle no-shows

Non-Functional Requirements:

• the system should aim to be always available
• the system should be scalable to handle multiple parking lots

Capacity Estimation

10 countries × 100 lots = 1,000 lots; ~200 reservations/lot/day → 200k reservations/day (~2–3 writes/sec). Read:write ≈ 50:1 → ~115 reads/sec. Stay profile: 80% short-term (~4h), 20% long-term (~5 days). Storage: ~128 B/reservation → ~25.6 MB/day → ~280 GB over 2 years including growth and auxiliary data (payments, gate events).

API Design

endpoints for the UX

• GET /parking-lots - list all available parking lots
• GET /parking-lots/{parking_lot_id} - show details of a single parking lot like address and prices
• GET /parking-lots/{parking_lot_id}/availability - show parking spots with their availability; an optional time window to search available spots in can be specified in the query parameters
• POST /reservations {parking_lot_id, parking_spot_id, licence_plates, start_time, end_time}
• POST /payments/{id} - start payment process
• POST /payments/{id}/callback {payment_status} - complete the reservation
• GET /payments/{id} - get payment status for the front end app

endpoints used by parking lot gates

• POST /check-in {licence_plates, timestamp}
• POST /check-out {licence_plates, timestamp}

there can also be endpoints used by administration to add a new parking lot, to manage prices, or manually manage reservations and payments

High-Level Design

Different front-end apps will communicate to a single public API gateway in charge of rate limiting and load balancing. WE have three main functions: browsing spots, making reservations and making payments so we will have at least three back end services:

• parking-spots-service: listing parking lots, parking spots and their availability; serving all /parking-lots… endpoints. Availability is served directly from the database — reads are infrequent (~115/sec) and time-window queries don't suit a KV cache, so no cache layer is needed.To make interval queries and double-booking prevention fast, the DB is PostgreSQL with range types and an exclusion constraint: EXCLUDE USING gist (spot_id WITH =, window WITH &&) — the database itself refuses overlapping reservations for the same spot, and availability lookups use the interval index. This replaces both the cache and a separate locking layer: reservations and availability checks hit the same authoritative store.
• reservations-service: in charge of making reservations and confirming them after the payments are made;
• check-in service: this service will be in charge of controlling the parking gates to allow a car to enter; it will manage check-in and check-out information and canceling reservations (for example in case of no shows)
• payments-service: to handle payments
• user-service: to handle user registration and authentication (auth can also be delegated to third party; or reservations without an account can be allowed)

There will be a single database which if needed can be sharded by parking lot ids

Database Design

SQL database because of the relations between parking_lot, parking_spots and reservations

Tables:

• users {id, name, address...}
• parking_lots {id, address}
• parking_spots {id, parking_lot_id, type, price} - shard by lot it
• reservations {id, user_id, licence_plate, window tsrange, status (hold, payed, checked-in, checked-out, timed_out)}
• transactions {id, reservation_id, user_id, amount, timestamp, status}

Detailed Component Design

Deep dive into 2-3 key components. Explain how they work, how they scale, discuss tradeoffs, capacity, and any relevant algorithms or data structures.

Starting with the parking-spots-service ("parking spots service"). The assumed scenario is that a user provides a time window in which they would like to park and we need to respond with a list of available parking spots. The user would then try and make a reservation for one spot for the requested time window.

In any case, the user will choose one or all of: parking lot, time window and we need to make a query to the DB to provide us with a list of spots available in the desired period. The user would then choose the spot/time window combination at which point we would make an entry in the reservations table with a status of "on hold", so no other user can try and book the same slot. After the user completes the payment the status would turn into "reserved".

If the payment doesn't happen within a specified timeout period, the record can be marked as timed-out. When the reservation is put on hold a timer starts, if it times out, the reservation will get a status timed-out and the front end polling mechanism will find it and can tell the user to start all over.

It is possible that a time window is put on hold or reserved by a different user in between the time a user sees it as available and initiates a reservation - in this case we can return an error and a new list of available time windows.

Error handling analysis

1) Double booking: handled by the DB; in case of overlap return error and offer alternative time slots.

2) Payment flow failures:

2.1) callback lost/delayed, a a hold waits forever - there must be a timeout after which the hold is released; the frontend polls so will find that the reservation was canceled; How will the frontend know why? the reservation will have acanceled status, and an error message

2.2) callback is retried (that's what providers do) - it has to be idenpotent, based on a payment id

2.3) user abandons payment - again a timeout after which the reservation entry is deleted.

3) if the payment provider is down - we have timeouts and a circuit breaker

4) database errors

4.1) shard goes down - sharding limits the damage; each has replicas and an in-built failover

4.2) retryable errors - retry with backoff and jitter

Metrics

• Utilization rate per lot
• No-show rate
• Booking conversion
• Average reservation duration
• Revenue per spot per hour
• Standard RED (Rate, Errors, Duration)
• Exclusion-constraint conflict rate
• Callback delay
• Hold expiry rate
• Shard hot-spotting
• Gate pull query latency

Testing

Security concerns

1. Payments — card data never enters our systems; the provider returns a token, keeping us out of PCI scope. The /payments/{id}/callback endpoint verifies the provider's signature before any state change, so a forged callback can't confirm an unpaid reservation.
2. Authorization — every reservation-scoped endpoint enforces ownership (WHERE id = ? AND user_id = ?) to prevent IDOR: user A can't read, cancel, or pay for user B's reservation.
3. Gate access — QR tokens are cryptographically signed (HMAC), time-bound to the reservation window, and single-use (marked consumed at check-in), so they can't be forged, replayed, or shared.
4. Data privacy — license plates and visit history are PII (GDPR): encrypted at rest, access-logged, and retained only as long as required. The plate-indexed check-in lookup is a sensitive search surface, so it gets access controls and audit logging.
5. API hygiene — parameterized queries with strict validation on the time-window inputs (start < end, sane window length), gateway rate limiting against scraping, and admin endpoints behind separate, stronger auth (SSO/mTLS).