## 4. Detailed Component Design

### 4.1 Component Interaction Overview

```plantuml

@startuml

skinparam componentStyle rectangle

package "Edge" {

[Gate Service] as Gate

}

package "Central" {

[Ticket Service] as Ticket

[Spot Inventory Service] as SpotInv

[Pricing Service] as Pricing

[Payment Service] as Payment

}

[Event Bus] as EventBus

actor "Vehicle" as Vehicle

Vehicle --> Gate : arrives / exits

Gate --> Ticket : CreateTicket / ExitRequest

Ticket --> SpotInv : AllocateSpot

SpotInv --> EventBus : SpotOccupied / SpotReleased

Ticket --> Pricing : RequestQuote

Pricing --> Ticket : Quote

Ticket --> Payment : process payment

EventBus ..> [Analytics\nAlerts\nCache Invalidation] : feeds

@enduml

```

**Flow summary**:

1. **Entry**: Gate Service → Ticket Service creates ticket → Allocation Service (within Spot Inventory) atomically reserves a spot → Event Bus publishes `SpotOccupied` → Gate opens.

2. **Exit**: Gate Service → Ticket Service looks up ticket → Pricing Service computes quote → Payment Service processes payment → Spot Inventory releases spot → Event Bus publishes `SpotReleased` → Gate opens.

3. **Async**: Event Bus feeds analytics, cache invalidation, alerting, and audit log consumers.

### 4.2 Spot Inventory + Allocation

#### Atomic Reservation Algorithm (Optimistic Concurrency)

To prevent overselling when two users try to reserve the same spot simultaneously, the system uses Compare-And-Swap (CAS) via a conditional `UPDATE`:

```sql

SELECT spot_id, version FROM spots

WHERE lot_id = ? AND type = ? AND status = 'AVAILABLE'

ORDER BY distance_to_gate ASC

LIMIT 10

FOR UPDATE SKIP LOCKED;

UPDATE spots

SET status = 'HELD', held_by = ?, held_until = NOW() + INTERVAL '15 minutes', version = version + 1

WHERE spot_id = ? AND status = 'AVAILABLE' AND version = ?;

```

* If `RowsAffected == 0`, another transaction won the race — retry with the next candidate from the batch.

* `FOR UPDATE SKIP LOCKED` ensures concurrent transactions don't block each other; they simply skip already-locked rows and try the next candidate.

* The `version` column provides an additional optimistic concurrency guard against stale reads.

#### Two-Phase Hold → Commit

Allocation is split into two phases to prevent conflicts during the window between spot selection and vehicle arrival:

|-------|--------|----------|-------------|

**Re-check at commit time**: When the vehicle arrives and the gate commits the hold, the system re-validates:

```sql

UPDATE spots

SET status = 'OCCUPIED', held_by = NULL, held_until = NULL

WHERE spot_id = ? AND status = 'HELD' AND held_by = ?;

```

If `RowsAffected == 0`, the hold has expired or been revoked — the entry flow restarts with a fresh allocation.

#### Expired Holds Cleanup

A background scheduler reclaims expired holds every 60 seconds:

```sql

UPDATE spots

SET status = 'AVAILABLE', held_by = NULL, held_until = NULL

WHERE status = 'HELD' AND held_until < NOW();

```

Each reclaimed hold publishes a `HoldExpired` event so no-show penalties and analytics can fire.

#### Idempotent Allocation (Duplicate Request Protection)

Each allocation request carries an `idempotencyKey` (generated by the gate). Before creating a new hold, the service checks:

```sql

SELECT spot_id FROM allocations WHERE idempotency_key = ?;

```

If a record exists, the previously allocated spot is returned without creating a duplicate hold.

#### Performance Optimization: Zone-Counters

Maintain a `zone_availability` table with transactional counters:

1. Identify a zone with `available_count > 0`.

2. Query for spots only within that high-probability zone to reduce lock contention across the entire table.

3. Counters are updated transactionally alongside spot status changes (same DB transaction).

#### Handling Overlapping Time Intervals

For reservation-based parking (pre-booked time slots), the system prevents overlapping bookings on the same spot:

```sql

SELECT 1 FROM reservations

WHERE spot_id = ?

AND status IN ('CONFIRMED', 'HELD')

AND start_time < ? -- requested end

AND end_time > ?; -- requested start

```

If a row is returned, the spot is unavailable for the requested interval. The allocation engine skips to the next candidate.

### 4.3 Ticket Service

* **State Machine**: `ACTIVE` → (`CLOSED` | `LOST`). `CLOSED` requires payment satisfaction.

