Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti
This page documents how the Vue client talks to the backend over its one WebSocket connection — how that connection comes to exist, and how telemetry subscription is layered on top of it for components that need live sensor data. For how a reading gets from a physical sensor to the point where this connection receives it, see Dashboard architecture and Socket architecture; this page starts where those leave off — the moment a telemetry event lands in the browser.
File: frontend/src/services/socket.ts
The whole app shares a single Socket.IO client instance, created once at module load:
export const socket: Socket<ServerToClientEvents, ClientToServerEvents> = io(URL, {
autoConnect: false,
transports: ['websocket'],
withCredentials: true,
})What autoConnect does. By default a Socket.IO client opens its connection the moment it is created. Here it is created when socket.ts is first imported, at page load.
Why it is off. /socket.io is gated: the edge lets a connection through only if it carries the authentication_token cookie. At page load the user may not be signed in yet, so there is no cookie:
autoConnect | At page load, not signed in | After sign-in |
|---|---|---|
true (default) | Connects, the edge answers 401, the client retries with growing pauses | A later retry succeeds, up to 5 s after sign-in |
false (set here) | Nothing happens | App.vue opens the connection, first try succeeds |
So the client is created idle, and App.vue opens and closes it by watching the sign-in state. It connects when the user signs in and disconnects on logout:
// The socket handshake requires the auth cookie, so only connect once the user
// is authenticated; drop the connection on logout. immediate covers the initial
// state (and the false→true flip when hydrate() resolves from the cookie).
watch(
() => authStore.isAuthenticated,
(authed) => (authed ? socket.connect() : socket.disconnect()),
{ immediate: true },
)withCredentials: true is what makes this work: it’s the client-side half of the httpOnly-cookie handshake documented in Socket Service — the browser attaches the authentication_token cookie to the WebSocket upgrade request automatically, client code never reads or holds the token itself. socket.ts also owns the one piece of WebSocket-driven state that isn’t telemetry: incoming notification events are appended straight to a shared reactive socketState (message, type, timestamp, a capped 100-item list, an unread counter) that any component can read directly — notifications don’t need a bucketed, opt-in subscription model the way telemetry does, since there’s only ever one feed a connected client cares about.
File: frontend/src/stores/commons/sensorData.ts
Multiple components routinely want the same building’s same metric at once — the 3D model and the room list both read live temperature, for instance. Rather than each opening its own REST fetch, its own subscribe_building call, and its own telemetry handler, they all acquire a reference to one shared bucket, keyed by (type, buildingId):
graph TD
APP["App.vue\nconnects socket.ts on login"] --> SOCKET["services/socket.ts\none shared Socket.IO client"]
SOCKET --> STORE["stores/sensorData.ts\nSensorDataStore — buckets by (type, buildingId)"]
STORE --> HOOK["composables/useBuildingSensor.ts\nacquire on mount, release on cleanup"]
HOOK --> C1["3D model view"]
HOOK --> C2["Room list"]
HOOK --> C3["...any other component"]
SOCKET -->|"telemetry event"| STOREfunction acquire(buildingId: string, type: SensorType): SensorBucket {
const key = bucketKey(type, buildingId)
let bucket = buckets.get(key)
if (!bucket) {
const firstForBuilding = !hasBucketForBuilding(buildingId)
bucket = { data: shallowRef([]), isLoading: ref(false), error: ref(null), refCount: 0, abort: null }
buckets.set(key, bucket)
if (firstForBuilding) socket.emit('subscribe_building', buildingId)
void fetchBucket(type, buildingId, bucket)
}
bucket.refCount++
return bucket
}
function release(buildingId: string, type: SensorType) {
const key = bucketKey(type, buildingId)
const bucket = buckets.get(key)
if (bucket && --bucket.refCount <= 0) {
bucket.abort?.abort()
buckets.delete(key)
}
if (!hasBucketForBuilding(buildingId)) socket.emit('unsubscribe_building', buildingId)
}Only the first caller for a building triggers subscribe_building; only the last release for that building triggers unsubscribe_building — the socket room’s lifetime is derived entirely from whether any bucket still references that building, with no separate counter to keep in sync. acquire also kicks off a REST fetch (GET /telemetry/:type/entireBuilding?building=...) for the initial snapshot, so a component sees the last known values immediately rather than waiting for the next telemetry tick; a second acquire for the same key doesn’t refetch, it just bumps refCount and returns the existing bucket.
One global handler dispatches every incoming event to its bucket by an O(1) map lookup — there’s no per-component listener to accumulate as more components mount:
function onTelemetry(rawEvent: unknown) {
const event = rawEvent as ApiDataPoint & { type?: SensorType; buildingId?: string }
const key = bucketKey(event.type as SensorType, event.buildingId as string)
const bucket = buckets.get(key)
if (!bucket) return
const arr = bucket.data.value
const idx = arr.findIndex((d) => d.roomId === event.roomId)
if (idx >= 0) arr[idx] = { ...arr[idx], ...event }
else arr.push(event)
dirty.add(key)
scheduleFlush()
}Every touched bucket is marked dirty and flushed together on the next animation frame, rather than triggering a reactive update per event:
function scheduleFlush() {
if (rafPending) return
rafPending = true
requestAnimationFrame(() => {
for (const key of dirty) {
const bucket = buckets.get(key)
if (bucket) bucket.data.value = bucket.data.value.slice()
}
dirty.clear()
rafPending = false
})
}The flush swaps in a new array reference (.slice()) rather than notifying Vue about the same array mutated in place. This is deliberate: consumers read a bucket’s data through a computed, and Vue’s reactivity only re-notifies a computed’s dependents when the underlying value changes by identity — an in-place mutation on the same array reference would be swallowed at that boundary and never reach the views. Batching to one rAF-scheduled reference swap per bucket, instead of a reactive trigger per telemetry event, keeps Vue’s scheduler from competing with the Three.js render loop the 3D view depends on for a steady frame rate.
function onReconnect() {
for (const buildingId of new Set([...buckets.keys()].map(buildingOf))) {
socket.emit('subscribe_building', buildingId)
}
for (const [key, bucket] of buckets) {
void fetchBucket(key.slice(0, key.indexOf(':')) as SensorType, buildingOf(key), bucket)
}
}The server holds no memory of which rooms a reconnected socket was in — a fresh connection starts in no rooms at all. On connect (which also fires after every reconnect), the store re-joins every building it still has an active bucket for and re-fetches each one’s snapshot, so a dropped connection loses at most the telemetry that arrived while disconnected, not the subscription itself.
useBuildingSensorFile: frontend/src/composables/dashboard/useBuildingSensor.ts
useBuildingReadings (same file) holds a changing set of metrics: the dashboard table subscribes to whatever its columns show, so a new plugin’s column fills with no frontend change.export function useBuildingSensor(buildingId: Ref<string | undefined>, type: SensorType) {
const store = useSensorDataStore()
const bucket = shallowRef<SensorBucket | null>(null)
watch(
buildingId,
(id, _old, onCleanup) => {
if (!id) { bucket.value = null; return }
bucket.value = store.acquire(id, type)
onCleanup(() => store.release(id, type))
},
{ immediate: true },
)
return {
data: computed(() => bucket.value?.data.value ?? []),
isLoading: computed(() => bucket.value?.isLoading.value ?? false),
error: computed(() => bucket.value?.error.value ?? null),
}
}This is the only entry point a component actually uses — it never touches sensorData.ts’s acquire/release directly. watch(buildingId, ..., { immediate: true }) handles three cases identically: the initial mount, a component switching to a different building, and unmount (via onCleanup) — each transition releases the old bucket reference (if any) and acquires the new one, so the store’s reference counts stay correct without the component needing any lifecycle logic of its own beyond calling this composable.