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

API Design

• get_available_items()
• select_item(item_id)
• pay(payment_info) : payment_info can be credit_card, debit_card, cash etc.
• subscribe_to_alert(subscriber)
• 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

High-Level Design

Each vending machine will have an embedded server & database 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 purposes.

Event service

will alert staff when vending machines need maintance

Authentication service

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

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.

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.

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.