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:
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:
-
Load a scenario from a file, or create a new one.
-
Edit the scenario data; save scenario to a file.
-
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:
-
Control the simulation flow: start, stop, resume, reset, speed up, slow down.
-
Observe the overall model statistics changing in real time.
-
See the tasks completed and tasks being done.
-
See trucks statistics.
-
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:
-
NOT_CREATED
-
STOPPED
-
RUNNING
To support the frontend features listed above, our backend should provide the following API:
URL | HTTP method | Description | Active simulation experiment state transition |
---|---|---|---|
|
|
Returns a list of embedded scenario names |
|
|
|
Initializes the active simulation experiment by the embedded scenario whose name is passed as the '[name]' part of the URL |
|
|
|
Initializes the active simulation experiment by the provided custom scenario file (transmitted as form data) |
|
|
|
Starts the active simulation experiment in non-blocking mode |
|
|
|
Stops the active simulation experiment (a stopped experiment can be resumed) |
|
|
|
Resumes the stopped active simulation experiment |
|
|
|
Resets the active simulation experiment to its initial state, clears simulation data |
|
|
|
Increases the speed of simulation for the active simulation experiment |
|
|
|
Decreases the speed of simulation for the active simulation experiment |
|
|
|
Returns a stream of data containing real-time information about the active simulation experiment: overall statistics, positions of trucks, etc. |
|
|
|
Returns a stream that contains task-related messages: task creation and task status change. Only changes are streamed. |
|
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:
-
The user receives a list of scenarios (
GET /scenarios
). -
The user chooses a scenario to initialize the active simulation experiment (
POST /init/embedded/[name]
orPOST /init/custom
). -
The user starts the simulation (
POST /start
). -
The user can stop (
POST /stop
) and resume (POST /resume
) the simulation, control simulation speed (POST /faster
,/POST slower
). -
The user can restart the active simulation experiment from the beginning (
POST /reset
, and thenPOST /start
). -
The user can receive real-time simulation information (
GET /updatestream
,GET /taskstream
).