Communication & Data Flow

CrowdVision uses three communication styles, chosen deliberately per relationship:

• Synchronous, user-driven — HTTP through the gateway, and the handful of service-to-service calls made on a user’s behalf. The caller’s identity travels with the request.
• Synchronous, control-plane — HTTP calls between backend-only services that have no end user attached (signup provisioning). Authenticated by a shared secret instead of a user identity, because there is no user identity to carry.
• Asynchronous (publish/subscribe) — over Redis, for the high-frequency telemetry and alert flows, where producers must not be coupled to, or blocked by, consumers.

This page maps all three, then walks five end-to-end flows.

Identity & Trust: How a Caller’s Identity Travels

There is no central session store and no per-request call back to an identity authority. Two distinct mechanisms carry trust, and which one applies depends on whether a human is behind the request:

Both patterns exist for the same reason: nobody re-implements JWT verification or invents a second signing scheme per pair of services. Every mesh-claims consumer and every HMAC consumer reuses one shared convention, respectively — see Identity & Tenancy Architecture and Service Mesh Architecture for the full verification mechanics.

A third category — no authentication at all — is used only where forwarding an identity would be meaningless or actively wrong: device-facing ingestion (a sensor has no user token to present) and a small number of internal bootstrap calls that write nothing sensitive (flagged individually in the table below).

Synchronous Communication

Browser ↔ Gateway

All external traffic enters through the single gateway (Caddy in compose, Istio Gateway API in k8s), which routes by URL prefix. See the routing table in the Overview — not repeated here.

Service-to-Service Calls

These calls are intentionally few. The design keeps the request path short and avoids synchronous chains on the hot path; anything high-frequency goes over the broker instead.

Device Ingestion

POST /ingest on sensor-service — no authentication (a physical sensor or simulator has no user token to present), and exempt from the gateway’s auth gate for the same reason. The endpoint responds 202 Accepted immediately and validates/persists/evaluates thresholds in the background (setImmediate), so a slow downstream step never makes an IoT device wait or retry.

Asynchronous Communication

Redis is the publish/subscribe backbone for everything high-frequency. Four channels and one stream carry the event flow:

Publishers never know who (if anyone) is listening, and the broker absorbs bursts, so a slow or restarting consumer cannot back-pressure a sensor.

Browser-Facing Real-Time Channels

Socket.IO (socket-service)

Web Push (notification-service)

The client fetches the server’s public VAPID key (GET /notification/public-key), calls the browser’s pushManager.subscribe(), and registers the resulting subscription (POST /notification/subscribe). When an alert fires, notification-service sends a push payload ({title, message, icon}) via the web-push package directly to the browser’s push service — this path does not go through Redis or socket-service, and works even if the user has no tab open. A service worker (frontend/public/service-worker.js) handles the push event to show an OS-level notification and notificationclick to focus/open the app.

End-to-End Flows

Path 1: Live Telemetry to the Browser

sequenceDiagram
    participant Sensor as Sensor source
    participant SS as sensor-service
    participant R as Redis
    participant CS as contracts-service
    participant WS as socket-service
    participant UI as Vue client

    Sensor->>SS: POST /ingest (no auth)
    SS-->>Sensor: 202 Accepted
    Note over SS: background: validate, persist, normalize
    SS->>R: PUBLISH telemetry:raw
    R-->>CS: telemetry:raw event
    Note over CS: read the event's own buildingId → route
    CS->>R: PUBLISH telemetry:filtered:{buildingId}
    R-->>WS: telemetry:filtered:{buildingId} event
    WS->>UI: emit "telemetry" to room building:{id}

contracts-service is the routing stage: it republishes each reading to its own building’s channel (an O(1) lookup on the event’s buildingId), so a reading reaches exactly one building’s feed and never leaks into another’s. It does not filter by metric type — every metric a building produces is forwarded, and the dashboard’s column preferences only decide what the table displays, client-side.

Path 2: Threshold Alert to the User

