# amank2854/vending-machine architecture

> Architecture diagram of the GitHub repository amank2854/vending-machine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amank2854/vending-machine
- Repository: https://github.com/amank2854/vending-machine

## Overview

##### Project type and purpose
- This is a hardware‐oriented digital design project implemented in Verilog HDL.
- The goal is to model a four‐product vending machine using a Finite State Machine (FSM) that accepts nickels and dimes, dispenses products, and returns change.

##### File structure
- README.md: documents the design, FSM states, inputs/outputs, and modules.
- VendingMachine.v: top‐level Verilog module that instantiates one of four item‐modules based on the user’s item_number input.
- VendingMachine_TestBench.v: simulation bench to validate coin insertion, state transitions, dispensing, and change return.

##### README for additional insights
- Inputs: item_number[3:0], nickel_in, dime_in, clock, reset
- Outputs: nickel_out, dispense
- Core FSM variables: current_state, next_state
- Four submodules (Item_One … Item_Four) each implement the FSM logic for a specific price point.
- The top module routes inputs to the chosen item‐module and forwards its outputs.

a. Main components
- User I/O block:
– item_number[3:0] (selection)
– nickel_in, dime_in (coin inputs)
– clock, reset (synchronous controls)
- Top‐level FSM router (VendingMachine)
- Four Item FSM modules (Item_One … Item_Four)
- State register block (current_state → next_state logic) inside each item module
- Output interface: dispense signal and nickel_out change return
- Testbench (VendingMachine_TestBench) shown separately as a simulation driver
b. Relationships and interactions
– User I/O drives the top module ports.
– VendingMachine decodes item_number to select and enable exactly one Item_X module.
– Selected Item_X FSM processes coin inputs, updates state register, and asserts dispense/nickel_out.
– dispense and nickel_out feed back to the user/output block.
– clock and reset fan out to all FSM blocks and registers.
– Testbench connects to all inputs/outputs of VendingMachine for validation.
c. Architectural patterns / design principles
– Hierarchical hardware design: top module + submodules
– Finite State Machine pattern in each Item_X module
– Synchronous state update with clock/standard reset
– Modular reuse: identical FSM structure customized per item price
d. Technologies/frameworks
– Verilog HDL  (structural + behavioral)
– Simulation via a Verilog testbench (e.g., ModelSim, Icarus Verilog)

##### Detail
– Capture each FSM instance as a distinct component, annotate its price and state variables.
– Include the clock/reset distribution network.
– Show the enable/selector derived from item_number.
– If including future scope, add an optional “Cancel/Return Button” block feeding into coin‐return logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Project Documentation
    README["README.md"]:::doc

    %% Testbench
    subgraph "Simulation Testbench"
        direction TB
        TB["VendingMachine_TestBench"]:::tb
    end

    %% User I/O Block
    subgraph "User I/O" 
        direction TB
        IO_ITEM["item_number[3:0]"]:::io
        IO_COIN["nickel_in, dime_in"]:::io
        IO_CTRL["clock, reset"]:::ctrl
    end

    %% Top-Level FSM Router
    VM["VendingMachine"]:::top

    %% Item FSM Modules
    subgraph "Item FSMs" 
        direction TB
        Item1["Item_One\n(current_state → next_state)"]:::item
        Item2["Item_Two\n(current_state → next_state)"]:::item
        Item3["Item_Three\n(current_state → next_state)"]:::item
        Item4["Item_Four\n(current_state → next_state)"]:::item
    end

    %% Output Interface
    subgraph "Output Interface"
        direction TB
        DISP["dispense"]:::io
        NICKEL_OUT["nickel_out"]:::io
    end

    %% Connections
    README --> VM

    IO_ITEM --> VM
    IO_COIN --> VM
    IO_CTRL --> VM

    VM -->|select & enable| Item1
    VM -->|select & enable| Item2
    VM -->|select & enable| Item3
    VM -->|select & enable| Item4

    Item1 --> VM
    Item2 --> VM
    Item3 --> VM
    Item4 --> VM

    VM --> DISP
    VM --> NICKEL_OUT

    IO_CTRL --> Item1
    IO_CTRL --> Item2
    IO_CTRL --> Item3
    IO_CTRL --> Item4

    %% Testbench connections
    TB --> IO_ITEM
    TB --> IO_COIN
    TB --> IO_CTRL
    TB --> VM
    TB --> DISP
    TB --> NICKEL_OUT

    %% Click Events
    click README "https://github.com/amank2854/vending-machine/blob/main/README.md"
    click VM "https://github.com/amank2854/vending-machine/blob/main/VendingMachine.v"
    click TB "https://github.com/amank2854/vending-machine/blob/main/VendingMachine_TestBench.v"

    %% Styles
    classDef doc fill:#f9f,stroke:#333,stroke-width:1px;
    classDef top fill:#bbf,stroke:#333,stroke-width:1px;
    classDef item fill:#bfb,stroke:#333,stroke-width:1px;
    classDef io fill:#eee,stroke:#333,stroke-width:1px;
    classDef ctrl fill:#fc9,stroke:#333,stroke-width:1px;
    classDef tb fill:#fcf,stroke:#333,stroke-width:1px;
```
