User Guide

Upload a Digital Twin

A building is created by uploading a single JSON file that describes its rooms and 3D layout. This page covers that file format and how to upload it, then explains private domains.

How to upload

Open the Digital Twin view.
In the left menu, click Register Building.
Select your \.json file.
Review the name, thresholds, and per-room capacity, then save. The building appears in the 3D scene.

Alternatively, from the Administrator Panel, select a domain and use Upload Building Data (JSON) to attach the building to that domain at the same time.

Figure 1 — The Register Building modal: upload the JSON, then review name, thresholds, and capacities.

The building JSON

A building cannot be built room by room in the UI; the whole structure is one file.

{
  "id": "building-main",
  "name": "Main Campus Building",
  "rooms": [
    {
      "id": "room-101",
      "name": "Lecture Hall A",
      "capacity": 120,
      "color": "#4f86c6",
      "position": { "x": 0, "y": 0, "z": 0 },
      "dimensions": { "width": 20, "height": 4, "depth": 15 }
    },
    {
      "id": "room-102",
      "name": "Study Room B",
      "capacity": 30,
      "position": { "x": 25, "y": 0, "z": 0 },
      "dimensions": { "width": 10, "height": 4, "depth": 8 }
    }
  ]
}

Building fields

Field	Type	Required	Description
`id`	string	Yes	Stable, human-readable identifier (e.g. `main-campus`).
`name`	string	No	Display name. Defaults to `id` if omitted.
`rooms`	array	Yes	At least one room object.

Room fields

Field	Type	Required	Description
`id`	string	Yes	Unique room id within the building.
`name`	string	No	Display name. Defaults to `id`.
`capacity`	number	Yes	Maximum safe occupancy; drives the dashboard status indicators.
`position`	object	Yes	`{ x, y, z }` — the room’s centre point in the 3D scene.
`dimensions`	object	Yes	`{ width, height, depth }` — the room’s size, same unit as `position`.
`color`	string (hex)	No	Default room colour (e.g. `#4f86c6`).

Coordinate system

Rooms are placed by their position (centre) and dimensions (size). The origin { x: 0, y: 0, z: 0 } is the centre of the scene.

x — left/right.
y — floor level. Ground floor uses y: 0; upper floors use positive y spaced by floor height.
z — front/back.

To place rooms side by side without overlap, offset x or z by at least width / 2 + neighbour_width / 2.

Thresholds are set after upload

Temperature limits are not part of the JSON. Set them per room or per building after upload, through Edit Room / Edit Building (see The Digital Twin.

Private domains

Every domain is either public or private:

Public domains are discoverable — any signed-in user can find them in the Domains list and request to join.
Private domains are hidden — they do not appear in the list and cannot be searched. Only invited users who know the domain can join. Private is the default.

Joining a private domain

OTP invite — your administrator shares an invite QR code; you enter the six-digit code during registration (see Account Registration.
SSO — for enterprise domains, you join through Single Sign-On, no OTP needed (see Enterprise Login (SSO).

Administrators: creating a private domain

When creating a domain in the Administrator Panel, leave Visible from outside off (the default). Share the invite QR code only with the people you want to onboard.

On this page