/
Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti
| Word | Meaning | Example |
|---|---|---|
| WebSocket | A connection the browser keeps open, so the server can push | One per open tab |
| Room | A group of connections that get the same messages | building:{id}, domain:{name} |
| Subscribe | A browser asks to join one building’s room | Opening the library page |
| Claims header | Who the caller is, set by the edge | x-gateway-claims |
| Functional core | Plain functions with no network, easy to test | “which room is this message for?” |
| Imperative shell | The part that does the network work around the core | Redis, WebSocket |
Realises part of the Telemetry Distribution domain, with dashboard: it carries live data to the people following a building. Rust, no database. Code-level page: Socket Service.
flowchart LR
D["dashboard"] -. "one feed per building" .-> S["socket"]
N["notification"] -. "alerts" .-> S
Tw["digital-twin"] -. "device dots" .-> S
S -- "who owns this building?" --> Tw
S <--> C["client, over WebSocket"]Dotted: Redis.
| Comes in on | Goes to room | Browser event |
|---|---|---|
| A building’s feed | building:{id} | telemetry |
notifications | domain:{name} | notification |
| A building’s device dots | building:{id} | Device positions |
Messages pass through unread, apart from finding the room.
flowchart LR
subgraph Shell["Shell: network work"]
CON["Connect and subscribe"]
LOOP["Redis listener"]
LOOK["Ownership lookup, cached"]
SWEEP["Lifetime sweep"]
end
subgraph Core["Core: plain functions"]
AUTH["Who is this? May they read?"]
ROUTE["Which room is this message for?"]
LIFE["How long may this connection live?"]
end
CON --> AUTH
CON --> LOOK
LOOP --> ROUTE
SWEEP --> LIFEsequenceDiagram
participant C as client
participant S as socket
participant Tw as digital-twin
C->>S: connect, with the cookie
Note over S: read claims, join domain rooms
C->>S: subscribe to building 42
S->>Tw: who owns building 42?
Tw-->>S: northfield-university
Note over S: shared organization? join building:42
S-->>C: live data from now on| Ownership answer | Kept for 60 s? | Result |
|---|---|---|
| Owners found | Yes | Join if an organization is shared |
| No owners, or unknown building | Yes | Refused |
| Lookup failed | No | Refused, the next try asks again |
digital-twin.digital-twin hiccup does not blank screens for a minute.digital-twin down must not look the same.socket closes it.client reconnects after a short wait, with a fresh cookie. That reconnect is the new identity check.client subscribes to its buildings again and fetches the gap.Example. The permission check runs only at subscribe. Ada leaves Northfield at 10:00. Her open tab keeps getting library data until its connection is closed, at most about 15 minutes later.
| Choice | Why |
|---|---|
| No domain model, no database | It only carries messages; it can be replaced at any time |
| Trust the edge’s claims | The edge already checked the pass; no second check |
| Building data per building room, alerts per organization room | No organization sees another’s data |
| A message with no organization is skipped | Sending it to everyone would leak names across customers |