Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

System Architecture Overview

Who this is for: Anyone who wants to understand how the SandGrain pieces fit together before integrating, deploying, or operating them.

What you'll learn: The high-level architecture, how the components talk to each other, and the path a single authentication takes through the system.

The shape of the system

SandGrain is built in layers, and the software is split across a few cooperating components:

  • Device SDK (test_device) runs on the unit that holds the crypto Token.
  • Gateway SDK (test_gw) relays and orchestrates authentication between devices and the cloud.
  • Cloud SDK agent (sandgrain-cloud-app) is the cloud-side counterpart that answers authentication requests.
  • TrustBridge backend (tb-be, a NestJS API) and frontend (tb-fe) provide the management API and UI.
  • Infrastructure: MySQL (tb-mysql) for storage and a Mosquitto MQTT broker (tb-mosquitto) for device messaging.

How the components connect

  • Device SDK to Gateway SDK over a TCP transport.
  • Gateway to Cloud/Server over MQTT (Mosquitto).
  • Gateway to TrustBridge backend over HTTP, to sync its device whitelist.
  • Frontend to backend over HTTP; backend to MySQL for persistence.

The SDK never assumes a specific transport. Where the bytes actually travel is decided in the Portability Layer, which is what makes the same SDK run on a PC, a Raspberry Pi, or an embedded MCU.

See The SDK Layered Architecture.

The path of one authentication

A single device authentication flows like this:

  1. The Device sends its identifier to the Gateway.
  2. The Gateway resolves that identifier against its auth_db to retrieve the Token ID (TID).
  3. The Gateway asks the cloud (CyberRock) to generate a Challenge Word (CW) for that TID and relays it to the Device.
  4. The Device's crypto chip computes a Response Word (RW) and echoes the CW back.
  5. On a clean CW echo, the Gateway forwards the RW to CyberRock, which decides AUT_OK, CLAIM_TOKEN, or AUT_NOK.
  6. If the CW echo differs but stays within CW_BITFLIP_THRESHOLD, the Gateway builds candidate CWs and checks each against CyberRock (this is Error Management). A difference above the threshold fails immediately.
  7. The result is returned to the Device and recorded.

For the full step-by-step with the gw_log progression,

see The Authentication Flow & Error Management.

Where the boundary is

The Client Platform Libraries (the operating system, transport stacks, and drivers) sit outside the SDK boundary. Everything platform-specific is confined to the Portability Layer, so the core protocol logic never changes when you move to new hardware.