Key Concepts

Consystence is an AI-native operating system for industrial sites — built for mining, coal handling and preparation (CHPP), and process plants. This page is a primer on the concepts you will meet everywhere else in these docs. Each section is deliberately short and links to the page that covers it in depth.

If you would rather see it running first, start with the quickstart and come back here for the “why”.

The deployment topology

A Consystence deployment is a chain from the browser down to physical field hardware. The platform tiers are edge → site server → cloud, each degrading gracefully if the link to the next is lost; the client and the field hardware bracket that chain. Each part has a narrow job and a defined protocol to its neighbour:

flowchart TB
  CP["Account control plane<br/>account.consystence.com · id.consystence.com"]
  B["Client<br/>browser · CLI · WinUI3"]
  S["Consystence Server<br/>{slug}.consystence.com · .dev"]
  E["Edge runtime<br/>PLCnext VL3 · Nvidia Orin"]
  G["PLCnext border gateway"]
  F["Field devices"]
  CP -. provisions orgs .-> S
  B --> S
  S --> E
  E --> G
  G --> F

• Client — a browser is the primary client today, talking to the server over SignalR. The csy CLI client and a Windows-native client are also first-class (see Server-driven UI).
• Consystence Server — the org runtime (sessions, the process and device model, the real-time pipeline). Next to a plant it runs in Site mode and speaks to the edge — or acquires controllers directly itself, over the same shared driver layer the edge uses; in the cloud the same code runs in Cloud mode for fleet views and analysis.
• Edge runtime — a small, network-resilient runtime that sits next to the plant and speaks to the controllers (see the edge).
• PLCnext border gateway — the primary path to field devices, providing the IT/OT boundary.
• Field devices — controllers, IO racks, VFDs, protection relays, and sensors.

The server-to-edge link is gRPC (over HTTP/2 TLS today; HTTP/3/QUIC is planned but not yet enabled server-side); the edge reads and writes PLCnext GDS/PORT variables over gRPC-on-a-Unix-domain-socket; the gateway in turn speaks CIP / EtherNet-IP to the field network. The full picture is in the architecture overview and PLC communication.

The account control plane and cells

Above the cells sits the account control plane (account.consystence.com, with id.consystence.com as the identity provider). It is where individual accounts live, where organisations are created, and from which tenant orgs are provisioned into cells. A cell is a server deployment that hosts tenant orgs, reached through the org’s public subdomain ({slug}.consystence.com / .dev); the control plane is never in the runtime data path between a plant and its operators.

Roadmap

The control plane and billing run in production behind launch gates — tenant creation passes an operator approval gate, and self-serve signup is not yet generally available; the marketplace is roadmap. Today’s deployments typically run a single server that acts as both the fleet view and the site proxy.

See cell topology for how cells and the control plane fit together.

Organisations and tenants

An organisation (org) is the ownership boundary — a customer, an integrator, or an internal team. An org owns one or more tenants: a tenant is the hosted tenancy boundary, running in a cell and addressed at its own subdomain ({slug}.{domain}), with sites sitting under the tenant. The hierarchy is org ⊃ tenant ⊃ site — though today’s code maps org to tenant one-to-one, so an org and “its” tenant often read as the same thing. An org has:

• an immutable canonical id — an opaque, account-minted org_… identifier, adopted by the cell as its org.Id — the stable identity and correlation key in database rows and cross-repo references;
• a user-facing slug — the cell’s operating key (grain state on the cell is keyed on it), and the subdomain under the tenant’s canonical domain: {slug}.consystence.com for enterprise-family tenants, {slug}.consystence.dev for integrator-family tenants, sandboxes, and trials. Slug rename is not currently supported;
• a licence tier (see Licensing).

A person’s account has no inherent power of its own; it gains capabilities purely through membership in one or more orgs. The same account can be an administrator in one org and a plain member in another. The platform overview and the org & site model go deeper.

Identity: the Entra oid

Identity is provided by Entra External ID (Microsoft’s customer identity / CIAM product), reached via id.consystence.com. The stable membership key for a person is the Entra oid — the tenant-immutable object id that is the same across every relying party. Email is a verified attribute and the invitation channel; it is not the identity key, and it can change without changing who the person is.

Because Entra owns the login experience, Consystence does not run its own email/password flow, registration, password reset, or MFA — those belong to Entra. See authentication for the full model.

Sites

A site is a physical location under a tenant — a mine, a wash plant, a pump station. Crucially, a site is a path under the tenant’s subdomain, not its own domain:

acme.consystence.com/sites/riverbend

One URL, one login, one tenant boundary. There is no separate .site domain.

A site hosts the server and edge installs that run its plant. One server source tree ships as two mode-baked artifacts — the mode is stamped at publish time, not read from configuration:

• Site — an on-prem (or site-adjacent) server reading live controller state for operators and site engineers;
• Cloud — a cloud/cell server serving fleet views, provisioning, and analysis from a replicated historian, with no dependency on live site state.

This dual-mode design is detailed in the org & site model.

Membership roles

Org membership carries exactly one of three roles:

Role	What it means
owner	Full control, including billing and deleting the org.
admin	Manage the org’s members, sites, and configuration.
member	A member of the org.

