🏛️ Architecture guidelines

This page goes over the architecture guidelines of the Flowcontrol project. It contains information about how the project is structured, etc.

🏗️ Our architecture

This diagram reflects our staging and production setup.

DIAGRAM STILL NEEDS UPDATE

For a detailed overview of the architecture, look at the diagrams in the documentation folder in the repository.

Development

For development purposes, some changes are made, which will be explained later on.

🌐 Nginx

The Nginx reverse proxy is the entry point for all incoming requests. It routes any traffic arriving at the server to the correct module. This can be the frontend, backend, Keycloak, etc. This way, the Nginx reverse proxy acts as a gateway for all incoming traffic. It also includes SSL termination, which means that all incoming traffic is encrypted and decrypted by the Nginx reverse proxy.

🔀 Backend modules & gateway

As you can see in the C1 diagram, all backend modules are connected to the spring cloud gateway. This centralized gateway is responsible for routing requests to the correct backend modules (we use context paths for this). You can compare this to the Nginx reverse proxy, but then only for the backend modules. We use eureka for service discovery, which means that the gateway knows where all the backend modules are located.

The backend modules are all microservices that are responsible for a specific part of the application.

🛠️ Development setup

For development, we use Docker to run the project locally. To simplify the setup, we have made some changes to the architecture. This includes a database in the docker network instead of an external server, not running the Nginx reverse proxy, exposing some ports for the modules, etc.

🗄️ Database

The database is running in the docker network. This means that the database is not running on an external server, but in the same network as the other modules. This changes little for the other modules, but it does make the setup easier, since we are in full control over the database.

🔑 Keycloak

When working on your local computer, keycloak will be running on localhost. This causes some issues since the modules that communicate with keycloak will not be able to reach the keycloak service. To reach this container in the network, they try to connect to keycloak-service (the container name). Because of this, the issuer of the tokens will be wrong (this will point to localhost), where the modules expect that to be keycloak-service.

To fix this, you need to add a line to the hosts file on your machine. This differs based on if you are on Windows or Linux.

For Windows

Open a text editor with administrator rights (e.g. notepad) and open the file C:\Windows\System32\drivers\etc\hosts. Add the following line:

127.0.0.1    keycloak-service

Then save the file and exit. For this to work, you might need to restart your computer.

For Linux

Run:

sudo nano /etc/hosts

This requires you to insert your password. Once you are in the file, add the following line:

127.0.0.1    keycloak-service

Then save the file and exit. For this to work, you might need to restart your computer, based on your linux distribution/version.

⛩️ Port numbers and services changes for development

To access the Keycloak service, the Flowcontrol gateway, and the client from outside the local docker network, the following ports need to be configured to be open:

• Keycloak service port: 8180
• Flowcontrol gateway port: 8762
• Client port: 8080

INFO

In our staging and production setups, these ports are not exposed since all the traffic goes via the nginx reverse proxy. For development purposes, these ports have already been exposed in the docker-compose file.