Design An Efficient Parking Lot System - System Design

Requirements

Functional Requirements:

End-to-End Reserve Journey: 1. Uあser searches → 2. System holds a spot (Status: PENDING) → 3. User pays → 4. Payment Gateway sends callback → 5. System confirms reservation (Status: CONFIRMED).

Payment Handoff & Callback: The system hands off to a 3rd-party (e.g., Stripe) with a unique SessionID. Once paid, Stripe hits our Webhook endpoint. This ensures we don't rely on the client-side redirect for critical state changes.

Non-Functional Requirements:

Define the system constraints to ensure stability and performance.

High Availability: The system must be operational 24/7 (99.99% uptime). A downtime means cars cannot enter/exit, leading to physical congestion.
Scalability: Must support thousands of parking lots and millions of daily transactions.
Consistency: Strong consistency is required for payments and spot allocation to prevent double-booking.
Low Latency: Gate entry/exit validation and spot availability checks must happen in real-time (<200ms).

API Design

The previous design missed operational and granular steps. Below is the comprehensive API suite:

Category	Method	Endpoint	Description
Discovery	`GET`	`/v1/lots/{id}/capacity`	Check real-time availability and capacity.
	`GET`	`/v1/price-quote`	Get a price estimate based on duration and vehicle type.
Booking	`POST`	`/v1/reservations/hold`	Place a 10-min tentative hold on a spot.
	`POST`	`/v1/reservations/confirm`	Finalize the booking after payment confirmation.
Operations	`POST`	`/v1/entry/check-in`	Triggered by Gate Device when vehicle arrives.
	`POST`	`/v1/exit/check-out`	Triggered by Gate Device when vehicle leaves.
Internal	`POST`	`/v1/payments/callback`

Webhook for External Payment Provider.

High-Level Design

The Reserve Journey

Search & Quote: User checks capacity and gets a price quote.
Tentative Hold: User selects a spot; system creates a PENDING record and holds the spot in Redis (TTL: 10m).
Payment Handoff: System redirects to External Payment Provider.
Asynchronous Confirmation: Payment Provider sends a callback to the API Gateway. The gateway pushes a message to Kafka.
Finalize: The Reservation Service consumes the Kafka message, updates the SQL DB (Source of Truth), and invalidates the Advisory Cache (Redis).

Detailed Component Design

Handling No-Shows

To prevent lost revenue and idle spots:

Expiration Worker: A background job identifies CONFIRMED reservations where vehicle_arrived is null after 30 minutes of start_time.
Automatic Cancellation: The system releases the spot and marks the status as NO_SHOW.
Penalty Fee: The Payment Provider is triggered to charge a non-refundable "No-show fee" as per policy.

Cache vs. Source of Truth

Advisory Cache (Redis): Used for fast capacity check and hold operations to ensure low latency for users.
Source of Truth (SQL): The final commit is always written to the SQL DB with ACID transactions. If the cache is stale, the SQL DB constraint will reject the transaction, ensuring zero double-bookings.

Hot-lot Surge & Idempotency

Hot-lot: Rate-limiting is applied at the API Gateway per lot_id to prevent DB connection exhaustion during peak surges.
Idempotency: Every POST request carries an Idempotency-Key. The Reservation Service checks this against Redis before processing to ensure retries don't create duplicate bookings.