Introduction

Hexastate has built a real-time event-driven microservices app focused towards production data. Our vision is to create the only app needed for tracking and analyzing production data of various kinds.

The app consist of a backend and a frontend. The backend has an ingestion layer, an analysis layer, and a public API.

Note

The public API allows by default for 100 requests per minute. Beyond that request rate, 429 statuses will be thrown.

Ingestion

The ingestion layer allows for pushing messages into the app. The ingestion layer primarily accepts messages that are recorded by sensors. However, other message types are over time integrated with the app.

The ingestion layer consist of several different services. Some of the highlighted features of the services are:

Subscribing to the "external world" (MQTT server and 3rd-party APIs).
Parsing and data validation of incoming messages.
Mapping of messages with objects.
Redirecting messages to their correct destinations.
Collecting fragment messages into complete measurements (relevant for large measurements like FFTs).
Horizontally scalable ensuring real-time ingestion support at any scale.
Securing data with frequent backups.

You can read more of the ingestion layer here.

Backend

The app backend currently consist of 8 services handling everything from authentication and authorization, factory structuring, device connectivity and management, analytics data interactions, maintenance, dashboards, etc.

Each service exposes a REST API and in several cases also a GraphQL API. The REST API performs CRUD actions and relatively simple backend requests beyond the CRUD actions. The GraphQL APIs doesn't contain a single mutation, as they are focused only on queries and subscriptions due to their flexibility and performance benefits. At the time of writing, the GraphQL APIs doesn't have publicly available documentation. However, it is our intention to prepare documentation for these APIs in the future.

Each service has its own documentation either as redoc or swagger. Links for the redoc documentation for each service can be found in the API Docs section of this page.

Frontend

Besides the REST API, the app is also accessible from a frontend. This is a progressive web app (PWA) you can access from your browser and your mobile. You can find the app at this link.

Whitelabeling

Furthermore, Hexastate offers whitelabeling of the app. The whitelabeling package includes branding the app with your own logos, favicon, and color scheme of main components (like buttons, sidebar, and similar).

Info

Whitelabeling of Hexastate's app is only available on the Enterprise platform plan.

Authentication

Hexastate employs JSON Web Tokens (JWT) for authentication. This method ensures secure and efficient user verification across our microservices.

Obtaining a JWT

To authenticate, users must provide their email and password. Upon successful authentication, a JWT is issued. This token has a short lifetime to enhance security.

Using the JWT

For accessing protected endpoints, include the JWT in your API requests. The token should be added to the HTTP header as follows:

Authorization: Bearer <your_token>

Key Points:

Short-Lived Tokens: JWTs are designed to expire quickly to minimize security risks. Users will need to re-authenticate periodically.
Secure Transmission: Always use HTTPS to ensure the JWT is transmitted securely.
Token Structure: JWTs consist of three parts: Header, Payload, and Signature. Each part is Base64Url encoded and separated by dots.

Here’s an example of a typical JWT structure:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Authorization

The app uses role-based access control (RBAC).

Role-Based Access Control (RBAC) is a method of regulating access to resources based on the roles assigned to users within an organization. Instead of assigning permissions directly to users, RBAC assigns permissions to roles, and users are then assigned to these roles. This simplifies the management of user permissions and enhances security by ensuring that users only have access to the resources necessary for their roles.

For API documentation on authentication and authorization, visit the redoc for the authentication service.

API Docs

This section covers the docs for each individual API service in the backend. It links to the sandbox environment of each service. The production environment will be available on the same URL if the "sandbox" substring is removed from the URL.

Auth

The "Auth" service is responsible for authentication and authorization in the system, and exposes an API for managing organizations, users, roles, and invitations.

The app uses JWT authentication based on user email and password. The access token has a relatively short lifetime.

Automations

Exposes a REST API for managing automations. Organizations can set up their own custom automations in the app. An automation could be triggering the creation of a work order if a machine changes condition.

Factories

The "Factories" service is responsible for the setup and "design" of factories and all subcomponents like areas, production lines, assets, etc. This is also the service in which sensors and gateways are registered in the system. From the factory service, you will also be able to get the connectivity status of both sensors and gateways, as well as the state of machines.

Furthermore, the factory service keeps records of the placement of sensors, and these logs will also be retrievable from this API.

OEE

The "OEE" services exposes an API for calculations related to the OEE of machines. This includes product rate, availability, performance, quality, and so on. Furthermore, the service exposes an API for production planning with products, batches, and templates.

Maintenance

A minimalistic CMMS for managing maintenance activities like planning and processing work orders with ability to use templates, and setting up recurring work orders either by calendar schedule or by operational hours of machines. This service is also integrated with CMMS partner apps for synchronizing maintenance activities with other CMMS apps or for triggering work orders based on events happening in Hexastate's system.

Energy

The "Energy" service is responsible for calculations and events related to energy monitoring of production machines. This service utilizes power data from sensors to determine the energy, power, and standby consumption, as well as the estimated emissions and potential savings based on the location of the factory in which the sensors are installed at.