System requirements

Functional:

• The vending machine system should be able to authenticate and accept multiple payment methods such as mobile payment, credit card or cash. The system should immediately charge the user.
• The user should be able to select which product they want and get it after their payment method was provided and authenticated.
• The vending machine should accurately showcase the quantity of products. This information should be immediately reflected after each transaction.

Non-Functional:

• The system should be highly consistent when it comes to its inventory, which can be done by locking on resource level to ensure no other user is attempting to purchase that same item and that the quantity will be accurately updated after.
• The system should be horizontally scaled to allow multiple users to attempt to purchase items. This can be achieved by having multiple vending machine services that interact with an inventory service.
• To speed up requests and not lock resources for too long, we should have a timeout defined per request. If a user takes too long to provide a proper payment method, we should return an error to the user to try again. If the payment method is declined, we should also return an error to the user to try again.

Capacity estimation

• I will assume there are about 20 items per vending machine and about 4 to 5 vending machines in the area. There should be about 4 to 5 quantity for each item. This means there are about 25 items. There will be a different database instance per vending machine since the quantity of each item is specific to the vending machine (this can be sharded by vending machine id)
• Number of payment methods are around 3 (cash, mobile payment, credit card)

API design

Endpoint: GET /vendingMachine/:id/item/:item_id

• Returns: the item selected for the vending machine

```json

{

"id": 1 // id of the item

"quantity": 1 // quantity of the item

"price": // price of the item in double (currency is USD)

}

```

• • If the item id is invalid (i.e. doesn't exist), this will return a 404

Endpoint: GET /vendingMachine/:id/items

• Returns a list of items available to that vending machine:

```json

[{

"id": 1 // id of the item

"quantity": 1 // quantity of the item

"price": // price of the item in double (currency is USD)

},{

"id": 2 // id of the item

"quantity": 1 // quantity of the item

"price": // price of the item in double (currency is USD)

}]

```

• • If the vending machine id is invalid (i.e. doesn't exist), this will return a 404.

Endpoint: POST /vendingMachine/:id/item/:item_id

In the body of the request, the user will specify their payment info information as well:

{

"paymentType": CARD / CASH/ MOBILE_PAY,

"paymentInfo": Optional<{

// card or mobile_pay details here

}>

}

This endpoint will do a couple things:

1. Check whether item is available for purchase by querying DB.
2. If the item is available, lock the row in the DB so another user cannot attempt to purchase.
3. Validate the payment info if the user has selected card or mobile pay by making an auth call to the provider. If the auth call succeeds, attempt to charge. If the charge attempt is successful, then update the resource to reflect the quantity. If the validation fails at any point, return a 403 error to the customer. Release the lock at the end.
4. Once validation is completed, then return the item to the customer.

The response for the endpoint will be info about the item:

```

{

"id": ,

"name": name_of_item,

"description": optional_description

}

```

Database design

Because we need the system to be consistent, we can have a relational db.

vending_machines table

• id: primary_key
• location: string // geo latitude of where the vending machine is

items

• id: primary_key (required)
• name
• vending_machine // required, foreign key reference to the vending machine so we know which items vending machine has
• original_quantity // so we know how much to restock if current_quantity == 0
• current_quantity

This design allows us to have different types of items per vending machine. It also allows us to track the quantity of the items independently from each vending machine.

High-level design

You should identify enough components that are needed to solve the actual problem from end to end. Also remember to draw a block diagram using the diagramming tool to augment your design. If you are unfamiliar with the tool, you can simply describe your design to the chat bot and ask it to generate a starter diagram for you to modify...

There will be an API gateway for the client to interact with.

Idempotent requests such as get vending machine or vending machine items will be handled by the vending machine service. Because get requests will likely be more popular than non idempotent requests such as purchase, we can assume this will be a read heavy application. We can have a write-through cache for the vending machine service. This means when the user purchases the item, the cache for the vending machine and item is updated accordingly.

Non-idempotent requests such as purchasing the items will be handled by the purchase service, which will also interact with the payment validation service. When a purchase occurs, the item for the purchase will be locked in the items database, and then a request will be made to the payment validation service. If the payment validation service returns a successful response, the purchase service will allow the purchase of the item be successful. If the payment validation returns a failure response, the purchase service will not allow the purchase of the item to be successful.

The lock on the item will be released after a terminal response is received from the payment validation service.

Request flows

We can go over a flow for a user deciding to check out what items are available and then deciding to purchase an item from the vending machine:

1. User wants to check out what items are available in the vending machine (id=1) by making a GET call /vendingMachine/1/items
   1. This call goes through the API gateway which routes the call to the vending machine service. The vending machine service checks out the vending machien by id 1 and returns it back to the client. This vending machine to items info will also be cached.
2. User sees the list of items and decides they want to purchase item #2 from vending machine #1. They make a POST call /vendingMachine/1/item/2 where they pass in their credit card info: `{"paymentType": "CARD", "paymentInfo": {"CARD_NUMBER":1234, "EXPIRY_DATE":"12/24","PIN":1234}`. This info will be encrypted at transit and at rest for security purposes.
   1. When this POST call is made, the api gateway will direct the call to the purchase service. The purchase service will first check whether or not the item requested is still available by querying the items database by item id and vending machine. We can also have an index on the item and vending machine id to speed up lookups. If the item is available, we will lock that row so the purchase service can proceed to make a call to the payment validation service to validate the payment info.
   2. Depending on the payment type, there will be different payment validation steps. For the sake of simplicity, we will just focus on the credit card payment validation. If given a credit card info, we can make a call to the payment gateway and see whether or not we get back an authentication token to make API calls to charge the card. If we do, then we go back to the purchase service and make the external API call to purchase. Once the external API call succeeds, we update the items and also the cache on the vending machine service to update the quantity. We will then return successful payload back to the user.

Detailed component design

1. The purchase service has a pretty long user flow. We check the items database for whether the requested item to purchase is available and if so, we then lock that item/row. We then make a call to the payment validation service which makes an external validation call. Because this external validation call can potentially take a long time, thus forcing us to hold onto the lock for the requested item longer, we should add a timeout around the external validation call to limit the amount of time we hold the lock for. If requests times out, we release the lock on the item and consider the post purchase request as a failure or error to retry. Because this is a long process, we should only lock the item if the item is available for purchase via pessimistic locking.
2. Because the vending machine service depends on the items cache which can get out of date when a purchase is being finalized, there can be an event listener via Kafka on database updates. Once an event is enqueued, there can be a worker that picks up the event and updates the cache that the vending machine uses.

Trade offs/Tech choices

• I separated the purchase service from the vending machine service which adds some complexity since when a purchase is made, not only is the primary database involved is affected, the cache for the vending machine service is also affected. There is a bit of coupling in this situation but with the event listener on db changes in items db, I think this is okay.
• The purchase for an item might also take awhile because we lock per item for a vending machine. I think this is ok if we want to accurately show how many items there are and for a vending machine, there is usually at most only one person purchasing an item at a time.

Failure scenarios/bottlenecks

• Calls to external API can take a while but we can add timeouts to limit how long the overall purchase will take
• Failure scenarios:
  • Payment info validation fail
• Bottlenecks are:
  • Purchasing an item since we lock on an item level

Future improvements

What are some future improvements you would make? How would you mitigate the failure scenario(s) you described above?