/

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

Architecture Overview

Keywords on this page
WordMeaningExample
ServiceA program deployed on its owntelemetry
EdgeThe one door between the internet and the servicesCaddy locally, Istio in the cluster
BrokerA middleman that carries messagesRedis, Kafka
Bounded contextOne domain, as owned by one or more servicesAlerting is notification
CedarThe language Ambitwin’s access rules are written inpolicy.cedar
TenantOne customer organizationNorthfield
Control planeServices that run the platform, not the productregistry, provisioner

Six domains become twelve deployed parts. This page shows how, then how they run.


From domain to services

DomainServicesStore
Identity & AccessKeycloak, claims-gateway, tenancy, registry, provisionerPostgreSQL
Building Managementdigital-twinMongoDB
Telemetry IngestiontelemetryPostgreSQL + TimescaleDB
Telemetry Distributiondashboard, socketMongoDB, socket has none
AlertingnotificationMongoDB, Redis for the cooldown
Knowledge & Assistancechat, agentMongoDB, PostgreSQL + pgvector

Plus client, the Vue app everyone uses.

Why Identity needs four services:

A signup has no user yet, and a sign-in needs no new customer. They change for different reasons.


The whole picture

flowchart LR
    B["Browser"] --> E["Edge"]
    S["Sensors"] --> E
    E --> I["claims-gateway, tenancy"]
    E --> T["telemetry"]
    E --> Tw["digital-twin"]
    E --> C["chat, agent"]
    Tw == "Kafka" ==> T
    T == "Kafka" ==> N["notification"]
    T -. "Redis" .-> D["dashboard, socket"]
    N -. "Redis" .-> D

Thin arrow: a request. Dotted: Redis, may be lost. Thick: Kafka, kept. To keep it readable this shows the main paths only. Communication & Data Flow lists every one.


Rules of the structure

RuleReason
One database per service, never reach into another’sA model cannot leak through shared tables
Services keep no sessionWho is asking travels with each request
One service, one domainA change stays in one place
High volume goes over a brokerA slow reader never holds back a sensor
Every outbound HTTP call has a timeoutA hang gives no error, so no fallback runs
Shapes that cross a service live in schemas/Two sides cannot drift apart unnoticed
The frontend keeps state in composables and components; a global store only when several screens share itLess hidden state to reason about

A change that breaks one of these is rejected, even with CI green. Rules for how a change is made: Toolchain Overview.


Same idea, different word

The domain speaks plainly. The code uses older names.

DomainCode
OrganizationDomain
PassJWT, x-gateway-claims
LimitThreshold
BreachAlertEvent
FocusBuilding preferences, columns
ReadingOne entry of a TelemetryEnvelope

Where code and domain disagree

The domain is right until someone decides otherwise. Each line is a to-do or a change to the domain.

Domain saysCode does
One breach, one alertOne alert per breaching reading, muted for 300 s per room and field. A long breach alerts every 5 minutes
News: Breach Started, Breach EndedNo breach is kept, and nothing says it ended
Staff can edit roomsRooms are fixed at upload, there is no route to change them
Three rolesFour in roles.json: admin also exists
Starting Focus comes from Building Readydigital-twin calls dashboard directly, best effort

Shared code

Never deployed, always built into a service.

FolderHoldsUsed by
backend/libs/auth-contractsToken shape, role ladder, HMAC signingGo services
backend/libs/auth-middlewareVerify a JWT, or read the edge’s headerclaims-gateway, tenancy
backend/libs/auth-policyThe one Cedar bundleEvery service that runs Cedar
schemas/*-schemaRust crates for shared shapesRust services
schemas/fixtures, schemas/jsonExamples every language must parse, written contractsAll

Two ways to run it

LocalCluster
Started withjust stack devjust k8s create
EdgeCaddyIstio gateway
Checks the tokenforward_auth to claims-gatewayRequestAuthentication at the gateway
Between servicesPlain, on Docker networksmTLS, by ztunnel
KeycloakIncludedNot in these manifests

Same paths, same gates. Differences are listed in Trust & Service Mesh.


Routes

Same table on both edges.

PathGoes toGated
/gatewayclaims-gatewayNo: client has no token yet, it gets one here
/tenancytenancyYes
/twindigital-twinYes
/telemetrytelemetryYes
/telemetry/ingest, /collector, /observationstelemetryNo, signed with HMAC instead
/dashboarddashboardYes
/notificationnotificationYes
/chatchatYes, streams answers as SSE
/agentagentNo, see Trust
/socket.iosocketYes
/clientNo

registry and provisioner have no route: nothing outside may reach them.

Exact paths

The three open telemetry paths are exact, and listed by hand on both edges. A sub-path falls under the gate and answers 401.