[[development-guide]]
= Development guide

== Project structure

The project is a multi-module Maven project.

.Module dependency tree diagram
image::modules.dot.svg[align="center"]

At the bottom of the module tree there are the back end and front end modules, which contain the application source code.

The standalone module is an assembly module that combines the back end and front end into a single executable JAR file.

The distribution module represents the final assembly step.
It takes the standalone application and the documentation and wraps them in an archive that is easy to distribute.

== Developing OptaWeb Vehicle Routing

The back end and front end are separate projects that can be built and deployed separately.
In fact, they are written in completely different languages and built with different tools.
Both projects have tools that provide a modern developer experience with fast turn-around between code changes and the running application.

In the next sections you will learn how to run both back end and front end projects in development mode.

[[backend]]
== Back end

////
- OptaPlanner, GraphHopper
- Quarkus
- Configuration (`application.properties`, `application-*.properties`)
- Package structure
- DevTools
- Docker
////

The back end module contains a server-side application that uses OptaPlanner to *optimize vehicle routes*.
Optimization is a CPU-intensive computation that must avoid any I/O operations in order to perform to its full potential.
Because one of the chief objectives is to minimize the travel cost, either time or distance, we need to keep the travel cost information in RAM memory.
While solving, OptaPlanner needs to know the travel cost between every pair of locations entered by the user.
This information is stored in a structure called the _distance matrix_.

When a new location is entered, we calculate the travel cost between the new location and every other location that has been entered so far, and store the travel cost in the distance matrix.
The travel cost calculation is performed by a routing engine called https://github.com/graphhopper/graphhopper[GraphHopper].

Finally, the back end module implements additional supporting functionality, such as:

- persistence,
- WebSocket connection for the front end,
- data set loading, export, and import.

In the next sections you will learn how to configure and run the back end in development mode.
To learn more about the back end code architecture, see <<appendix-backend-architecture#backend-architecture>>.

[[run-quarkus-maven-plugin]]
=== Running the back end using the Quarkus Maven plugin

.Prerequisites
- Java 11 or higher is <<quickstart#install-java,installed>>.
- The data directory is set up.
- An OSM file is downloaded.
// TODO application-local.properties

You can manually <<run-noscript#data-dir-setup,set up the data directory>> and <<run-noscript#download-osm,download the OSM file>> or you can use the <<run-locally#run-locally-sh,run script>> to complete these tasks.

.Procedure
To run the back end in development mode, enter the following command:

[source,shell]
----
mvn compile quarkus:dev
----

=== Quarkus development mode

In development mode, the back end automatically restarts whenever you refresh the browser tab where the front end runs if there are any changes in the back-end source code or configuration.

Learn more about https://quarkus.io/guides/maven-tooling#development-mode[Quarkus development mode].

=== Running the back end from IntelliJ IDEA Ultimate

IntelliJ IDEA Ultimate has a bundled Quarkus plugin that automatically creates run configurations for modules using the Quarkus framework.
Use the *optaweb-vehicle-routing-backend* run configuration to run the back end.

Learn more about https://www.jetbrains.com/help/idea/quarkus.html#run-app[running Quarkus applications] in IntelliJ IDEA Ultimate.

[[backend-configuration]]
=== Configuration

==== The `application.properties` file

The base configuration is stored in the `application.properties` file, under `/src/main/resources/`.
This file is under version control.
Use it to permanently store the default configuration and to define Quarkus profiles.

==== System properties

To override the default configuration temporarily, use system properties (`-Dproperty=value`).

==== The `.env` file

To override the default configuration permanently, for example to store a configuration that is specific to your development environment, use the `optaweb-vehicle-routing-backend/.env` file.
This file is excluded from version control and so it does not exist when you clone the repository.
Use `optaweb-vehicle-routing-backend/.env-example` to initialize your own `optaweb-vehicle-routing-backend/.env` file.
You can make changes in the `.env` file without  affecting the Git working tree.

See the complete list of <<appendix-backend-config#backend-configuration-properties>>.

See also the complete list of https://quarkus.io/guides/all-config[common application properties] available in Quarkus.

=== Logging

OptaWeb uses the SLF4J API and Logback as the logging framework.
For more information, see https://quarkus.io/guides/logging[Quarkus - Configuring Logging].

[[frontend]]
== Front end

////
- PatternFly, Leaflet
- Npm, React, Redux, TypeScript, ESLint, Cypress, `ncu`
- Chrome, plugins
- Docker
////

The front end project was bootstrapped with https://create-react-app.dev/[Create React App].
Create React App provides a number of scripts and dependencies that help with development and with building the application for production.

=== Setting up the development environment

.Procedure
. On Fedora, run the following command to install npm:
+
[source,shell]
----
sudo dnf install npm
----

For more information about installing npm, see https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[Downloading and installing Node.js and npm].

=== Install npm dependencies

Unlike Maven, the npm package manager installs dependencies in `node_modules` under the project directory and does that only when requested by running `npm install`.
Whenever the dependencies listed in `package.json` change (for example when you pull changes to the main branch) you must run `npm install` before you run the development server.

.Procedure
. Change directory to the front end module:
+
[source,shell]
----
cd optaweb-vehicle-routing-frontend
----

. Install dependencies:
+
[source,shell]
----
npm install
----

=== Running the development server

.Prerequisites
- npm is installed.
- npm dependencies are installed.

.Procedure
. Run the development server:
+
[source,shell]
----
npm start
----

. Open http://localhost:3000/ in a web browser.
By default, the `npm start` command attempts to open this URL in your default browser.

[TIP]
.Prevent `npm start` from launching your default browser
====
If you don't want `npm start` to open a new browser tab each time you run it, export an environment variable `BROWSER=none`.

You can use `.env.local` file to make this preference permanent.
To do that, enter the following command:

[source,shell]
----
echo BROWSER=none >> .env.local
----
====

The browser refreshes the page whenever you make changes in the front end source code.
The development server process running in the terminal picks up the changes as well and prints compilation and lint errors to the console.

=== Running tests

.Procedure
. Run `npm test`.

=== Changing the back end location

Use an environment variable called `REACT_APP_BACKEND_URL` to change the back end URL when running `npm start` or `npm run build`.
For example:

[literal]
....
REACT_APP_BACKEND_URL=http://10.0.0.123:8081
....

Note that environment variables will be "`baked`" inside the JavaScript bundle during the npm build, so you need to know the back end location before you build and deploy the front end.

Learn more about the React environment variables in https://create-react-app.dev/docs/adding-custom-environment-variables/[Adding Custom Environment Variables].

== Building the project

Run `./mvnw install` or `mvn install`.