* **No-Show State**: If a hold expires without vehicle arrival, the ticket transitions to `NO_SHOW` and a penalty policy is evaluated.

* **Plate Handling**: License plates are hashed and encrypted. Original values are stored only if required for compliance.

### 4.4 Pricing Service

Uses a versioned JSON rules engine to build a timeline:

* Evaluate time bands (hourly, daily, flat).

* Apply priority rules (holidays, guest types).

* Return a transparent breakdown for the user.

### 4.5 Payment Service

* **States**: `INITIATED` -> `AUTHORIZED` -> `CAPTURED/FAILED` -> `REFUNDED`.

* **PSP Integration**: Uses tokenization to minimize PCI scope on internal systems.

* **Idempotency**: Every payment request requires an `idempotencyKey`. The PSP adapter de-duplicates on this key to prevent double charges on retries.

### 4.6 Edge Gate Service (Offline-First)

#### Local Cache & Staleness Mitigation

* **Local Fallback**: Gate keeps a cache of availability and pricing rules.

* **Cache Invalidation**: The Event Bus pushes `SpotOccupied` / `SpotReleased` events to edge subscribers. On receipt, the local cache is updated within seconds. A full cache refresh runs every 5 minutes as a safety net.

* **Stale Cache Guard**: When online, every allocation request goes to the central Spot Inventory Service (source of truth). The local cache is only used for display/guidance. Actual booking always hits the central DB with the atomic CAS query, so stale cache **cannot** cause incorrect bookings — it can only show temporarily wrong availability counts.

* **Conflict Mitigation**: If offline, issue tickets with a local sequence prefix and sync upon restoration. Operates on a "pre-allocated quota" (a fixed number of spots reserved for offline use) to prevent overselling while disconnected.

### 4.7 Observability

* **Allocation Accuracy**: Cross-check sensor data vs database states.

* **Latency Metrics**: Track p95 for entry/exit gates.

* **Operational Health**: Monitor offline mode durations and synchronization success rates.

* **Hold Metrics**: Track hold-to-commit conversion rate, expired hold count, and no-show rate.

---

## 5. Scalability & High-Traffic Design

### 5.1 Load Balancing

* An **Application Load Balancer (ALB)** fronts the Ticket Service and Spot Inventory Service, distributing requests across multiple instances.

* Gate-to-cloud traffic is routed through a regional load balancer with health checks and automatic failover.

### 5.2 Horizontal Scaling

* **Stateless Services**: Ticket, Pricing, Payment, and Allocation services are stateless and scale horizontally behind the load balancer.

* **Database Scaling**: Spot Inventory DB is partitioned by `lotId`. Each lot's data is independent, so high contention on one lot does not affect others.

* **Read Replicas**: Availability queries (`GET /availability`) hit read replicas to offload the primary.

### 5.3 Handling Demand Spikes (Stadium Events)

* **Pre-allocated Batches**: For known events, the system pre-segments available spots into allocation batches. Each service instance is assigned a batch, eliminating cross-instance contention on the same rows.

* **Queue-based Throttling**: During extreme surges, entry requests are funneled into a message queue (SQS/Kafka). Workers consume at a controlled rate, preventing database overload. Vehicles see a "processing" status with estimated wait time.

* **Auto-scaling**: Cloud infrastructure auto-scales service instances based on queue depth and request latency metrics.

### 5.4 Distributed Architecture

```plantuml

@startuml

node "Global LB" as GLB

node "Region A" {

component "Services" as SvcA

database "DB (lotA)" as DBA

}

node "Region B" {

component "Services" as SvcB

database "DB (lotB)" as DBB

}

node "Region C" {

component "Services" as SvcC

database "DB (lotC)" as DBC

}

queue "Event Bus\n(Kafka/SNS)" as EventBus

component "Analytics" as Analytics

component "Audit Log" as AuditLog

GLB --> SvcA

GLB --> SvcB

GLB --> SvcC

SvcA --> DBA

SvcB --> DBB

SvcC --> DBC

SvcA --> EventBus

SvcB --> EventBus

SvcC --> EventBus

EventBus --> Analytics

EventBus --> AuditLog

@enduml

```

* **Data Locality**: Each parking lot's data lives in the region closest to the physical lot. No cross-region queries for real-time operations.

* **Event Bus**: Cross-region events flow through the Event Bus for portfolio-wide analytics and reporting.

* **No Global Locks**: Because spot allocation is lot-scoped, there is no need for distributed locks across regions.

Submissions

Displaying Solutions with Scores Ranging from 1 to 10