Requirements

Functional Requirements:

• Allow users to reserve a parking spot based on vehicle type (compact, large, EV, handicapped).
• Process payments securely for the reservation, supporting dynamic, time-based pricing.
• Enable parking of a car in the specific reserved spot.
• Support early departure before the reservation time expires, triggering partial refunds or charge adjustments.
• Facilitate automated gate check-in/out via License Plate Recognition (LPR) or QR codes.
• Automatically handle "no-shows" by freeing up unutilized spots after a grace period.

Non-Functional Requirements:

• High Availability & Reliability: The system must not trap users inside or cause traffic pile-ups outside if a single component fails. Gate functionality needs a fallback offline mode.
• Low Latency: Gate check-in/out validation must occur in under 500ms.
• Consistency: Strict prevention of double-booking the same spot at the same time.
• Scalability: Capable of expanding to multiple parking lot locations globally with varying capacities.

API Design

We will use RESTful principles for client-facing operations.

• POST /v1/reservations
  • Payload: user_id, lot_id, vehicle_type, start_time, end_time
  • Response: reservation_id, spot_id, status
• PUT /v1/reservations/{reservation_id}/cancel
  • Response: status, refund_amount
• POST /v1/gates/check-in
  • Payload: lot_id, gate_id, identifier (license plate string or QR token)
  • Response: action (open_barrier, deny), spot_id
• POST /v1/gates/check-out
  • Payload: lot_id, gate_id, identifier
  • Response: action (open_barrier), pending_charges
• POST /v1/payments
  • Payload: reservation_id, amount, payment_method_id
  • Response: transaction_id, status

High-Level Design

The architecture is broken down into modular, independent services to isolate failures and scale components independently.

• Client Interfaces: Mobile Apps (for users) and IoT Gate Terminals (cameras/scanners).
• API Gateway: Routes incoming traffic, handles rate-limiting, SSL termination, and user authentication.
• Core Services:
  • Reservation Service: Handles the lifecycle of a booking.
  • Spot Management Service: Tracks real-time availability and physical location of spots.
  • Gate Service: Interfaces with physical hardware. Designed for extreme low latency.
  • Payment Service: Integrates with external payment processors (e.g., Stripe).
• Message Broker (Kafka/RabbitMQ): Facilitates asynchronous communication between services (e.g., Gate Service notifying Spot Service of an entry).
• Data Layer:
  • Relational DB (PostgreSQL): Stores users, reservations, parking lot configurations, and payment ledgers.
  • Cache (Redis): Stores active sessions, fast-lookup reservation tables for the gates, and real-time available spot counters.

Detailed Component Design

1. Spot Allocation & Concurrency Control

• Problem: Two users try to book the last available compact spot at the exact same millisecond.
• Solution: We use a relational database with strict ACID properties.
• Mechanism: * When a reservation request comes in, the system starts a database transaction.
  • We use a SELECT ... FOR UPDATE query to lock the specific row of an available parking spot.
  • If successful, the spot's status is updated to RESERVED for the specified time block, and the transaction commits. If the row was already locked by another thread, the system catches the failure and retries fetching a different available spot.
  • To prevent database overload during high traffic, we maintain an atomic counter in Redis for available_spots_by_type. If the Redis counter is zero, we reject the request immediately without hitting the database.

2. Low-Latency Gate Check-In/Out

• Problem: Querying a massive database to verify a license plate at the gate can take too long, causing physical traffic jams.
• Solution: Read-optimized caching and asynchronous state updates.
• Mechanism:
  • When a reservation is created, an event is sent to Redis, caching a key-value pair: Plate_XYZ: {reservation_id, spot_id, valid_time}.
  • When a car pulls up to the gate, the Gate Service queries Redis. This takes less than 5ms.
  • If valid, the Gate Service immediately sends the "open barrier" command to the hardware.
  • After the gate opens, the Gate Service fires an asynchronous event to the Message Broker: VehicleEnteredEvent.
  • The Spot Management Service consumes this event at its own pace and updates the primary PostgreSQL database to mark the spot as OCCUPIED.

3. Handling No-Shows and Early Departures

