Warning

Nightly releases are generated automatically from the latest source code and are intended for experimental purposes only. These builds may contain incomplete or untested features, bugs, or security vulnerabilities, and as such, are not for production use. Users should be aware that nightly releases may cause unexpected behavior, data loss, or system instability. Use of these releases is at the user's own risk, and it is advised to have adequate backups before testing. The software is provided as is with no guarantees or support.

System Overview¶

The system consists of several components working together. Each is responsible for a specific part of the system. The system is designed to be modular and scalable, allowing for easy extension and modification.

It can be helpful to get an understanding of the system’s architecture in order to better understand how the system works and more easily be able to find the source of an issue if one arises.

Architecture¶

Each of the components is responsible for a specific part of the system. The image above shows a simplified overview, omitting some components for clarity.

Components¶

A full list of components is provided below:

Component	Short Description
Client	Talks to the system. There are multiple implementations in different languages.
API Gateway	Provides a single entrypoint to the system, routing to the correct internal service.
Resource Gateway	Resolves requests for backend services, providing updates of their state.
Entry Gateway	Hosts webvis.js and provides endpoints for session initialization for clients.
Key Store	Handles resource signing keys and notifies system on key updates.
Admin Service	Handles administrative functions and log inspection.
Upload Service	Provides storage for user uploads.
Space Service	Provides the Space API.
Space Store Service	Provides a persistent storage API for storing and retrieving 3D spaces.
Transcoder Service	Converts CAD data to the unified l3d format usable by clients.
Measurement Service	Provides an interactive measurement API for clients to use.
Vis Service	Provides an interactive visualization API for clients to use.
Geometric Service	Provides an interactive clipping API on geometry for clients to use. Fills holes.
Tracker Service	Provides an interactive model tracking API to position AR objects.
Delivery Service	Provides an API for retrieving results of the Transcoder Service.
Query Service	Provides an API for dynamic queries of non-geometric data of Transcoder results.
Shared Session Service	Provides an interactive API for collaborating simultaneously with multiple users.
RabbitMQ	Internal service used to schedule service requests and send state changes.
PostgreSQL	Internal service storing system state and queryable data of Transcoder results.
Data Gateway	Abstract service concept used to retrieve geometry data and authorize user access.
License Server	Server hosting the instant3Dhub license. Stores client usage data for billing.
Auth Service	Sidecar service used to perform authorization and signature checks.
Transfer Service	Used in Hub Mesh scenarios to transfer transcoder results if required.
Migrate	Migrates database schemas on startup.
Prometheus	Stores OpenTelemetry metrics and provides exploration GUI.
Jaeger	Stores OpenTelemetry traces and provides exploration GUI.
PgBouncer	Pools connections to PostgreSQL to preserve resources on database side.
Postgres Exporter	Provides OpenTelemetry metrics of PostgreSQL internals.
Grafana	Provides dashboards detailing system behavior.

Client¶

Multiple clients are available to interact with the system. The clients are responsible for providing high level APIs to interact with the system. Clients are available in multiple languages.

API Gateway¶

Responsible for routing requests to the correct internal service. The API Gateway provides a single entrypoint to the system.

This service can be scaled horizontally to handle more requests.

Resource Gateway¶

Responsible for resolving requests for backend services. The Resource Gateway will provide service state updates to clients. If requested data requires transcoding, this service will queue a request to the Transcoder Service via RabbitMQ. Similarly, other on-demand services such as a client wanting to use measurements will also result in the Resource Gateway queuing a request to start a measurement service via RabbitMQ.

State updates of transcodings, measurement service readiness, and other on-demand services are provided to the clients via a websocket connection.

This service can be scaled horizontally to handle more requests.

Entry Gateway¶

The Entry Gateway hosts webvis.js and provides an initial static entrypoint for clients to interact with the system.

This service can be scaled horizontally to handle more requests.

Key Store¶

An optional service that handles resource signing keys. Only relevant if the system is configured to require signed input URIs. The Key Store keeps track of signing keys and propagates key updates to the system via RabbitMQ.

This service cannot be scaled horizontally.

Admin Service¶

Handles administrative functions and log inspection. Can view logs of services such as individual transcoder runs, individual user measurement sessions and more.

Also provides links to interfaces for other third party services such as Prometheus and Jaeger for further inspection.

This service is required to start at least once, as it initializes the shared volume used to store webvis.js and other static files used by the Entry Gateway.

This service cannot be scaled horizontally.

Upload Service¶

Handles user uploads triggered via the 3D Space API. Stores data on a persistent volume. Cannot be interacted with directly by clients.

This service can be scaled horizontally.

Space Service¶

Provides the 3D Space API. This API is used to create, and modify 3D spaces. Internally it uses the Shared Session Service to perform requested actions.

This service can be scaled horizontally.

Space Store Service¶

Provides a persistent storage API for storing and retrieving 3D spaces. Data is persisted in PostgreSQL.

This service can be scaled horizontally.

Transcoder Service¶

Receives transcoding tasks from RabbitMQ and processes them. The Transcoder Service converts CAD data to a unified internal format usable by clients.

Each transcoder pod can handle a configured number of transcoding tasks concurrently. Memory usage depends mostly on input file size, allowing configuration of either a higher or lower number of concurrent workers depending on average expected size.

This service can be scaled horizontally. See Autoscaling for an example configuration scaling based on RabbitMQ queue length.

Measurement Service¶

Receives measurement service requests from RabbitMQ and processes them. The Measurement Service provides an interactive measurement API for clients to use.

For each measurement task, a new executable is started internally, which provides the API required by clients to perform measurements. Each of these only handles one user session at a time.