sequenceDiagram
    participant SS as sensor-service
    participant R as Redis
    participant NS as notification-service
    participant TW as twin-service
    participant WS as socket-service
    participant Push as Browser push service
    participant U as User

    Note over SS: background: reading crosses a configured bound
    SS->>R: PUBLISH alerts:temperature
    R-->>NS: alerts:temperature event
    Note over NS: throttle repeats (per-room cooldown)
    NS->>TW: GET /domain/{buildingName}
    TW-->>NS: domain name(s)
    Note over NS: select opted-in recipients
    NS->>R: PUBLISH notifications {domainName}
    NS->>Push: web-push send (VAPID)
    R-->>WS: notifications event
    WS->>U: emit "notification" to room domain:{name}
    Push-->>U: service worker "push" → OS notification

Unlike Path 1, this is a two-hop async chain, not one publish: sensor-service never calls notification-service directly — the threshold trigger and the resolved, recipient-scoped notification are two distinct Redis events, with notification-service sitting in between doing the one synchronous call it needs (resolving domains from twin-service) and fanning out over both delivery paths — in-app (broker + socket) and Web Push (direct, works with no tab open).

Path 3: Assistant Tool-Calling

sequenceDiagram
    participant U as Browser
    participant Chat as chat-service
    participant Agent as agent-service
    participant Twin as twin-service
    participant Sensor as sensor-service

    U->>Chat: POST /chat/... (x-gateway-claims via gateway)
    Chat->>Agent: POST /ask {question}, x-gateway-claims forwarded
    Note over Agent: LLM decides which tool(s) to call
    Agent->>Twin: GET /buildings/{domain}, x-gateway-claims forwarded
    Twin-->>Agent: building data
    Agent->>Sensor: GET /{metric}/latest, x-gateway-claims forwarded
    Sensor-->>Agent: reading
    Agent-->>Chat: answer
    Chat-->>U: chat response

Every tool call agent-service makes carries the original user’s x-gateway-claims header, forwarded across two hops (chat-service → agent-service → twin-service/sensor-service) — so twin-service and sensor-service apply the same Cedar authorization to an assistant-driven read as they would to a direct API call from that user. chat-service persists the conversation in its own MongoDB independently of this flow.

Path 4: Login & Identity Resolution

sequenceDiagram
    participant U as User
    participant CG as claims-gateway
    participant KC as Keycloak
    participant TS as tenancy-service

    U->>CG: POST /login (credentials or IdP redirect)
    CG->>KC: verify credentials / verify token
    KC-->>CG: verified identity + Organization claim
    CG->>TS: GET /internal/memberships (HMAC)
    alt no membership yet
        CG->>TS: POST /internal/provision (HMAC)
        TS-->>CG: membership created from the Organization claim
    end
    CG-->>U: signed internal token (StandardClaims)

This is the only point where tenancy-service is consulted for identity — once per login, never per request. Every subsequent request in a session is authorized locally, from the token/header, with zero further network hops for auth. See Identity & Tenancy Architecture for how the membership itself is derived, and Service Mesh Architecture for how the resulting token becomes the x-gateway-claims header at the mesh edge.

Path 5: Organization Signup & Provisioning

sequenceDiagram
    participant C as New customer
    participant RS as registry-service
    participant P as provisioner
    participant TS as tenancy-service

    C->>RS: POST /organizations (no auth — no credentials exist yet)
    RS-->>C: 201, status=provisioning
    loop every 15s
        P->>RS: GET /internal/organizations/pending (HMAC)
    end
    P->>TS: POST /internal/domains (HMAC, idempotent)
    TS-->>P: 201 or 409 (both = success)
    P->>RS: POST /internal/organizations/{id}/status (HMAC)

This is the control-plane path: no end user is authenticated mid-flow, so every internal hop uses the HMAC X-Signature scheme rather than a forwarded identity header. See Overview for what registry-service/provisioner/tenancy-service each own.

Why Three Styles