/

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

Digital Twin

Keywords on this page
WordMeaningExample
TwinThe stored shape of a building: floors, rooms, sizesNorthfield Library, 3 floors
UploadOne request to register a building, tracked until doneStatus ready
WorkerA loop inside the service that builds twins from a queuePicks the next upload
PlacementWhere one sensor or router sits in the buildingRouter on floor 1, by the stairs
TrackOne phone followed from tick to tickMoves from hall to room 2
PortWhat the core needs from outside, said in its own words“store this building”
AdapterThe piece that does it with a real technologyMongoDB

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.


Who talks to 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:

ToSendsWhen
telemetryRoom limitsAfter an edit
dashboardStarting columnsAfter registration, best effort
notification“Upload failed”When a registration fails
JobIn plain words
BuildingsRegister, read, list, change owner organizations, send again to telemetry
PlacementsWhere each sensor and router sits
Wi-Fi estimateWhere phones probably are, room by room
Ownership lookupAnswers “which organizations own building X?” for the other services

Inside

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 -.-> O

Registering a building

sequenceDiagram
    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
StepWhy this way
Check before answeringA building the service would refuse is never accepted
Answer before buildingBuilding is slow, and can fail for reasons Ada cannot fix
Ada polls the handleShe sees ready or failed, never silence
Announce on Kafka, do not calltelemetry can be down; the request waits for it
Ready only on the answerSending the request is not success. telemetry saying “done” is

Estimating phones from Wi-Fi

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"]
  1. The floor is split into small cells. For each cell, the service knows how loud each router should sound there, walls included.
  2. Each phone gets the cell that best matches what the routers heard.
  3. A phone cannot jump faster than a person walks, so its last place narrows the choice.
  4. A phone unseen for a few ticks is dropped. One missed poll does not end it.

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.


Choices

ChoiceWhy
The service makes building idsThe id never depends on what a client or a database chose
Owners come from the passNo call to identity services per request
Shape treated as fixedOnly names and owners change; the live data lives elsewhere
Same size checks on every writeA bad room is refused with a clear error, never stored

Gaps