This service can be scaled horizontally.

Vis Service¶

Receives visualization service requests from RabbitMQ and processes them. The Vis Service provides an interactive visualization API for clients to use.

For each visualization task, a new executable is started internally, which provides the API required by clients to perform visualizations. Each of these only handles one user session at a time.

The service is primarily used by the Unreal client to perform visibility calculations in order to reduce the amount of data required by the client.

Requires a GPU in the cluster to run. This service can be scaled horizontally.

Geometric Service¶

Receives geometric service requests from RabbitMQ and processes them. The Geometric Service provides an interactive clipping API on geometry for clients to use.

For each geometric task, a new executable is started internally, which provides the API required by clients to perform geometric operations. Each of these only handles one user session at a time.

This service can be scaled horizontally.

Tracker Service¶

Receives tracker service requests from RabbitMQ and processes them. The Tracker Service provides an interactive model tracking API to position AR objects.

For each tracker task, a new executable is started internally, which provides the API required by clients to position AR objects. Each of these only handles one user session at a time.

The service requires a GPU in the cluster to run.

This service can be scaled horizontally.

Delivery Service¶

Provides an API for retrieving results of the Transcoder Service. The Delivery Service is shared between all clients and is not started on-demand. It is expected to be running at all times.

This service can be scaled horizontally.

Query Service¶

Provides an API for dynamic queries of non-geometric data of Transcoder results. The Query Service is shared between all clients and is not started on-demand. It is expected to be running at all times.

Queries are performed against PostgreSQL.

This service can be scaled horizontally.

Shared Session Service¶

Receives shared session requests from RabbitMQ and processes them. The Shared Session Service provides an interactive API for collaborating simultaneously with multiple users.

For each shared session, a new executable is started internally, which provides the API required by clients to use shared sessions. Each processes is then shared between users requesting the same session.

Shared sessions attempt to load the 3D Space with the same ID from the Space Store Service on startup. If the space does not exist, a new space will be created and saved once the shared session ends.

This service can be scaled horizontally.

RabbitMQ¶

RabbitMQ is used as a task scheduler and event bus. It is used to schedule service requests and send state changes. RabbitMQ takes care of distributing work to the appropriate services.

This service cannot easily be scaled horizontally.

PostgreSQL¶

PostgreSQL stores system state and queryable data of Transcoder results. Configuration allows moving each part to separate external databases to improve stability and performance of the system.

This service cannot easily be scaled horizontally.

License Server¶

Stores usage data for billing purposes and licensed data formats. If configured via serial key, usage data and license information is automatically synchronized with threedy.

If running in an air-gapped mode, the license server is required to be installed on a dedicated, host-bound machine. Usage reports must be manually submitted to threedy for updated licenses.

This service can be scaled horizontally.

Data Gateway¶

A Data Gateway is an not a service provided by the system, but an abstract service interface the system expects to find when attempting to load or authorize external data. The interface expects HTTP GET and HTTP HEAD methods to be implemented for requested data.

Even a simple file server such as nginx can be used to provide the required interface.

For more information see Data Gateway Integration.

Auth Service¶

Several pods have sidecars with the auth service running alongside the main respective service. These are:

API Gateway: The auth service is used to check correct signatures in URLs used to access internal services.
Delivery Service: The auth service is used to check signatures for accessing transcoder results. Additionally, external HEAD requests are sent to the URL of the transcoder source to check if the current user has permissions to access the data.
Query Service: Same behavior as the Delivery Service, except results are queried from PostgreSQL.

Transfer Service¶

Responsible for transferring transcoder results between different instant3Dhub instances. This requires data pool configuration to assign certain rules to other instant3Dhub instances, and users to then request the transfer.

This service can be scaled horizontally.

Migrate¶

Responsible for migrating database schemas on startup. This service is required to start at least once to ensure the database is correctly set up.

This service runs as a Kubernetes job. Other pods will wait for the job to complete before starting.

Prometheus¶

Optional service which gathers metrics from all internal services. Endpoints are discovered via SRV records provided by Kubernetes.

If Grafana is enabled, Prometheus will be configured as a data source for dashboards. If Grafana is not enabled, Prometheus queries are possible via the Prometheus GUI accessible on the Monitoring tab of the Admin Service.

Jaeger¶

Optional service which receives OpenTelemetry traces from all internal services.

If Grafana is enabled, Jaeger will be configured as a data source for trace data. Together with Prometheus, this allows correlating selected metrics with respective traces through exemplars.

If Grafana is not enabled, Jaeger traces are viewable via the Jaeger GUI accessible on the Monitoring tab of the Admin Service.

PgBouncer¶

Used to pool connections to PostgreSQL to preserve resources on the database. Pooling is done on a transaction level, allowing for a high number of simultaneous connections to be handled by PostgreSQL. Normally each PostgreSQL connection requires a separate PostgreSQL process, which can lead to high resource usage on the database side.

Postgres Exporter¶

Provides OpenTelemetry metrics of PostgreSQL internals. This allows monitoring things such as connection count, query performance, and more.

If Grafana is enabled, a dashboard detailing this information will be enabled by default.

Grafana¶

Optional service which provides a GUI for Prometheus and Jaeger data. If enabled, Grafana will be available on the splash page of the installation.

Several dashboards are provided by default, including:

General Overview: Provides metrics detailing error rates, delivery times, memory usage, and more.
Transcoder Overview: Provides metrics detailing transcoder internals, such as time taken per transcoding step.
PostgreSQL Overview: Provides metrics detailing PostgreSQL internals, such as connection count, query performance, and more.