The guarded invariant is admin authority: an org always retains at least one member who is an owner or an admin — a demotion or removal that would leave zero is rejected.

Authority is two-tier: the org role governs only tenant management and membership, while a separate site role is the sole authority for every site-level function — an org admin holds no site capability by that fact alone. Platform administration is a separate, audited Consystence-staff concern — not an org role. See roles.

Device types and instances

Consystence separates the reusable definition of a piece of equipment from each deployed copy of it:

• A device type is a reusable template with a dot-notation id (for example consystence.pump.centrifugal). It declares the equipment’s tags, states, alarms, and commands once.
• A device instance is a type commissioned at a specific site. It carries a site-local AssetNumber (for example PP-01) and the confirmed tag mappings to real hardware.

Authoring against types and stamping out instances keeps a fleet of pumps consistent and makes type-level reasoning (“show me every centrifugal pump across all sites”) tractable.

Device types live in a global type catalog shared across tenants, distributed as packaged type bundles (.cspkg), rather than being authored per tenant. An instance can carry per-instance overrides where a placement deviates from its type — and because types are catalog-owned, a tenant export references type ids but carries no type definitions.

The engineering model: controller, module, channel, tag

Beneath the device model is a vendor-neutral hierarchy. Consystence says controller, never “PLC”, because ControlLogix, PLCnext, and Modbus devices are all controllers:

Controller   owns the backplane and scan cycle; root of all IO ownership
  └── Module   passive hardware (DI, DO, AI, AO, comms, safety, compute)
        └── Channel   an individual IO point
              └── Tag / register   a named value in the controller's tag register

In the Consystence model, each such value is a data point: it has a dataType (Bool, Int, DInt, Real, or String), an access mode (Read, Write, or ReadWrite), and a physicalRole. The model’s hard rule (register gating) is that no model may reference a tag path that does not exist in a controller’s tag register — but note that commission-time enforcement is not yet implemented, so a bad mapping surfaces at runtime instead: samples for unknown tag paths are dropped, and reads/writes against them fail. PLC communication covers how these tags are read and written.

Server-driven UI

The UI is server-driven. The server holds the state and renders a semantic UI tree — a renderer-agnostic tree of primitives describing what a surface expresses, not how it looks. That one tree, carried over a single JSON wire format, drives multiple first-class clients:

• the browser wire renderer (the default browser surface) — the tree is carried over SignalR and rendered in the browser; the earlier server-rendered HTML path is legacy and being removed;
• the csy CLI (csy ui), shipped as a peer renderer;
• a native WinUI3 client for Windows control rooms (planned).

State lives in Orleans virtual-actor grains; each interactive UI session is backed by its own server-side session actor, keyed by session. The architecture overview explains the rendering pipeline and grain topology.

Advisory-only AI

AI is woven through the platform — it configures models, answers questions, classifies alarms and events, and explains plant state in plain language. It uses the same tool surface a human integrator would.

AI is advisory-only

The AI never commands equipment. It configures, queries, classifies, and explains; it does not issue control writes to a controller on its own authority. Hard interlocks and safety functions live in deterministic controller logic and hardwired safety relays — never in the server or AI path. On-edge machine-learning inference is roadmap, not a shipping capability.

This advisory boundary is a load-bearing safety property of the platform, and it holds end to end.

Authentication

Programmatic and human access funnel through a single multi-scheme authentication selector that picks a scheme per request:

Scheme	Used by	Token
CIAM Bearer JWT	Browser sessions	JWT issued by id.consystence.com
X-Api-Key	Partner / programmatic flows	Tenant API key, prefix csk_
Site-PIN JWT	Offline-capable site login	Locally issued, JWKS-signed JWT

Tenant API keys are minted at /api/admin/api-keys and the plaintext key is shown once. There is no separate Consystence login, registration, or password flow — those are Entra’s responsibility. Full detail is on the authentication page; the cell’s /api/* surface is documented in the API reference.

Licensing

Licensing has two independent dimensions:

• an org tier, in two families of three rungs each — the enterprise family (SME, Enterprise, Enterprise Unlimited) and the integrator family (Integrator, Integrator Pro, Certified Partner) — with Basic as the unlicensed free default. SME, Enterprise, Integrator, and Integrator Pro are purchasable by self-serve checkout; the remaining rungs are sales-led, granted by a platform operator;
• counted per-seat SKU pools (SiteServer, Edge, Agent) drawn down as installs are provisioned.

Licences are account-issued and cell-mediated, bound to a provisioned identity rather than hardware. Offline operation is supported via an account-signed ECDSA/JWKS artifact. Critically, licence grace and expiry degrade rather than kill, and never gate operator control writes — a plant keeps running.

Behind launch gates

Stripe billing and the tier/seat pools run in production behind launch gates — self-serve signup is not yet GA. The licensing page describes the full model and what is live today.

Where to next

• Quickstart — get hands-on.
• Architecture overview — the full system shape.
• Cell topology — cells and the control plane.
• The edge and PLC communication — how Consystence reaches field hardware.
• Platform, org & site model, authentication, roles, and licensing — the tenancy and access model.