Supermarket Simulator

Discrete-event simulation of customer flow and checkout systems in a supermarket. Built with Java 21, JavaFX 20 and MariaDB as the course project for Object-Oriented Programming (TX00EY21-3013) at Metropolia University of Applied Sciences.

---

Screenshot

The simulator running at saturation: 4 service points, live queue animation, and real-time statistics — all configurable from the control panel.

---

Group Members

Member	Contribution
Dornaraj Kharal	Simulation engine (simu.framework, simu.model)
Delara Nipa	Controller and model–view bridge (controller)
Noel Marenco	JavaFX user interface (view) + MariaDB persistence (simu.dao)

---

Course requirements coverage

#	Requirement	Status
1	≥ 4 service points, non-linear network	✅
2	Distributions / parameters changeable from UI	✅
3	JavaFX user interface	✅
4	Visualisation / animation of the run	✅
5	External data repository (file or database)	✅ MariaDB
6	Slow / speed up / pause / step at runtime	✅
7	Pleasant, easy-to-use UI	✅

---

Tech stack

Layer	Technology
Language	Java 21 (toolchain target)
UI	JavaFX 20 (controls, fxml, graphics)
Database	MariaDB 11 + mariadb-java-client 3.3.x (JDBC)
Build	Maven
CI	GitHub Actions

---

Architecture

view  ──── ISimulatorUI ────►  controller  ◄──── IControllerMtoV ──── simu.model (engine)
   ▲                                  │
   │                                  ▼
   └──── IVisualisation ◄──    simu.dao (MariaDB persistence)

• simu.framework / simu.model — discrete-event engine. Owns the event list and runs in its own Thread.
• controller — the bridge. Marshals UI input into a SimulationConfig and dispatches engine events back onto the JavaFX thread via Platform.runLater. Also persists the finished run.
• view — JavaFX UI with simulation controls and live animation canvas.
• simu.dao — JDBC persistence layer. Saves a row per run plus a flexible key/value table for metrics.

---

Project structure

src/main/java
├── Main.java                              # launcher
├── controller/
│   ├── Controller.java                    # bridges UI + Engine + DAO
│   ├── IControllerVtoM.java
│   └── IControllerMtoV.java
├── simu/
│   ├── framework/                         # generic engine (Engine, Event, Clock…)
│   ├── model/                             # supermarket specifics
│   │   ├── MyEngine.java
│   │   ├── Customer.java
│   │   ├── ServicePoint.java
│   │   ├── EventType.java
│   │   ├── Statistics.java
│   │   └── SimulationConfig.java
│   └── dao/
│       ├── DatabaseConnection.java
│       ├── SimulationRun.java
│       └── SimulationRunDAO.java
├── eduni/distributions/                   # statistical distributions library
└── view/
    ├── SimulatorGUI.java
    ├── ISimulatorUI.java
    ├── IVisualisation.java
    ├── Visualisation.java
    └── Visualisation2.java

src/main/resources
├── db.properties.example                  # template (committed)
├── db.properties                          # local secrets (gitignored)
└── db/
    └── schema.sql                         # MariaDB DDL

---

Getting started

Prerequisites

• Java 21+
• Maven 3.8+
• MariaDB 11 (optional — app works without it, see note below)

1. Install and configure MariaDB (one-time)

# macOS
brew install mariadb && brew services start mariadb

mariadb -u root <<'SQL'
CREATE DATABASE IF NOT EXISTS supermarket_sim;
CREATE USER IF NOT EXISTS 'simulator'@'localhost' IDENTIFIED BY 'simpass2026';
GRANT ALL PRIVILEGES ON supermarket_sim.* TO 'simulator'@'localhost';
FLUSH PRIVILEGES;
SQL

mariadb -u simulator -p'simpass2026' supermarket_sim < src/main/resources/db/schema.sql

2. Configure credentials

cp src/main/resources/db.properties.example src/main/resources/db.properties
# edit if your password differs

db.properties is gitignored — each developer keeps their own copy.

3. Run

# From command line
mvn javafx:run

# From IntelliJ IDEA
# Open pom.xml as a project → run Main, or Maven panel → javafx:run

No MariaDB? The simulation runs fully — UI, animation, and statistics work. Only the persistence step is skipped with a console warning. This is intentional graceful degradation.

---

Suggested simulation parameters

Scenario	Sim time	Arrival mean	Self-checkout max items
Stable / under-loaded	480 min	15	10
Saturated (queues form)	120 min	3	10
Stress test	60 min	1	5

---

Inspecting saved runs

# List all runs
mariadb -u simulator -p'simpass2026' supermarket_sim \
  -e "SELECT id, run_at, customers_processed, end_time_minutes FROM simulation_run ORDER BY run_at DESC;"

# Metrics for a specific run
mariadb -u simulator -p'simpass2026' supermarket_sim \
  -e "SELECT metric_name, metric_value, metric_unit FROM simulation_run_metric WHERE run_id = 1;"

---

Roadmap

• UI screen to browse historical runs from MariaDB
• Multi-checkout (N regular + N self-checkout) in the engine
• Live statistics panel (avg waiting time, utilisation %)
• JUnit tests for DAO and ServicePoint
• GitHub Actions artifact — packaged JAR on release

---

JavaDoc

Full API documentation is available in the docs/ folder, or hosted at nipadelara.github.io/SupermarketProject.

---

License

MIT — see LICENSE for details.