• Problem: Unused spots cost money. We need a way to reliably free up inventory if someone leaves early or doesn't show up.
• Solution: Time-To-Live (TTL) events and state-machine transitions.
• Mechanism:
  • No-Shows: When a reservation starts, a message is placed into a delayed queue (or a Redis Key-Space Notification) with a TTL of the grace period (e.g., 30 minutes). If the VehicleEnteredEvent is not received before the TTL expires, a worker function executes, changes the reservation status to NO_SHOW, applies the penalty fee via the Payment Service, and releases the spot back into the available pool.
  • Early Departure: When a VehicleExitedEvent is received before the end_time, the system immediately recalculates the cost, triggers a refund via the Payment Service if applicable, and unlocks the spot for new reservations instantly.

Deep Dive

1. Expanding the API Design (Covering All Operations)

Your initial API covered the core actions, but a real-world system needs to handle the pre-booking phase. Users need to check capacity and see prices before committing. Also, booking and paying usually require a "hold" mechanism.

Let's add these missing pieces to the API contract:

• GET /v1/lots/{lot_id}/availability
• Query Params: start_time, end_time, vehicle_type
• Response: available_spots_count
• POST /v1/quotes
• Payload: lot_id, start_time, end_time, vehicle_type
• Response: quote_id, price, valid_until (Supports dynamic pricing based on current load).
• Refined Reservation Flow (Two-Phase):
• Instead of booking immediately, we hold the spot:
• POST /v1/reservations/hold -> Changes spot status to HOLD for 5 minutes.
• POST /v1/reservations/confirm -> Called after payment succeeds. Changes status to RESERVED. If not called within 5 minutes, the TTL expires and the spot reverts to AVAILABLE.

2. Handling Overlapping Reservations (Concurrency Deep-Dive)

The initial design mentioned SELECT ... FOR UPDATE, which is on the right track, but we need to explain how we prevent a bottleneck where hundreds of users are waiting for the lock on the exact same row.

• Pessimistic Locking with SKIP LOCKED: * When searching for a spot, the query should be: SELECT id FROM spots WHERE type = 'compact' AND status = 'AVAILABLE' LIMIT 1 FOR UPDATE SKIP LOCKED;
• Why this matters: If User A is locking Spot 1, User B's query won't wait for User A to finish. It will instantly skip Spot 1 and grab Spot 2. This ensures extremely high throughput without double-booking
• Optimistic Locking (Alternative):
  • Add a version column to the spots table.
  • When booking: UPDATE spots SET status = 'RESERVED', version = version + 1 WHERE id = 123 AND version = {expected_version};
  • If two users try to book at the exact same time, the first one succeeds, changing the version. The second user's query updates 0 rows, triggering the application to instantly retry finding a new spot.
• Idempotency: * What if a user's phone lags and they tap "Reserve" twice? The API Gateway must require an Idempotency-Key in the header for POST requests. If the same key is seen within a short window, the system returns the cached successful response rather than booking a second spot.

3. Handling System Failures and Unexpected Issues

A parking lot system interacts with the physical world. If AWS goes down, you cannot trap people inside a physical garage. Here is how we architect for resilience:

• Network Partition (The "Offline Gate" Problem):
• Scenario: The internet connection to the parking garage drops.
• Solution: Edge Computing. The local gate hardware shouldn't rely entirely on the cloud in real-time. We install a lightweight local server (Edge Node) at the garage. Every 5 minutes, the cloud synchronizes the upcoming reservations to a local Redis cache on the Edge Node. If the internet drops, the gate uses the local cache to allow users in and out, queueing the VehicleEntered and VehicleExited events locally. Once the connection is restored, it syncs those events back to the cloud via Kafka (Eventual Consistency).
• Database Crash:
• Scenario: The primary PostgreSQL node corrupts or fails.
• Solution: Deploy the database in a Multi-AZ (Availability Zone) configuration with synchronous replication to a standby node. If the primary crashes, an automated failover promotes the standby to primary within seconds.
• Service Outages & Cascading Failures:
• Scenario: The Payment Service (Stripe) is experiencing a severe outage and taking 30 seconds to respond, tying up all our server threads.
• Solution: Implement Circuit Breakers (e.g., Resilience4j) between microservices. If the Payment Service fails repeatedly or times out, the circuit "opens" and immediately returns a fast-fail error to the user ("Payment system unavailable, please try again later") without hanging the entire Reservation Service.
• Use Dead Letter Queues (DLQs) in Kafka. If the Spot Service fails to process a VehicleEnteredEvent due to a bug, it shouldn't just disappear. It gets pushed to a DLQ so engineers can inspect it and replay it later.