Traceability FOSS

Trace-X is a system for tracking parts along the supply chain.

A high level of transparency across the supplier network enables faster intervention based on a recorded event in the supply chain. This saves costs by seamlessly tracking parts and creates trust through clearly defined and secure data access by the companies and persons involved in the process.

Table of Contents

• Trace-X
  • How to contribute
  • Releasing
  • Environments
  • The frontend application
    • Challenges and solutions
    • Prerequisites
    • Installation
    • Getting started
    • Application authentication
    • Application architecture & patterns
    • User guide
  • The backend application
    • Prerequisites
    • Installation
    • Running tests
      • Unit tests
      • Integration tests
      • Running all tests
  • API documentation
  • Container Image
  • License

How to contribute

A detailed guide on how to contribute can be found here.

Releasing

Here is our Releasing guide.

The frontend application

This application serves as a user entry point to the Catena-X network.

It's written in Typescript based on the Angular framework. We decided on using Angular because of two important aspects. Firstly, Angular comes with strict guidelines, which makes it harder to start working on for new developers, but for established developers it is easy to start working with. Secondly, Angular scales perfectly in the long run. Because of the restricted possibilities and stricted guidelines it is hard to implement multiple solutions for the same problem. e.g. Storing data or routing. With that in mind it made sense it chose Angular for an open source project.

Source files are exposed statically through the NGINX web server.

Challenges and solutions

"Visualisation of traceability" is one of our most important feature, but once was one of our biggest problems. We wanted to achieve something that is visually pleasing, is easy to use and performs very good in a browser application. Our first approach was to use HTML canvas. But it turned out it is hard to perform accurate actions inside a canvas. That is why we decided on using the D3 library. D3.js is a JavaScript library for manipulating documents based on data. D3 helps you bring data to life using HTML, SVG, and CSS. Because it uses SVGs, we knew it will perform great. And we are able to have pinpoint accuracy when it comes to user actions.

Frontend Prerequisites

• Node.js 18
• Angular CLI
• YARN

Frontend Installation

• see Installation guide

Getting started

Clone the source locally:

$ git clone [email protected]:eclipse-tractusx/traceability-foss.git
$ cd traceability-foss/frontend

Install prerequisites:

1. install node.js

$ npm install --global yarn
$ npm install -g @angular/cli
$ yarn install

Start application withyarn start and navigate to http://localhost:4200.

Application authentication

Please find here some important information about the app authentication.

Application architecture & patterns

This architecture gives you a roadmap and best practices to follow when building an application so that you end up with a well-structured app.

User guide

A detailed explanation of how to use the application.

The backend application

Backend Prerequisites

• JDK 17
• Docker Engine

Backend Installation

• see Installation guide

Running tests

Unit tests

To run unit tests invoke following command:

mvn clean test

Integration tests

Product Traceability FOSS Backend relies on Testcontainers library in order to provide persistence layer, thus Docker Engine is required to be running.

To run integration tests via command line, invoke following command:

mvn -pl tx-models,tx-backend,tx-coverage -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn -B verify

Running all tests

To run all tests invoke following command:

mvn -DskipTests=false clean verify

Please note that this task depends on integrationTest task, so it's required to have Docker Engine running.

API documentation

The project follows OpenAPI Specification in order to document implemented REST Endpoints. The documentation can be found under /openapi directory or can be viewed in the Swagger UI accessing the url: {projectBasePath}/api/swagger-ui/index.html

License

Apache License 2.0

Notice for Docker image

This application provides container images for demonstration purposes.

Eclipse Tractus-X product(s) installed within the image:

DockerHub Backend: https://hub.docker.com/r/tractusx/traceability-foss DockerHub Frontend: https://hub.docker.com/r/tractusx/traceability-foss-frontend

• GitHub: https://github.com/eclipse-tractusx/traceability-foss
• Project home: https://projects.eclipse.org/projects/automotive.tractusx
• Dockerfile Backend: https://github.com/eclipse-tractusx/traceability-foss/blob/main/Dockerfile
• Dockerfile Frontend: https://github.com/eclipse-tractusx/traceability-foss/blob/main/frontend/Dockerfile
• Project license: Apache License, Version 2.0

Used base image

• eclipse-temurin:20-jre-alpine
• Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin
• Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin
• Additional information about the Eclipse Temurin images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.