Loading...
Requirements
Functional Requirements:
- Allow reservation of a parking spot.
- Process payment for the reservation.
- Enable parking of a car in the reserved spot.
- Support early departure before reservation time expires.
- Gate check-in/out.
- Handle no show.
Non-Functional Requirements:
- High availability: if the systems fails, we have another AZ to still operate.
- Scalability: when we have system spikes the system can still operate correctly without failing.
- security: because we are going to have transactions.
- fault tolerance: if we lose the internet, the system can save all the data until it comes back up.
- Latency: It must have low latency to save the spot of the car.
API Design
Define the APIs expected from the system. This is your chance to analyze and define the read and write paths so that you can come up with the high-level design...
This is the API design
- Reservation
- post/reservations:
| Code | Description | Links | ||||
| 201 | Reservation successfully created | Media type | application/json | Controls Accept header. | Example Value | Schema |
{
"reservationId": "res_98721x",
"status": "confirmed",
"vehicleType": "SUV",
"reservationTime": "2026-06-02T14:00:00Z",
"name": "John Doe",
"email": "[email protected]",
"createdAt": "2026-06-02T13:27:00Z"
GET
Get details of a specific reservation
Fetches all core attributes associated with a specific, singular reservation identifier.
Parameters
Try it out
| NameDescription | |||
| reservationId * | string | (path) | The unique alphanumeric system identifier for the target reservation. |
Responses
| Code | Description | Links | ||
| 200 | Detailed information for the requested reservation | Media type | application/json | Controls Accept header. |
- Example Value
- Schema
{
"reservationId": "res_98721x",
"status": "confirmed",
"vehicleType": "SUV",
"reservationTime": "2026-06-02T14:00:00Z",
"name": "John Doe",
"email": "[email protected]",
"createdAt": "2026-06-02T13:27:00Z"
}
| No links | |||
| 404 | The requested reservation ID pointer does not exist | Media type | application/json |
- Example Value
- Schema
{
"error": {
"code": "reservation_not_found",
"message": "The requested reservation resource pointer does not exist.",
"timestamp": "2026-06-02T13:30:00Z"
}
}
GET
Retrieve available or filtered parking spots inside a lot
Returns an array of spots belonging to a specific parking lot. Highly optimized for querying available real estate by vehicle type.
Parameters
Try it out
| NameDescription | ||||||
| lotId * | string | (path) | The unique identifier of the target parking lot facility. | |||
| status | string | (query) | Filter by the current availability state. Defaults to available for user discovery. | Available values : available, occupied, reserved | Default value : available | --availableoccupiedreserved |
| vehicleType | string | (query) | Filter spots by compatible classification layout constraints (e.g., EV, Compact, SUV). | |||
| limit | integer | (query) | Max layout array window size returned per thread call. | Default value : 50 |
Responses
| Code | Description | Links | ||
| 200 | Bounded collection array of matching spot entities. | Media type | application/json | Controls Accept header. |
- Example Value
- Schema
{
"data": [
{
"spotId": "spot_floor2_a4",
"levelName": "Floor 2",
"spotNumber": 104,
"status": "available",
"vehicleType": "EV",
"hasChargingStation": true
}
],
"total_available_count": 14
}
| No links | |||
| 404 | The specified lotId identifier could not be resolved. | Media type | application/json |
- Example Value
- Schema
{
"error": {
"code": "reservation_not_found",
"message": "The requested reservation resource pointer does not exist.",
"timestamp": "2026-06-02T13:30:00Z"
}
} |
POST
Charge a tokenized card asset via an external provider
Charges a transaction using a pre-generated processor token string. No raw card data crosses our infrastructure.
Parameters
Cancel
| NameDescription | |||
| X-Idempotency-Key * | string($uuid) | (header) | Unique transaction key to protect against duplicate payment operations on request retries. |
Request body
application/json
Execute
Responses
| Code | Description | Links | ||
| 200 | Payment request captured successfully by the processor. | Media type | application/json | Controls Accept header. |
- Example Value
- Schema
{
"transactionId": "txn_01H89XZ7",
"reservationId": "res_98721x",
"status": "processing"
}
| No links | |||
| 400 | Structural formatting or validation parameter error. | Media type | application/json |
- Example Value
- Schema
{
"error": {
"code": "reservation_not_found",
"message": "The requested reservation resource pointer does not exist.",
"timestamp": "2026-06-02T13:30:00Z"
}
}
POST
Inbound event notifications receiver from Stripe
Endpoint exposed to the public internet edge to consume transaction event state changes asynchronously. Requires signature parsing (Stripe-Signature header verification) to protect against spoofing.
Parameters
Cancel
| NameDescription | |||
| Stripe-Signature * | string | (header) | Cryptographic signature string generated by the provider to prove authenticity. |
Request body
application/json
Standard event envelope wrapper payload directly from the processor.
Execute
Responses
| Code | Description | Links |
| 200 | Event successfully consumed and processed by the system. | No links |
| 400 | Invalid signature verification checkpoint constraint | No links |
POST
Process physical gate check-in at entry barrier
Validates the pre-paid reservation. Stamped with an entry time for facility occupancy tracking.
Parameters
Try it out
No parameters
Request body
application/json
- Example Value
- Schema
{
"reservationId": "res_98721x",
"licensePlate": "7XYZ99"
}
Responses
POST
Process physical gate check-out at exit barrier
Validates the ticket scanner ID and marks the pre-paid session as closed. No fees calculated.
Parameters
Try it out
| NameDescription | |||
| ticketId * | string | (path) | The unique active ticket scanner ID generated during entry check-in. |
Responses
| Code | Description | Links | ||
| 200 | Check-out successful. Ticket invalidated, status set to COMPLETED, exit gate opens. | Media type | application/json | Controls Accept header. |
- Example Value
- Schema
{
"ticketId": "tkt_55011a",
"status": "COMPLETED",
"exitedAt": "2026-06-02T17:05:00Z"
}
| No links | |||
| 404 | Ticket ID does not match any active parking tracking sessions. | Media type | application/json |
- Example Value
- Schema
{
"error": {
"code": "invalid_ticket",
"message": "Scan event rejected.",
"timestamp": "2026-06-02T21:24:45.053Z"
}
}
High-Level Design
Describe the overall system architecture. Identify the main components needed to solve the problem end-to-end. Use the diagramming tool to create a block diagram.
The system is made up of
- Load balancer: when we have 10000 users at the same time trying to book a slot, the system stays reliably.
- Api-gateway: for rate limiting, reverse-proxy, and for auth.
- public subnet: this is exposed to the internet load balancer and api-gateway
- I used a sync communication because we need to know if, there are any available slots, the payment is done.
- we use webhooks for communication.
- Private subnet: here is our domain, reservation service, payment service, the database.
- reservation service: we use the reservation service to create the reservation logic.
- payment service: here's the logic to implement the payment of the booking through a third vendor.
- cache: we use cache so if the user needs to get the reservation instead of querying the db always.
- for uniqueness we use the database id_ so we can have a unique reservation for every reservation.
- database: the best approach it was using a NoSQL database, for better flexibility and performance.
Detailed Component Design
Deep dive into 2-3 key components. Explain how they work, how they scale, discuss tradeoffs, capacity, and any relevant algorithms or data structures.
The scale: we use a horizontal scaling.