Requirements

Functional Requirements:

• Users can browse available products on a display or interface, select one, and complete a purchase.
• The system supports various payment methods including cash, coins, credit/debit cards, and mobile payments.
• The system tracks product stock levels in real time, updates inventory after each transaction, and generates alerts when stock falls below a minimum threshold.
• The system issues a refund for the payment amount if a transaction fails or the user cancels it.
• Authorized service personnel can access the machine in a maintenance mode for restocking products, performing repairs, updating configuration, and viewing diagnostic information.

Non-Functional Requirements:

• Consistency is critical. payments will fail & need to be refunded if the vending machine registers a product that is there as is missing. additionally if the data is inconsistent users may be double charged or not charged
• Durability: we need to keep a record of all the financial transactions occuring for reporting & auditability
• Reliability: vending machines should not fail because of network issues or issues with other vending machines
• Security: user financial info needs to be handled securely
• Scalibility: shared network data warehouse things are gonna recieve information from the entire fleet. needs to scale well to additional vending machines being added

Back of Envelope Calculations

Throughput

Let say there are 10,000 vending machines. Each vending machin processes 500 transactions a day, which is ~.002 transactions per second. We have no scaling or throughput issues at the indvidiual machine level. now calculating the vending machines we are at 20 transactions per second.

Storage

Each transaction is roughly a kb of info, we are at 500 * 10,000 = 5 million kb = 5GB a day to warehouse & 50MB per vending machine per day. We want to keep data analysis for five year before putting them in cold storage. So 1.5TB per year, nothing crazy. Can use a few servers to hold that data. Additionally the Vending Machine can easily have a day's data locally on the machine before sending it over

Database schema

Item

item_id: uuid

name: string

price_usd: number

Payment

payment_id: uuid

type: str

status: "Pending" | "Approved" | "Cancelled"

info: json

Refund

id: uuid

payment_to_refund: payment_id

is_complete: boolean

reason: str

Machine

machine_id

location

Transaction

item_id

machine_id

payment_id

status: "Pending" | "Approved" | "Cancelled" | "Refunded"

Alert

reason: str

status: "Unacknowledged" | "Acknowledged" | "Resolved"

machine_id

API Design

• get_available_items()
• select_item(item_id)
• pay(payment_info) : payment_info can be credit_card, debit_card, cash etc.
• cancel_and_refund(payment_id)
• enter_maintenance_mode(security_credentials)
• update_configuration(new_configuration)
• get_diagnostics()
• refresh_inventory(): scans the items that have been restocked to update internal inventory
• health_check(): used to ensure that vending machine is working

High-Level Design

Vending machine

Each vending machine will have an embedded server & database (sql-lite) and respond to its own apis. It will occasionally make network requests to update a central database with analytical information & contact a payment processor to handle payments. It may also send out alerts to event subscribers. Largely however it will do local embedded operations to serve customers.

Data warehouse

this will recieve diagnostic info from the vending machine for reporting and analytical workload purposes. Notably this data can be used to craft algorithms or machine learning models that can predict when items will need to be restocked in advance, which items should be procured for maximum profit, and even when preventive maintenance should be conducted.

Event service

will alert staff when vending machines need maintance or inventory refills. This will be a service like pager duty that alerts employees. This can either be a dynamic dispatching service for whoever is nearby or a simple assignment to the employee assigned to the machine.

Authentication service

when staff attempt to enter maintenance mode, ensures that they are authorized to do so

Database

Transactions need the ACID properties and relational properties of sql, hence sqllite for the vending machines & postgresql for the data warehouse.

Payment Service

Needs a payment gateway that can dispatch any form of payment to the appropriate handler. It will also need to be able to handle refunds.

Detailed Component Design

Vending machines:

Will have a simple, embedded relational database like sqllite. This gives us ACID properties witout needless network calls. This database will store the inventory and keep a local history of trasnactions. The vending machine will also need a physical point of sale device to handle payments & a physical scanner so it knows what is in its inventory. Here is how each api is implemented.

On reliability, vending machines should be fully operational even when connection to the data warehouse is down. This is why they will rely only on their own local database, and only send data to a central warehouse for analytical loads. They should only rely on connection to the payment processor (no way to process a payment without talking to their bank)

The vending machine will be designed with a State Machine design pattern. In each state only certain operations are avaialble

• Normal state
  • get_inventory: returns the current inventory in the database.
  • select_item: displays price information on the point of sale device, and transitions to "Ready for Payment"
  • enter_maintance_mode: if auth service says users has correct credentials enters Maintance
• Ready for Payment
  • pay: accepts the user's information, and then sends it to Stripe (or similar vendor) for payment processing. enters Payment Processing state
• Payment Processing
  • by default continues to process the payment. polls Stripe webhook to see if payment was resolved, if successful gives food to user. If failed, cancels and enters Payment Complete mode
  • cancel_and_refund: if it is currently processing a transaction, attempts to cancel the request. If it fails to cancel or payment is recieved, then issues a refund request. Then enters Normal State
• Payment complete
  • updates inventory db, checks if any events need to be sends, sends transaction data to data warehouse. (note if data warehouse does not need to be updated in real time, we can batch these updates instead and send them during off hours for cheaper compute).
• Maintenance
  • update_configuration(new_configuration)
  • get_diagnostics():
  • refresh_inventory(): uses the scanner to see what the new inventory is like, updates the local database & enters Normal

Data warehouse

This stores data across all vending machines for analytical workloads. Assuming that this can be a day behind, each vending machine can update the data warhouse with its information during off hours in batched jobs. We would not want every vending machine to perform this update at once, but would spread it out over time, vending machines 1-10 during the first hour, 11-20 in the second etc. If there are few enough vending machines, we should keep these jobs in off hours to save money on cloud compute, otherwise we can do these jobs thoughout the day. Once the records are confirmed to be in the data warhouse, we can remove the records from the local vending machine databases. These only need to know their current inventory for smooth operation purposes.

This information can then be used for analytical and machine learning model workflows.

Event service

When vending machines either enter an invalid state or are low on inventory they should send an alert to an employee dispatch service. THen this service can page the relevant team to go and assist. These events can be queued in a message queue to then be processed and resolved by the pager service.

Additionally it should do a health check each minute for each machine to ensure they are still operational. If the vending machine fails the health check it should create an alert.