/
Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti
| Word | Meaning | Example |
|---|---|---|
| Twin | The stored shape of a building: floors, rooms, sizes | Northfield Library, 3 floors |
| Upload | One request to register a building, tracked until done | Status ready |
| Worker | A loop inside the service that builds twins from a queue | Picks the next upload |
| Placement | Where one sensor or router sits in the building | Router on floor 1, by the stairs |
| Track | One phone followed from tick to tick | Moves from hall to room 2 |
| Port | What the core needs from outside, said in its own words | “store this building” |
| Adapter | The piece that does it with a real technology | MongoDB |
Realises the Building Management domain. Rust, MongoDB. Code-level page: Digital Twin Service.
The source of truth for the shape of every building. Other services add live data on top of it.
flowchart LR
C["client, agent"] --> Tw["digital-twin"]
O["notification, telemetry, socket"] -- "who owns it?" --> Tw
Tw == "registration, room counts" ==> T["telemetry"]
T == "registration done, Wi-Fi ticks" ==> Tw
Tw -. "device dots" .-> S["socket"]Thin: a request. Thick: Kafka. Dotted: Redis.
It also calls three services directly:
| To | Sends | When |
|---|---|---|
telemetry | Room limits | After an edit |
dashboard | Starting columns | After registration, best effort |
notification | “Upload failed” | When a registration fails |
| Job | In plain words |
|---|---|
| Buildings | Register, read, list, change owner organizations, send again to telemetry |
| Placements | Where each sensor and router sits |
| Wi-Fi estimate | Where phones probably are, room by room |
| Ownership lookup | Answers “which organizations own building X?” for the other services |
flowchart LR
subgraph In["Driving adapters"]
H["HTTP"]
W["Worker"]
KC["Registration answers"]
WC["Wi-Fi ticks"]
end
subgraph Core["Core"]
UC["Use cases"]
E["Entities and rules"]
P["Ports"]
end
subgraph Out["Driven adapters"]
M["MongoDB: buildings, uploads, placements"]
KP["Kafka out"]
R["Redis out"]
O["HTTP to other services"]
end
H --> UC
W --> UC
KC --> UC
WC --> UC
UC --> E
UC --> P
P -.-> M
P -.-> KP
P -.-> R
P -.-> OsequenceDiagram
participant A as Ada
participant Tw as digital-twin
participant T as telemetry
participant N as notification
A->>Tw: upload the building
Note over Tw: check it, then save the upload
Tw-->>A: accepted, with a handle
Note over Tw: the worker picks it up and builds the twin
Tw->>T: registration requested
Note over T: store rooms, set limits
T->>Tw: registration completed
Note over Tw: upload is ready or failed
Tw-->>N: failed? tell the owners| Step | Why this way |
|---|---|
| Check before answering | A building the service would refuse is never accepted |
| Answer before building | Building is slow, and can fail for reasons Ada cannot fix |
| Ada polls the handle | She sees ready or failed, never silence |
| Announce on Kafka, do not call | telemetry can be down; the request waits for it |
| Ready only on the answer | Sending the request is not success. telemetry saying “done” is |
dashboard and room limits are sent after; a failure is logged, not fatal.Each tick says which routers hear which phone, and how loud.
flowchart LR
Tick["Wi-Fi tick"] --> Grid["Score every spot on the floor plan"]
Grid --> Prior["Weigh by where the phone was before"]
Prior --> Spot["Most likely spot and room"]
Spot --> Dots["Dots, no ids"]
Spot --> Counts["Phones per room"]Example. Router A hears a phone loud, router B faint. The cells near A and far from B score best. Last tick the phone was in room 2, next door, so room 2 wins over the hall beyond it.
socket, room counts back to telemetry.| Choice | Why |
|---|---|
| The service makes building ids | The id never depends on what a client or a database chose |
| Owners come from the pass | No call to identity services per request |
| Shape treated as fixed | Only names and owners change; the live data lives elsewhere |
| Same size checks on every write | A bad room is refused with a clear error, never stored |
dashboard, best effort, not a reaction to “Building Ready”. If it fails, the building gets no live feed until someone saves its columns.