/

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

The Whole Picture

Keywords on this page
WordMeaningExample
OrganizationA customernorthfield-university
TenantSame as Organization, used when talking about keeping data apartNorthfield and Acme
TwinThe 3D copy of a real buildingThe 3D Science Hall
ReadingOne value from one room at one momentLab 2, 14:05, 27 °C
LimitThe range a value should stay in18 to 26 °C
BreachThe time a room spends outside a limitLab 2, from 14:05 to 14:20
AlertThe message sent for one Breach“Lab 2 is too hot”
PassStatement of who you are and your membershipsLia’s pass
News“This happened”, sent to whoever listensBreach Started

Two words to keep apart

  • Domain in this chapter: one area of the business, like Alerting. The six are listed below.
  • Organization: a customer, like a university. The rest of the guide and the code call this a “Domain” too. Here it is always “Organization”.

The story, in six questions

Everything comes from six questions. Each one needs the answers before it, so the order is not random.

#QuestionDomainNeeds
1Who are you, and what may you do?Identity & AccessNothing
2What does the place look like?Building Management1, to know whose building it is
3What is happening in each room, and is it OK?Telemetry Ingestion2, a reading needs a room
4How do people follow a building, live?Telemetry Distribution3, something to follow
5Who must be told, and where?Alerting1, 2 and 3
6Can someone explain all this to me?Knowledge & Assistance1, 2 and 3

Click through the map, or read the pages in this order.

Ambitwin


How the domains talk

Three ways, and only three.

flowchart LR
    B["2 Building Management"]
    T["3 Telemetry Ingestion"]
    D["4 Telemetry Distribution"]
    A["5 Alerting"]
    K["6 Knowledge & Assistance"]

    B -- "Building Ready" --> T
    B -- "Building Ready" --> D
    T -- "Reading Recorded, Breach Started, Breach Ended" --> D
    T -- "Breach Started" --> A
    A -. "which organizations?" .-> B
    K -. "what is this building?" .-> B
    K -. "what is happening?" .-> T

Solid arrow: news. Dotted arrow: a question. Identity & Access is left out because everyone holds its pass.

All the news

NewsSaid byHeard byWhat the listener does
Building ReadyBuilding ManagementIngestion, DistributionSet starting limits, set starting Focus
Reading RecordedTelemetry IngestionDistributionUpdate the building’s status
Breach StartedTelemetry IngestionAlerting, DistributionTell people, mark the room
Breach EndedTelemetry IngestionDistributionMark the room as back to normal

All the questions

Who asksWho answersQuestionWhy ask
AlertingBuilding ManagementWhich organizations own this building?Ownership is a Building Management fact, and an alert must never reach the wrong tenant
Knowledge & AssistanceBuilding ManagementWhat is this building?The assistant owns no facts
Knowledge & AssistanceTelemetry IngestionWhat is happening right now?Same

One full example

Made-up numbers, used on every page of this chapter.

Sam has a phone and a tablet. At 14:00 the lab is 25 °C. At 14:05 it reaches 27 °C.

sequenceDiagram
    participant S as Sensor in Lab 2
    participant T as Telemetry Ingestion
    participant D as Telemetry Distribution
    participant A as Alerting
    participant B as Building Management
    participant P as Sam

    S->>T: 14:00, 25 °C
    Note over T: recorded, inside 18 to 26
    T-->>D: Reading Recorded
    Note over D: Lia and Sam see 25 °C
    S->>T: 14:05, 27 °C
    Note over T: recorded, above 26, breach starts
    T-->>D: Reading Recorded
    T-->>A: Breach Started
    A->>B: Who owns Science Hall?
    B-->>A: northfield-university
    Note over A: Sam opted in to temperature alerts
    A->>P: alert on phone and tablet
    S->>T: 14:10, 27.5 °C
    Note over T: still above, same breach, no new alert
    S->>T: 14:20, 25 °C
    Note over T: back inside, breach ends
    T-->>D: Breach Ended

What to notice:


Rules that hold everywhere

  1. One owner per fact. A room’s size lives in Building Management. Its temperature lives in Telemetry Ingestion. Nobody keeps their own copy of the truth.
  2. An organization is known by its name. The name is the only thing all domains share.
  3. Tenants never see each other. This holds in every domain.
  4. What happened stays recorded. A wrong reading is fixed by a new reading, never by an edit.

How much care each domain gets

Not every domain deserves the same effort.

KindMeaningDomains
CoreThe reason customers payBuilding Management, Telemetry Ingestion, Telemetry Distribution
SupportingNeeded, but nobody picks us for itIdentity & Access, Alerting, Knowledge & Assistance

Not in this model

Left out for now: