The BIL Validator Tool is a web based validation tool for eCMR documents notarized by the BIL eCMR platform. Furthermore, the tool can be built as native App using the Electron framework.
git ^2.24.0
node ^12.16.1
npm ^6.13.4 - included with node version 12.16.1
yarn ^1.22.4
bash ^5.0.11 or similar shell engine to call scripts
// clone repository:
git clone <this-repo>
// move into project folder
cd ./validator-tool
// install dependencies
yarnThe project is divided into the following three packages:
- backend
- frontend
- native
The backend handles fetching of the eCMR data, resolving the CMR Nr. and Pin-Code and checking the validity of the given document.
The frontend sends the given PDF document or the CMR No. and Pin-Code to the backend and then displays the result of the validation and the data inside the CMR document.
The native package contains the required electron files. Each package contains its own README, which should be carefully read before using the application.
- to easily manage the monorepo-structure, the project is setup with yarn workspaces and lerna and the setup follows best-practices from the lerna and yarn documentation pages. If you don't know about lerna and yarn workspaces you can start with an introduction and a comparison to other approaches here.
- the mentioned tooling divides our project in a root-project and 3 sub-packages in the packages folder
- these sub projects are divided in:
- api: contains a nodeJS application using the NestJS framework for serving a REST-backend. This package is responsible for proxying eCMR-REST APIs and providing additional functionalities for the frontend. Additionally this module can be deployed as single backend using docker.
- web: contains a SPA (S ingle P age A pplication) written in React. This part represent the main-view of our application and can be deployed with a webserver like nginx (docker) or as single html/js/css-package.
native: contains a wrapper application with electron that bundles the api package and web package into a full native desktop application for Windows, Linux and macOS.
- additional information regarding single packages can be taken from the README in the respective package-folder
- one additional folder in the root package is e2e: this contains testing logic for e2e tests of backend/api/native packages
- there is a root
package.jsoncontaining useful scripts utilizing lerna for e.g. linting, building or testing of the whole project - just have a look at the defined scripts in rootpackage.json. - every package contains its own
package.jsonfile with its own naming scheme and can be deployed and run individually. Further information on running and building subpackages can be taken from the respective README orpackage.json. - to run a command in a subpackage, simply
cdinto a package and run the specific commands. - in the root
package.jsonfile also Docker scripts are configured to run and deploy docker containers providing the backend and web package. To use these scripts, docker and docker-compose must be installed. - Docker-images have to be built from the root directory as the whole monorepo is copied from
cwdinto the Docker build context and access to parent folders is denied when starting a build from a specific subfolder.
The project's package.json contains predefined commands for running and deploying the project for development. These commands
need to be executed from the root folder of the project. The subpackages located in the packages folder contain additional commands
for the individual packages.
The api package can be started using the following command:
yarn dev:apiFor running the frontend the following command should be used:
yarn dev:webFurthermore, starting the desktop application can be done via the following command:
yarn dev:nativedocker create \
--name=frontend \
-e BASEPATH=/ \
-e BACKEND_URL=<URL_OF_BACKEND> \
-p 8082:8082 \
ss20aseqse01/web:latest| Parameter | Function |
|---|---|
| BASEPATH | Used to set the URL of the frontend. Should start with '/' and should not end with '/'. |
| BACKEND_URL | Used to give the container the URL or IP of the backend system |
docker create \
--name=backend \
-v <PATH_TO_LOGS>:/tmp/validator/logs/
-e LOGDIR_PATH=/tmp/validator/logs/ \
-e SWAGGER_PATH=/swagger \
-p 8083:8083 \
--restart unless-stopped \
ss20aseqse01/api:latest| Parameter | Function |
|---|---|
| LOGDIR_PATH | Used to set the location for log files inside the container |
| SWAGGER_PATH | Used to set the URL for the swagger backend |
In order to run the application in a dockerized manner, please use the given docker-compose.yml file. The file contains further
docker-specific comments for the deployment.
Using Docker Compose the application with default values can be started using:
docker-compose upIf you want to supply a custom configuration for REST-Endpoints, add the following line to the api container in the docker-compose.yml:
volumes:
- <PATH TO YOUR REST CONFIG JSON FILE>:/app/restConfiguration.jsonAfter executing docker-compose up again the new config should be injected and overrides the initial configuration file.
- use an IDE like IntelliJ/Webstorm/VSCode and install plugins for development like prettier, eslint, npm-scripts, browser-debugging etc.
- use tooling like IntelliSense and language support for TypeScript, React, JS and config files like babel, eslint, editorconfig etc.
- disable IDE-indexing of node_modules as every change cases a reindex on the whole node_modules folder
- web-apps can be debugged by attaching a debugger to the dev-server started by most of the packages in background
- disable save-writes and switch to manual-saves in the IDE as the dev-servers watch file changes and build changed parts instantly - a write from IDE on every letter may cause the dev-server to build uninterrupted (activate also asterx to don't forget unsaved files)
- turn on eslint auto-detection as all eslint-config files are present in the project and the eslint is contained in the project, so there is no need to specify an extra instance with own linting-rules
- if some linting-rules are not useful, make a suggestion in a merge-request, maybe the current eslint-rules are too messy and should be sorted out
- Client side debugging with JetBrains IDEs like IntelliJ
- Disable safe writes: here or here
- Configuration of typescript with lerna
- Lerna Typescript structure - also describing module resolution with Typescript (ts references)
- Lerna managed multi-sdk project
- Another Lerna managing a frontend/backend app
- Webpack
- How to Set Up a React TypeScript Project from Scratch with Babel and Webpack: also describes how babel can be used to transform typescript.
- Bundler decision/Parcel vs Webpack