Part 5: Web Application

Intro

As we have seen in the previous parts of the tutorial, we can design our program to provide both the final results of the simulation (e.g., the total expenses) and the intermediate simulation state (e.g., where the truck is right now, is it full or empty).

So far we have:

  1. A desktop application that runs a simulation interactively (see Part 3);

  2. A web service that runs a simulation and returns the aggregated simulation results (see Part 4).

In this part we will add a UI to our server-side simulation, so that we can see the simulation status in a web browser.

The backend will be based on the web service that was created in Part 4. You can download its source code from GitHub: https://github.com/amalgama-llc/supply-chain-tutorial-part-4

Functionality overview

Let’s think first what we want our web application to do for us.

Users of the desktop application (Part 3 of this tutorial) can do the following:

  1. Load a scenario from a file, or create a new one.

  2. Edit the scenario data; save scenario to a file.

  3. Switch to the simulation mode and run a simulation interactively.

For the web application, we will only implement the simulation mode: scenarios will be either embedded or user-provided.

Consider the simulation mode features that we already have in the desktop application:

  1. Control the simulation flow: start, stop, resume, reset, speed up, slow down.

  2. Observe the overall model statistics changing in real time.

  3. See the tasks completed and tasks being done.

  4. See trucks statistics.

  5. See the road graph and trucks animation.

These items of functionality combined help users get insights on the details of what is going on in the simulated system under certain conditions, which, in turn, helps them to make business decisions.

So, a desktop application user will likely be inclined to consider using a web version only if it also provides the features listed above.

Backend API overview

There will be at most one active simulation experiment on the backend in non-blocking mode. This experiment will thus be shared by all users of the web application.

The active simulation experiment has the following states:

  1. NOT_CREATED

  2. STOPPED

  3. RUNNING

To support the frontend features listed above, our backend should provide the following API:

Table 1. New backend API endpoints
URL HTTP method Description Active simulation experiment state transition

/scenarios

GET

Returns a list of embedded scenario names

[NOT_CREATED, RUNNING, STOPPED] → <no state transition>

/init/embedded/[name]

POST

Initializes the active simulation experiment by the embedded scenario whose name is passed as the '[name]' part of the URL

[NOT_CREATED, RUNNING, STOPPED] → STOPPED

/init/custom

POST

Initializes the active simulation experiment by the provided custom scenario file (transmitted as form data)

[NOT_CREATED, RUNNING, STOPPED] → STOPPED

/start

POST

Starts the active simulation experiment in non-blocking mode

[RUNNING, STOPPED] → RUNNING; NOT_CREATED → <error>

/stop

POST

Stops the active simulation experiment (a stopped experiment can be resumed)

[RUNNING, STOPPED] → STOPPED; NOT_CREATED → <error>

/resume

POST

Resumes the stopped active simulation experiment

[RUNNING, STOPPED] → RUNNING; NOT_CREATED → <error>

/reset

POST

Resets the active simulation experiment to its initial state, clears simulation data

[RUNNING, STOPPED] → STOPPED; NOT_CREATED → <error>

/faster

POST

Increases the speed of simulation for the active simulation experiment

[RUNNING, STOPPED] → <no state transition>; NOT_CREATED → <error>

/slower

POST

Decreases the speed of simulation for the active simulation experiment

[RUNNING, STOPPED] → <no state transition>; NOT_CREATED → <error>

/updatestream

GET

Returns a stream of data containing real-time information about the active simulation experiment: overall statistics, positions of trucks, etc.

[NOT_CREATED, RUNNING, STOPPED] → <no state transition>

/taskstream

GET

Returns a stream that contains task-related messages: task creation and task status change. Only changes are streamed.

[NOT_CREATED, RUNNING, STOPPED] → <no state transition>

These are the new backend API endpoints that we will implement in this part of the tutorial.

Why do we introduce a separate /taskstream endpoint? Can’t we just post all tasks created so far using the /updatestream endpoint? Well, this would not be a good solution: as simulation proceeds, more and more tasks get created, so we would end up passing the same (unchanged!) data about the completed tasks over and over again. Only 'deltas' should be transported from backend to frontend, in case of an increasing payload, such as the task list.

So, the workflow supported by this API is as follows:

  1. The user receives a list of scenarios (GET /scenarios).

  2. The user chooses a scenario to initialize the active simulation experiment (POST /init/embedded/[name] or POST /init/custom).

  3. The user starts the simulation (POST /start).

  4. The user can stop (POST /stop) and resume (POST /resume) the simulation, control simulation speed (POST /faster, /POST slower).

  5. The user can restart the active simulation experiment from the beginning (POST /reset, and then POST /start).

  6. The user can receive real-time simulation information (GET /updatestream, GET /taskstream).