Platform / Reference architecture
Operational data, with its evidence intact.
Sawariee connects installed operational systems to governed objects, inspectable insight, and verified action—without asking you to replace the controls that already work.
MirayaConcept · design-partner stage
- 01Source evidenceBACnet/IP · AHU_TB_12_04_SAT
2026-01-15T06:30:00Z - 02Governed objectAHU-TB-12-04
isPointOf → serves → TB-12-EAST - 03Transformation lineageAdapter 1.4.0 · Mapping 2.1.0
Raw record linked · UCUM unit: Cel
The operating loop
From signals to outcomes.
A shared evidence contract follows the observation through each stage. Context is added without deleting where the value came from or how certain it is.
- 01
Sense
Acquire data through vendor-neutral adapters without erasing source identity or quality.
- 02
Understand
Bind observations to governed assets, spaces, systems, and typed relationships.
- 03
Steer to KPIs
Rank analysis against the operational outcomes the city or estate has chosen.
- 04
Act
Move approved insight into a traceable workflow with explicit operational guardrails.
- 05
Prove
Verify the outcome against source evidence and an agreed baseline—not an acknowledgement alone.
Interactive architecture
Eight layers. One chain of custody.
Select a layer to inspect its responsibility and design boundaries. Each layer adds context while preserving the evidence needed to replay, explain, and verify the result.
Use arrow keys to move between layers.
Edge / gateway
Establish a controlled site boundary that acquires data, reports local health, and buffers within explicit limits when northbound connectivity is interrupted.
Required design choices
- Start with read-only profiles and use outbound-only connections where feasible.
- Bound store-and-forward by bytes, duration, source, and event class; expose stale-data or data-loss signals when limits are reached.
- Assess source clocks and keep local equipment control independent of cloud availability.
Store-and-forward is not unlimited retention or guaranteed recovery. Each site needs an agreed priority and drop policy.
This is the target reference architecture for Miraya, which is at the Concept · design-partner stage. It does not assert that every adapter, semantic mapping, deployment option, or third-party integration is already implemented or certified. Delivery claims require version-specific acceptance evidence.
Canonical observation contract
One envelope. No lost meaning.
The target Miraya contract uses operational JSON, with JSON-LD contexts where linked-data exchange is needed. Stable identity, two clocks, source quality, and provenance remain attached.
{
"@context": {
"@vocab": "https://schema.miraya.example/observation/v1#",
"id": "@id",
"type": "@type",
"brick": "https://brickschema.org/schema/Brick#"
},
"id": "urn:miraya:observation:demo:ahu-tb-12-04:sat:20260115T063000Z",
"type": [
"Observation",
"TemperatureObservation"
],
"schemaVersion": "1.0.0",
"timestamp": "2026-01-15T06:30:00Z",
"ingestedAt": "2026-01-15T06:30:00.317Z",
"source": {
"protocol": "BACnet/IP",
"standard": "ANSI/ASHRAE 135",
"siteId": "urn:miraya:site:demo:RIY-01",
"gatewayId": "urn:miraya:gateway:demo:GW-RIY-01-02",
"deviceInstance": 412004,
"objectType": "analog-input",
"objectInstance": 12,
"originalPointName": "AHU_TB_12_04_SAT",
"originalValue": 13.1,
"originalUnit": "degrees-celsius"
},
"subject": "urn:miraya:asset:demo:AHU-TB-12-04",
"observedProperty": {
"id": "urn:miraya:property:supply-air-temperature",
"label": "Supply air temperature"
},
"value": 13.1,
"unit": "Cel",
"quality": {
"sourceStatus": "no-fault-detected",
"status": "good",
"estimated": false,
"stale": false
},
"provenance": {
"adapter": {
"name": "bacnet-ip",
"version": "1.4.0"
},
"mapping": {
"id": "ahu-supply-air-temperature",
"version": "2.1.0"
},
"rawRecordRef": "urn:miraya:raw:demo:bacnet:20260115T063000Z:000184",
"chain": [
{
"step": "acquired",
"at": "2026-01-15T06:30:00.184Z",
"actor": "urn:miraya:gateway:demo:GW-RIY-01-02"
},
{
"step": "normalized",
"at": "2026-01-15T06:30:00.241Z",
"actor": "urn:miraya:adapter:bacnet-ip:1.4.0"
}
]
},
"semanticTags": {
"haystack": {
"defsVersion": "4.0",
"tags": [
"ahu",
"supply",
"air",
"temp",
"sensor",
"point"
]
},
"brick": {
"modelVersion": "1.4",
"class": "brick:Supply_Air_Temperature_Sensor",
"equipmentClass": "brick:AHU"
}
},
"relations": [
{
"type": "isPointOf",
"target": "urn:miraya:asset:demo:AHU-TB-12-04"
},
{
"type": "serves",
"target": "urn:miraya:zone:demo:TB-12-EAST"
}
]
}Replay keeps the same identity.
Stable observation and object URIs make retries idempotent. Corrections reference earlier records rather than erasing them.
Bad data never becomes a reassuring zero.
Source status, staleness, estimation, and clock uncertainty remain visible beside the governed quality state.
Every transformation stays inspectable.
Adapter and mapping versions, raw-record references, and acquisition steps connect the result back to its evidence.
Semantic federation
Explicit mappings, not semantic shortcuts.
One governed source identity can serve several consumers without each dashboard or model inventing its own interpretation.
- JSON-LD 1.1
- Governed contexts add global identity and graph semantics; the syntax alone is not an ontology.
- Haystack 4 · Brick · ASHRAE 223P
- Practical tags and formal building semantics use explicit, versioned mappings. 223P remains a proposed standard in the source architecture.
- NGSI-LD · SensorThings 1.1
- Northbound exchange mappings are added for a concrete consumer contract, not as competing internal envelopes.
- RealEstateCore · SAREF
- Optional ecosystem alignments are introduced only when an estate or partner needs them.
Protocol and interface inventory
Meet the estate where it is.
Miraya is designed as a vendor-neutral normalization and evidence layer above installed systems. Integration begins with discovery and read-only observation.
Protocol names are design targets, not universal compatibility claims. Coverage is confirmed against the tested system, firmware, protocol profile, permissions, and acceptance evidence.
01Building and industrial5 interface families
BACnet/IP · MS/TP · SC
BMS, AHUs, VAVs, chillers, and other building systems.
Pin the network, object and property identities, acquisition behaviour, units, status flags, and actual Secure Connect profile.
OPC UA
PLCs, SCADA, industrial equipment, and BMS gateways.
Test the transport, security policy, namespace, companion-model version, source timestamps, and status codes.
Modbus RTU/TCP
Meters, VFDs, PLCs, power equipment, and utilities.
Govern the device register map, addressing, byte order, signedness, scaling, units, and rollover behaviour.
KNX
Lighting, blinds, room HVAC, and sensors.
Retain group addresses, datapoint types, and project provenance without disturbing commissioned local behaviour.
LonWorks / LonTalk
Installed HVAC, lighting, and field-controller estates.
Preserve node and network-variable context; begin with passive or read-only discovery where the estate requires it.
02Metering, lighting, and power5 interface families
M-Bus / Wireless M-Bus
Heat, cooling, water, gas, and electricity meters.
Record addressing, telegram interpretation, units, tariffs, and reset behaviour. Reception does not imply control.
DALI-2
Lighting control gear, drivers, and sensors.
Map only the capabilities supported by the installed controller. Product certification is not inherited by an adapter.
DNP3
Electrical and water utility RTUs and SCADA.
Preserve object variations, quality flags, event classes, and timestamps. Controls remain disabled by default.
IEC 61850
Substations, protection equipment, and power monitoring.
Monitoring must not interfere with protection. Process-bus capture requires a separately engineered safety case.
SNMP
Network equipment, UPSs, PDUs, and gateways.
Pin MIB versions and counter semantics. Use SNMPv3 security capabilities where supported; do not silently fall back.
03Applications and enterprise5 interface families
MQTT 3.1.1 / 5.0
Sensors, gateways, industrial telemetry, and application events.
Version payload contracts by topic family. Sparkplug B is a separate profile, not an assumption for ordinary MQTT.
HTTPS / REST
Enterprise applications, cloud services, and operational platforms.
Contract-test the exact API version, pagination, retries, rate limits, schema, and permission scope.
WebSocket / webhooks
Streaming interfaces and event-driven system exchange.
Validate signatures, replay behaviour, duplicates, schema versions, and failure handling.
Documented system APIs
BMS, CMMS, ERP, visitor, lift, rostering, footfall, and ticketing systems.
Scope each connector to its documented interface, licence, permissions, and tested product release.
Controlled file exchange
Systems where a managed file interface is the appropriate boundary.
Require malware checks, schema validation, manifests, and duplicate detection.
Security and tenancy
Tenancy is enforced, not inferred.
Identity, authorization, data partitioning, and operational evidence are cross-cutting design requirements. Their exact scope and assurance are validated for each deployment.
Isolation, read-only access, segmentation, controlled accounts, monitoring, and physical controls reduce exposure; they do not add modern authentication or encryption to a legacy protocol.
01Identity and least privilege
Authenticate users, services, gateways, and connectors. Authorize each request with role- and attribute-aware least privilege, including query and export permissions.
02Tenant boundaries at every layer
Enforce tenancy during identity issuance, API authorization, stream routing, object and storage partitioning, caching, exports, and logs. A tenant ID in a payload is never an authorization boundary by itself.
03Transport security and secret handling
Use TLS and certificate validation for northbound and supported southbound connections. Keep credentials in managed secret storage, restrict and rotate them, and record access.
04Segmented OT and IT networks
Prefer outbound-only gateway connections where feasible, restrict inbound firewall paths, and provide controlled break-glass procedures. Local equipment control does not depend on cloud availability.
05Append-only operational evidence
Record mapping changes, approvals, model outputs, writes, and administrative actions in append-only audit and evidence records, with site-specific retention and legal-hold policy.
06Health and misuse monitoring
Monitor clock drift, stale sources, queue saturation, buffer exhaustion, rejected records, certificate expiry, and repeated authorization failures.
Deployment shapes
SaaS or on-premises.
Begin alongside the incumbent BMS or SCADA with read-only observation. The deployment shape changes where components run, not the evidence contract or action boundaries.
Managed platform, controlled site boundary.
Site gateways acquire and buffer operational data. The managed control plane hosts normalization, the twin, storage, analytics, and experiences. Residency and bandwidth determine what remains local.
Action guardrails
Read-only first. Writes are a separate decision.
On-premises is a deployment variant, not a promise of identical managed-service operations. Local deterministic control and life-safety functions stay in their designated systems.
- 01
Authorize the exact use case. Name targets, permitted values, schedule, owner, credentials, and allowlist before enabling writes.
- 02
Review consequential action. Record the reviewer, evidence, and model and mapping versions. AI output never becomes a safety dependency.
- 03
Fail safely. Apply preconditions, local interlocks, command expiry, and correlation IDs. Define manual operating procedures; never assume physical rollback is safe.
- 04
Verify the outcome. Confirm the result against live values and retain the evidence. A command acknowledgement alone is not proof.
Consultancy-led delivery
Start with one painful operational problem.
Bring the installed systems and the outcome you need. We will discover the estate, agree the evidence, and baseline a read-only pilot before proposing scale or governed action.