Architecture

This page describes roughly the Service and Workflow Architecture of ubTrace.

Workflow outlook

ubTrace is designed to take increasing responsibility for the Sphinx build process and artifact management. This transition happens in multiple phases, starting with user support and gradually automating more tasks.

MVP (Minimum Viable Product)

In the initial release, ubTrace expects a predefined folder structure that contains all project documentation build results in a specific format. The required structure is:

organization/project/version

This structure allows ubTrace’s multi-project feature to organize and present the data correctly.

Typically, this output structure is maintained by CI scripts to automate its creation.

../_images/ubtrace_workflow_1.drawio.png

Version 1.0

In the next phase, ubTrace will require a configuration file provided by the user. This file will include the necessary information, such as:

  • Path to the documentation build results

Additionally, the build result directory must contain another configuration file with the following details:

  • Organization

  • Project

  • Version

Using this information, the ubTrace Collector will automatically generate the required output structure.

Also internally, the vis-tree app moves into ubTrace to become a single service.

../_images/ubtrace_workflow_2.drawio.png

Version 2.0

In the long term, ubTrace will be capable of building the entire documentation without relying on Sphinx. This will be possible for the Safe Toolchain, a subset of Sphinx features and extensions that are maintained, tested, and documented according to safety-critical standards like ISO 26262.

At this stage, ubTrace will only need the location of the source files or even just a commit ID from a Git repository to build and deploy the documentation.

../_images/ubtrace_workflow_3.drawio.png

ubTrace Work Elements

This diagram illustrates the main data elements (e.g., projects, documentation) and how they are utilized in ubTrace.

../_images/ubtrace_work_element.drawio.png

Elements and their hierarchies.

ubTrace Data Model

The following diagram shows the graph-based data model used by ubTrace to manage and analyze documentation content.

../_images/ubtrace_data_model.drawio.png

Graphs and their content for ubTrace.

ubTrace Artifact Model

../_images/ubtrace_architecture.drawio.svg