Parking Lot Management

1. Problem and requirements

A parking operator runs one or more facilities. Each facility has floors, spots, and entry and exit gates. Drivers take a ticket at entry and pay at exit.

Assumptions

• A facility has several floors and several entry and exit gates, each running a gate terminal that calls the backend.
• Vehicles are MOTORCYCLE, CAR or TRUCK. A spot has a size, and a vehicle fits a spot of its own size or larger (a motorcycle may use a car spot when motorcycle spots are full; a truck needs a large spot).
• Some spots have features: EV_CHARGING and ACCESSIBLE. A vehicle that requests a feature is only given a spot with it.
• A vehicle is identified by its licence plate as read or typed at the gate.
• Pricing depends on vehicle type, duration and the facility’s tariff: an hourly rate, a grace period and a daily cap.

Functional requirements

Non-functional requirements

Out of scope for version one

Reservations in advance, dynamic pricing, automatic number-plate recognition hardware, and season passes. Each is a separate feature with its own consistency questions. Reservations, for example, introduce holds that expire. They are listed in scaling evolution with the trigger that would justify them.

2. Capacity estimation

Assumptions: a large facility has 1,000 spots and 4 entry gates. One gate can admit a car about every 6 seconds at the busiest time. Spots turn over 6 times a day. The operator runs 200 facilities.

What this says: writes are small and the system is not throughput-bound. One PostgreSQL primary handles 300 writes/s comfortably. The real difficulty is contention: at a busy facility, many requests compete for the same few free spots on the nearest floor. The design therefore optimises for short transactions and conflict-free allocation, not raw scale.

3. Architecture and APIs

High-level architecture

flowchart LR
  subgraph Facility
    EG[Entry gate terminal]
    XG[Exit gate terminal]
    DB1[Display boards]
  end
  EG -->|HTTPS + Idempotency-Key| API
  XG -->|HTTPS + Idempotency-Key| API
  DB1 -->|GET availability| API
  subgraph Backend [Parking service · Spring Boot]
    API[REST controllers]
    PS[ParkingService]
    AL[AllocationService]
    FC[FeeCalculator]
    PAY[PaymentService]
  end
  API --> PS
  PS --> AL
  PS --> FC
  PS --> PAY
  AL --> PG[(PostgreSQL)]
  PS --> PG
  PAY -->|charge / status| PSP[Payment provider]

API contracts

All unsafe requests carry an Idempotency-Key header. A repeated key returns the stored response of the first call.

Example entry:

POST /facilities/F-12/entries
Idempotency-Key: 6f1c2a7e-gate-E2-000183

{ "plate": "OD02AB1234", "vehicleType": "CAR", "features": ["EV_CHARGING"] }

201 Created
{
  "ticketId": "T-9f2c",
  "spot": { "id": "S-2-047", "floor": 2, "label": "B-47", "features": ["EV_CHARGING"] },
  "enteredAt": "2026-10-22T08:14:03Z"
}

Errors use one shape everywhere (RFC 9457 problem details):

{ "type": "/errors/no-spot-available", "title": "No compatible spot is free",
  "status": 503, "code": "NO_SPOT_AVAILABLE", "retryable": true }

Deployment

