/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Communication & Data Flow

Keywords on this page
WordMeaningExample
TickEverything one building reports at one momentOne batch of readings
Pub/subSend to whoever listens now; nobody listening, message goneRedis channel
TopicA log that keeps messages until readKafka alerts
Consumer groupReaders sharing one topic’s workalerts
Claims headerWho the caller is, set by the edgex-gateway-claims
HMACA signature proving a shared key was usedX-Signature
Dead-letter topicWhere messages that cannot be handled waitalerts.dlq

How the services talk, and why each talk looks the way it does.


Pick by what happens if the message is lost

StyleUsed forIf lost
HTTP with claimsA person is waitingThe person sees an error
HTTP with HMACNo person involved, like provisioningRetried on the next round
Redis pub/subLive readings, in-app alertsNothing: the next tick replaces it
KafkaBreaches, building registration, Wi-Fi ticksNot lost, read after a restart

Example. dashboard restarts for 10 seconds. Readings of those 10 seconds never reach its channel. Fine: a new tick comes, and a client that reconnects asks telemetry for the latest values. A breach in those 10 seconds waits in Kafka, because nothing else would remember it.


Who is calling

CallerProofChecked by
A personCookie with a JWTThe edge, once. Services read x-gateway-claims
A service acting for a personSame header, forwarded unchangedThe receiving service, for what it allows
A service, no personX-Signature, shared secretThe receiver
A device or collectorX-Signature, key of the buildingtelemetry

Full details: Trust & Service Mesh.


Calls between services

FromToCallProofWhy
digital-twintelemetryPUT /thresholds/buildings/{id}ClaimsKeep the limit in step after an edit
digital-twindashboardPOST /preferences/init/{id}ClaimsStarting columns, best effort
digital-twinnotificationPOST /triggerSystem claimsReport a failed provisioning
notificationdigital-twinGET /domain/{id}ClaimsWho owns this building
telemetrydigital-twinGET /domain/{id}ClaimsWho may read this building
socketdigital-twinGET /domain/{id}ClaimsMay this client subscribe
dashboardtelemetry, digital-twinGET /contractsNoneCollect the metric catalog
chatagentPOST /askClaimsAnswer a question as that person
agentdigital-twin, telemetryRead routesClaimsTool calls, under the person’s own rights
claims-gatewaytenancy/internal/memberships, /internal/provisionHMACOnce per sign-in, never per request
provisionerregistry, tenancy/internal/...HMACTurn a signup into an organization
telemetrySimulators/control/*NoneStart and stop simulated buildings

registry and tenancy only receive. Only claims-gateway talks to Keycloak.


Messages

Redis channels

ChannelFromToCarries
telemetry:rawtelemetrydashboardOne envelope per tick
telemetry:filtered:{buildingId}dashboardsocketSame bytes, per building
notificationsnotificationsocketOne alert, for one organization
twin:devices:{buildingId}digital-twinsocketEstimated device dots, no ids, never stored

Kafka topics

TopicFromToGroupCarries
alertstelemetrynotificationalertsOne message per breach of a field
alerts.dlqnotificationNobody yetAlerts that could not be handled
building-registration-requesteddigital-twintelemetrybuilding-registrationsNew building and its rooms
building-registration-completedtelemetrydigital-twinbuilding-registrations-completedready or failed
wifi-observationstelemetrydigital-twinwifi-observationsReceived Wi-Fi ticks, kept 10 min
estimated-occupancydigital-twintelemetryestimated-occupancyRoom counts, stored as readings

All names come from schemas/, never typed by hand in a service.

Two services never share a group

A group shares the work: each partition goes to one member. These topics have one partition, so in a shared group one service would read everything and the other nothing. Copies of one service do share a group.

Renaming a group replays the topic

No saved position means reading from the start. Harmless for registration, since every write is an upsert. For alerts, old breaches go out again as real pushes, limited only by the cooldown. Wait for retention to pass, or move the new group to latest first.


Flows

A reading reaches the screen

sequenceDiagram
    participant S as Sensor
    participant T as telemetry
    participant D as dashboard
    participant W as socket
    participant U as Browser
    S->>T: POST /ingest, one batch, signed
    Note over T: check signature, validate, store
    T-->>S: 202
    T->>D: telemetry:raw
    Note over D: read buildingId only
    D->>W: telemetry:filtered:{id}
    W->>U: "telemetry" to room building:{id}

A breach reaches a person

sequenceDiagram
    participant T as telemetry
    participant N as notification
    participant Tw as digital-twin
    participant W as socket
    participant P as Push provider
    participant U as Person
    Note over T: a value is over its limit
    T->>N: Kafka alerts
    Note over N: cooldown set? stop here
    N->>Tw: GET /domain/{id}
    Tw-->>N: northfield-university
    N->>W: Redis notifications
    W->>U: "notification" to room domain:{name}
    N->>P: Web Push
    P->>U: phone or laptop notification

A building is registered

sequenceDiagram
    participant A as Ada
    participant Tw as digital-twin
    participant T as telemetry
    A->>Tw: upload
    Note over Tw: validate, then save the job
    Tw-->>A: accepted, with a handle
    Note over Tw: worker builds the twin
    Tw->>T: building-registration-requested
    Note over T: store rooms and names
    T->>Tw: building-registration-completed
    Note over Tw: job is ready or failed

Wi-Fi ticks

flowchart LR
    C["Collector"] --> T["telemetry: check, count"]
    T -- "wifi-observations" --> Tw["digital-twin: estimate"]
    Tw -- "twin:devices" --> S["socket"]
    Tw -- "estimated-occupancy" --> T

Bytes go on as received, and unknown fields are refused, so a stray MAC address cannot reach Kafka. Details: Wireless People Flow.

Sign-in

sequenceDiagram
    participant U as Person
    participant G as claims-gateway
    participant K as Keycloak
    participant N as tenancy
    U->>K: sign in, OIDC with PKCE
    K-->>U: code
    U->>G: exchange
    G->>K: verify
    G->>N: memberships, HMAC
    Note over G,N: none yet? provision one
    G-->>U: cookie with the internal JWT, 15 min

Later requests need no call to tenancy. The app renews every 10 minutes.

Signup

sequenceDiagram
    participant C as New customer
    participant R as registry
    participant P as provisioner
    participant N as tenancy
    C->>R: POST /organizations
    R-->>C: provisioning
    loop every 15 s
        P->>R: anything pending?
    end
    P->>N: create the domain
    P->>R: ready or failed

A 409 from tenancy counts as success, so a repeat is safe.

A question to the assistant

sequenceDiagram
    participant U as Browser
    participant C as chat
    participant A as agent
    participant Tw as digital-twin
    participant T as telemetry
    U->>C: question
    C->>A: POST /ask, same claims
    A->>Tw: tool call, same claims
    A->>T: tool call, same claims
    A-->>C: answer
    C-->>U: stream

The same access rules apply as if the person had called directly. The assistant holds no rights of its own.