Data Flow

This page documents how data moves between services: which protocols are used, how each connection is authenticated, and what data is exchanged.

Inter-service communication matrix

From	To	Protocol	Auth	Purpose
Cloud SPA	Cloud Backend	REST (`/api/v1/*`)	JWT Bearer	All CRUD operations
Cloud SPA	Cloud Backend	WebSocket (`/api/ws/*`)	JWT query param `?token=`	Real-time security alerts, VPN sessions
Cloud Backend	Management Backend	HTTP (`/internal/v1/*`)	`X-Internal-Token` (shared secret)	License state fetch
Management Backend	Cloud Backend	HTTP (`/internal/license/refresh`)	HMAC signature (`CLOUD_WEBHOOK_HMAC_SECRET`)	License activation push
Edge Appliance	Cloud Backend	HTTP (`/api/v1/devices/*`, `/api/v1/commands`)	Provisioning key (per tenant)	Device registration, command polling
Edge Appliance	Ingestor	HTTP (`POST /v1/ingest`)	`X-Device-Key` header	Telemetry batch upload
Cloud Backend	Microsoft Entra ID	OIDC (HTTP)	OAuth client credentials	Platform SSO and per-tenant OIDC
Cloud Backend	Resend	HTTP	API key	Transactional email
Cloud Backend	NVD / CISA / MITRE	HTTP	API key (NVD) / public	CVE feed synchronization
Management SPA	Management Backend	REST (`/api/v1/*`)	JWT Bearer	Tenant management

Sequence: browser REST request

sequenceDiagram
    participant Browser
    participant CloudSPA as Cloud SPA
    participant API as Cloud Backend API
    participant SQL as Azure SQL

    Browser->>CloudSPA: Navigate to /incidents
    CloudSPA->>API: GET /api/v1/incidents (Bearer token)
    API->>API: Validate JWT, extract tenant_id + user_id
    API->>API: Check RBAC permission (incidents:read)
    API->>SQL: SELECT … WHERE tenant_id = SESSION_CONTEXT(...)
    SQL-->>API: Rows (RLS enforced)
    API-->>CloudSPA: 200 JSON
    CloudSPA-->>Browser: Render incidents list

Sequence: WebSocket real-time alert

sequenceDiagram
    participant Browser
    participant API as Cloud Backend API
    participant SQL as Azure SQL

    Browser->>API: WS upgrade /api/ws/security?token=<jwt>
    API->>API: Validate JWT, register connection in hub
    Note over API: hub maps tenant_id → []connections

    loop External alert arrives
        API->>SQL: INSERT security_alert (via webhook or ingestor)
        API->>API: Broadcast to all hub connections for tenant_id
        API-->>Browser: WS message { type: "alert", ... }
    end

    Browser->>API: WS close
    API->>API: Remove connection from hub

Sequence: Management → Cloud license activation

sequenceDiagram
    participant MgmtFE as Management SPA
    participant MgmtBE as Management Backend
    participant CloudBE as Cloud Backend

    MgmtFE->>MgmtBE: POST /api/v1/tenants/:id/license
    MgmtBE->>MgmtBE: Update tenant_licenses table (Mgmt DB)
    MgmtBE->>CloudBE: POST /internal/license/refresh (HMAC signed)
    CloudBE->>CloudBE: Verify HMAC signature
    CloudBE->>CloudBE: Update tenant_licenses + tenant_features (Cloud DB)
    CloudBE-->>MgmtBE: 200 OK
    MgmtBE-->>MgmtFE: License activated
    Note over CloudBE: Tenant active. Without activation, login is blocked.

Sequence: Edge device telemetry ingest

sequenceDiagram
    participant Edge as Edge Appliance
    participant CloudBE as Cloud Backend
    participant Ingestor as Ingestor Service
    participant SQL as Azure SQL

    Edge->>CloudBE: POST /api/v1/devices/register (X-Provisioning-Key)
    CloudBE->>SQL: INSERT device, return device_key
    CloudBE-->>Edge: { device_key }

    loop Telemetry batch (periodic)
        Edge->>Ingestor: POST /v1/ingest (X-Device-Key)
        Note right of Edge: body: [{ kind: "telemetry", ... }, ...]
        Ingestor->>SQL: INSERT ingest_events (partitioned by tenant)
        Ingestor-->>Edge: 204 No Content
    end

    loop Command polling
        Edge->>CloudBE: GET /api/v1/commands (X-Device-Key)
        CloudBE-->>Edge: [{ command: "update_snap", ... }]
    end

Environment variable dependencies

The connections above depend on these environment variables being set correctly on each service:

Variable	Set on	Purpose
`CLOUD_INTERNAL_API_TOKEN`	Cloud Backend + Management Backend	Shared M2M Bearer secret
`CLOUD_WEBHOOK_HMAC_SECRET`	Cloud Backend + Management Backend	HMAC signing key for license webhook
`MANAGEMENT_API_URL`	Cloud Backend	URL of Management Backend (Cloud → Mgmt calls)
`CLOUD_API_URL`	Management Backend	URL of Cloud Backend (Mgmt → Cloud webhook)
`VITE_API_URL`	Cloud Frontend	Cloud Backend API origin
`VITE_WS_URL`	Cloud Frontend	WebSocket base URL

See Cloud Backend local dev and Management local dev for full variable lists.