flowchart LR
  G[Gate terminals] --> LB[Load balancer]
  LB --> A1[parking-service #1]
  LB --> A2[parking-service #2]
  A1 --> P[(PostgreSQL primary)]
  A2 --> P
  P -. streaming replication .-> R[(Hot standby)]

Two stateless instances behind a load balancer give availability, not throughput. One instance could handle the load. The standby is promoted if the primary fails.

4. Internal design and workflows

Class diagram

classDiagram
  class ParkingLot {
    +id
    +name
    +floors List~ParkingFloor~
  }
  class ParkingFloor {
    +number
    +spots List~ParkingSpot~
  }
  class ParkingSpot {
    +id
    +size SpotSize
    +features Set~Feature~
    +state SpotState
    +fits(Vehicle) bool
  }
  class Vehicle {
    +plate
    +type VehicleType
    +requires Set~Feature~
  }
  class ParkingTicket {
    +id
    +enteredAt
    +exitedAt
    +state TicketState
  }
  class Payment {
    +id
    +amount
    +idempotencyKey
    +providerRef
    +status
  }
  class Tariff {
    +hourlyRate
    +graceMinutes
    +dailyCap
  }
  class SpotAllocationStrategy {
    <<interface>>
    +candidates(lot, vehicle, n) List~SpotId~
  }
  class NearestToEntryStrategy
  class FeeCalculator {
    <<interface>>
    +fee(ticket, exitAt, tariff) Money
  }
  class HourlyWithCapCalculator
  class ParkingService {
    +enter(cmd) Ticket
    +quote(ticketId) Money
    +pay(ticketId, key) Payment
    +exit(ticketId)
  }
  class AllocationService {
    +claim(lot, vehicle) ParkingSpot
  }
  class SpotRepository {
    <<interface>>
    +claimIfAvailable(spotId) bool
  }
  class TicketRepository {
    <<interface>>
    +open(facility, spot, vehicle, at) Ticket
  }
  class PaymentService {
    +charge(ticket, amount, key) Payment
  }

  ParkingLot "1" *-- "1..*" ParkingFloor
  ParkingFloor "1" *-- "1..*" ParkingSpot
  ParkingTicket "*" --> "1" ParkingSpot
  ParkingTicket "*" --> "1" Vehicle
  ParkingTicket "1" --> "0..*" Payment
  SpotAllocationStrategy <|.. NearestToEntryStrategy
  FeeCalculator <|.. HourlyWithCapCalculator
  ParkingService --> AllocationService
  ParkingService --> FeeCalculator
  ParkingService --> PaymentService
  ParkingService --> TicketRepository
  AllocationService --> SpotAllocationStrategy
  AllocationService --> SpotRepository

Interfaces exist only where there is a real variation point. SpotAllocationStrategy (nearest to entry today, balanced across floors tomorrow) and FeeCalculator (hourly with cap today, time-of-day tariffs later) will change. The repositories are interfaces so the domain can be tested without a database. There is no interface for ParkingService: it has one implementation and always will.

ParkingSpot.fits(vehicle) holds the compatibility rule in one place:

public boolean fits(Vehicle v) {
    return size.ordinal() >= v.type().minimumSize().ordinal()
        && features.containsAll(v.requires())
        && state == SpotState.AVAILABLE;
}

State machines

stateDiagram-v2
  [*] --> AVAILABLE
  AVAILABLE --> OCCUPIED: entry claims spot
  OCCUPIED --> AVAILABLE: exit releases spot
  AVAILABLE --> OUT_OF_SERVICE: operator
  OUT_OF_SERVICE --> AVAILABLE: operator
  OCCUPIED --> OCCUPIED: operator cannot disable (409)

stateDiagram-v2
  [*] --> ACTIVE: ticket issued
  ACTIVE --> PAID: payment captured
  PAID --> ACTIVE: grace period expired before exit (fee for extra time)
  PAID --> CLOSED: exit gate opened
  ACTIVE --> LOST: operator marks ticket lost (flat fee)
  LOST --> CLOSED: lost-ticket fee paid
  CLOSED --> [*]

There is no RESERVED spot state in version one, because there are no advance reservations. A spot goes straight from AVAILABLE to OCCUPIED inside the entry transaction. If reservations are added later, RESERVED arrives with an expiry and a sweeper (see scaling).

Every transition is a method on the entity that checks the current state, so an illegal move throws instead of silently corrupting data:

void markPaid(Payment p) {
    if (state != TicketState.ACTIVE) throw new IllegalTransition(state, TicketState.PAID);
    state = TicketState.PAID;
    paidUntil = p.capturedAt().plus(EXIT_GRACE);
}

Data model and indexes

erDiagram
  FACILITY ||--o{ FLOOR : has
  FLOOR ||--o{ SPOT : has
  FACILITY ||--o{ TARIFF : prices
  SPOT ||--o{ TICKET : "occupied by"
  TICKET ||--o{ PAYMENT : "paid by"
  FACILITY {
    uuid id PK
    text name
    text timezone
  }
  FLOOR {
    uuid id PK
    uuid facility_id FK
    int number
  }
  SPOT {
    uuid id PK
    uuid floor_id FK
    text size
    text_array features
    text state
    int distance_rank
    bigint version
  }
  TICKET {
    uuid id PK
    uuid facility_id FK
    uuid spot_id FK
    text plate
    text vehicle_type
    timestamptz entered_at
    timestamptz exited_at
    timestamptz paid_until
    text state
  }
  PAYMENT {
    uuid id PK
    uuid ticket_id FK
    bigint amount_minor
    text idempotency_key UK
    text provider_ref
    text status
    timestamptz created_at
  }
  TARIFF {
    uuid id PK
    uuid facility_id FK
    text vehicle_type
    bigint hourly_rate_minor
    int grace_minutes
    bigint daily_cap_minor
    daterange valid
  }

The constraints that carry the correctness requirements:

-- N1: a spot has at most one open ticket
CREATE UNIQUE INDEX one_open_ticket_per_spot
  ON ticket (spot_id) WHERE state IN ('ACTIVE', 'PAID', 'LOST');

-- N2: a vehicle has at most one open ticket per facility
CREATE UNIQUE INDEX one_open_ticket_per_vehicle
  ON ticket (facility_id, plate) WHERE state IN ('ACTIVE', 'PAID', 'LOST');

-- N3: one payment per idempotency key
ALTER TABLE payment ADD CONSTRAINT payment_idem UNIQUE (idempotency_key);

-- Fast candidate search: free spots by facility, size, nearest first
CREATE INDEX free_spots ON spot (floor_id, size, distance_rank) WHERE state = 'AVAILABLE';

The partial unique indexes are the real guarantee. Even if application code has a bug, the database refuses the second open ticket for a spot or a vehicle.

Entry sequence

sequenceDiagram
  participant G as Entry gate
  participant P as ParkingService
  participant A as AllocationService
  participant D as PostgreSQL
  G->>P: POST /entries (plate, type, Idempotency-Key)
  P->>D: lookup idempotency key
  alt key seen before
    D-->>P: stored response
    P-->>G: same 201 as the first call
  else new request
    P->>A: claim(facility, vehicle)
    A->>D: SELECT candidates (free, fits, nearest) LIMIT 5
    loop each candidate until one succeeds
      A->>D: UPDATE spot SET state='OCCUPIED' WHERE id=? AND state='AVAILABLE'
    end
    A-->>P: claimed spot (or none: 503)
    P->>D: INSERT ticket + idempotency record (same transaction)
    D-->>P: commit
    P-->>G: 201 ticket
  end

The allocation algorithm

The claim is a conditional update. It affects one row only if the spot is still free at that instant, so two concurrent requests can both see spot B-47 as a candidate but only one can claim it:

@Transactional
public Ticket enter(EntryCommand cmd) {
    var vehicle = cmd.vehicle();
    List<SpotId> candidates = strategy.candidates(cmd.facility(), vehicle, 5);
    for (SpotId id : candidates) {
        if (spots.claimIfAvailable(id)) {           // UPDATE ... WHERE state = 'AVAILABLE'
            return tickets.open(cmd.facility(), id, vehicle, clock.instant());
        }                                          // lost the race: try the next candidate
    }
    throw new NoSpotAvailable(cmd.facility(), vehicle.type());
}

UPDATE spot SET state = 'OCCUPIED', version = version + 1
WHERE id = :id AND state = 'AVAILABLE';   -- 1 row: claimed. 0 rows: someone else won.

Why not SELECT ... FOR UPDATE? Row locking works, but it makes concurrent entries wait on each other for the same nearest spot. The conditional update never waits. A loser moves straight to the next candidate. Under heavy contention, SELECT ... FOR UPDATE SKIP LOCKED is the alternative that also avoids waiting. It is the right tool when there are many workers competing for a queue of rows, and it is noted as the fallback in decision record 1.

The fee calculation

FeeCalculator is pure: same inputs, same output, no clock or database inside it. That makes the boundaries easy to test.

Money fee(Ticket t, Instant exitAt, Tariff tariff) {
    long minutes = Duration.between(t.enteredAt(), exitAt).toMinutes();
    if (minutes <= tariff.graceMinutes()) return Money.ZERO;
    long days = minutes / (24 * 60), rest = minutes % (24 * 60);
    long hours = (rest + 59) / 60;                                   // started hours are charged
    Money partial = tariff.hourlyRate().times(hours).min(tariff.dailyCap());
    return tariff.dailyCap().times(days).plus(partial);
}

Money is held as an integer number of the smallest currency unit, never as double.

Transaction boundaries and data ownership

The payment provider call is never inside a database transaction. Holding a row lock while waiting on a network call is how one slow provider freezes a whole facility.

5. Failure modes and consistency

Concurrency and idempotency, summarised

• Spot claims: atomic conditional update, never a read-then-write in application code.
• Uniqueness: partial unique indexes enforce one open ticket per spot and per vehicle.
• Idempotency: every unsafe call stores (key, request hash, response). A replay with a different body under the same key is rejected with 422.
• No in-JVM locks are used for correctness, because there are two instances.

Caching

Availability boards poll often but tolerate a 2-second staleness (N6). A per-facility count is computed with one indexed query and cached in memory for 1 second per instance. Allocation never reads the cache: it always goes to the database, because a stale cache there would cause failed claims.

Security and abuse

• Gate terminals authenticate with mutual TLS and a per-device credential; operators use SSO with roles (OPERATOR, ADMIN).
• Tariff changes and out-of-service changes are audited with who, when and the previous value.
• Plates are personal data: masked in logs, and closed tickets are anonymised after the retention period.

6. Scaling evolution

The design never needs distributed transactions, because a parking event belongs to exactly one facility.

7. Operations and validation

Metrics and SLOs

Test plan (to build)

Load test (to measure)

A k6 script drives entries and exits for 50 simulated facilities at 3× the estimated peak. To be recorded: entry p50/p95/p99, claim retries per entry, and database CPU. No results are claimed until this has been run.

8. Decision records

DR-1: Conditional update, not in-memory locks

• Context: several application instances allocate spots in the same facility.
• Decision: claim with UPDATE ... WHERE state = 'AVAILABLE' and back it with partial unique indexes.
• Rejected: synchronized or ReentrantLock per facility (works only inside one JVM, so it is wrong as soon as a second instance runs); a Redis lock (adds a dependency whose failure and expiry semantics must then be reasoned about, for no gain over the database we already have); SELECT ... FOR UPDATE (correct but serialises requests on the same row).
• Consequence: correctness survives any number of instances. Under extreme contention, switch candidates to SKIP LOCKED (stage 4).

DR-2: Monolith, not microservices

• Context: allocation, tickets and payments are one workflow with one owner.
• Decision: one modular application, modules separated by package and interface.
• Rejected: separate allocation, ticket and payment services. They would turn a local transaction into a distributed workflow, adding sagas and failure modes for no scaling benefit at 140 writes/s.

DR-3: Write PENDING before calling the payment provider

• Decision: persist the payment intent with its idempotency key first, then call the provider, then record the result.
• Why: if the process dies after the provider charges but before we record it, the PENDING row and the shared key let reconciliation find and settle the charge. Calling first and writing after would lose that money silently.

9. Limitations, and implemented versus proposed

Known limitations

• Offline gate operation trades exact spot assignment for flow; occupancy can be briefly wrong after a long outage.
• Plate-based identity fails with misread plates. A ticket ID or QR code is the fallback key at exit.
• Nearest-first allocation can wear out the ground floor; the balanced strategy is a planned alternative.

Status