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:

CategoryMethodEndpointDescription
DiscoveryGET/v1/lots/{id}/capacityCheck real-time availability and capacity.
GET/v1/price-quoteGet a price estimate based on duration and vehicle type.
BookingPOST/v1/reservations/holdPlace a 10-min tentative hold on a spot.
POST/v1/reservations/confirmFinalize the booking after payment confirmation.
OperationsPOST/v1/entry/check-inTriggered by Gate Device when vehicle arrives.
POST/v1/exit/check-outTriggered by Gate Device when vehicle leaves.
InternalPOST/v1/payments/callback

Webhook for External Payment Provider.


High-Level Design

The Reserve Journey

  1. Search & Quote: User checks capacity and gets a price quote.
  2. Tentative Hold: User selects a spot; system creates a PENDING record and holds the spot in Redis (TTL: 10m).
  3. Payment Handoff: System redirects to External Payment Provider.
  4. Asynchronous Confirmation: Payment Provider sends a callback to the API Gateway. The gateway pushes a message to Kafka.
  5. 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.