Telemetry Service Integration

Telemetry is a sibling Go service in the same monorepo, deployed as a separate AWS App Runner service within the same VPC. The Core API communicates with it via the TELEMETRY_INTERNAL_URL environment variable (pointing to the Telemetry App Runner service URL). The frontend client SDK talks to Telemetry directly for analytics and media tracking.

Overview

Core API's role: Write audit events to local audit_log (synchronous), then forward to Telemetry (async). See ../../reference/audit.md for the audit middleware implementation.

Telemetry's role: Receives audit events from the Core API for enrichment (geo, actor hashing, security threat detection). Receives analytics and media events directly from the frontend SDK. Stores enriched data in its own PostgreSQL (7-year audit retention) and ClickHouse (2-year analytics/media retention).

API Endpoints

Telemetry API endpoints consumed by the Core API and frontend:

Endpoint	Consumer	Purpose
POST /v1/audit/ingest	Core API (internal)	Receive forwarded audit events for enrichment
POST /v1/analytics/track	Frontend SDK	Page views, clicks, feature usage
POST /v1/media/events	Frontend SDK	Video session lifecycle (session_start, heartbeat, session_end)
POST /v1/pose/frames	Frontend SDK	Batched MediaPipe pose tracking data
POST /v1/errors/report	Frontend SDK	App/video/network errors with device context
GET /v1/media/bandwidth/stats	Frontend SDK	Bandwidth monitoring for rehab sessions
GET /health	App Runner	Health check

Databases

Telemetry databases (managed independently):

Database	Purpose	Retention
PostgreSQL (5 schemas)	Enriched audit logs, security events, staff activity, privacy exclusions	7 years (audit), 90 days (operational)
ClickHouse	Analytics events, media sessions, bandwidth samples, staff metrics	2 years (TTL)
Redis (shared with the Core API)	Session cache, rate limiting, queues	N/A

Shared Types

The pkg/auditevt/ package defines the Event struct used by both services. The Core API produces events, Telemetry consumes them. One definition, no drift.

// pkg/auditevt/event.go

type Event struct {
    Action         string    `json:"action"`          // CREATE, UPDATE, DELETE
    EntityType     string    `json:"entity_type"`     // appointment, patient, form, etc.
    EntityID       int64     `json:"entity_id,omitempty"`
    UserID         int64     `json:"user_id"`
    OrganizationID int64     `json:"organization_id"`
    IPAddress      string    `json:"ip_address"`
    UserAgent      string    `json:"user_agent"`
    RequestPath    string    `json:"request_path"`
    StatusCode     int       `json:"status_code"`
    Timestamp      time.Time `json:"timestamp"`
    Changes        any       `json:"changes,omitempty"`

    // Context tags (set by the Core API for special operations)
    ActionContext   string `json:"action_context,omitempty"`   // "normal", "break_glass", "impersonation"
    BreakGlassID   *int64 `json:"break_glass_id,omitempty"`
    ImpersonationID *int64 `json:"impersonation_id,omitempty"`
}

What Telemetry Does NOT Do for the Core API

Telemetry does not serve the Core API's audit log read queries. Admins read audit logs via the Core API's API (which queries the Core API's local audit_log table, RLS-scoped). Telemetry's enriched data is for compliance dashboards and analytics — a separate UI concern.

Cross-Tenant Isolation

Telemetry runs as a separate App Runner service within the same AWS VPC as the Core API. It is not exposed to the public internet — only reachable via the TELEMETRY_INTERNAL_URL (the Telemetry App Runner service URL).

• All audit events forwarded from the Core API include organization_id
• Telemetry stores events in its own PostgreSQL with org-scoped schemas
• Read access to audit logs is through the Core API's API only (RLS-filtered). Telemetry does not expose audit read endpoints to clients
• Frontend analytics/media events also include organization_id from the authenticated session
• Telemetry's compliance middleware hashes patient actor IDs (SHA-256 + salt) — analytics data in ClickHouse contains no PII

Network Isolation

• Telemetry is only reachable within the AWS VPC (no public endpoint)
• the Core API → Telemetry communication is over HTTPS within AWS
• Frontend → Telemetry communication is over public HTTPS (for analytics/media tracking only)
• No audit read endpoints are exposed publicly

Security Checklist

• [ ] Telemetry service is only reachable within the AWS VPC for audit forwarding
• [ ] the Core API audit events include organization_id and are only readable via the Core API's RLS-filtered API
• [ ] Telemetry ClickHouse analytics data contains hashed actor IDs, not PII
• [ ] Frontend analytics/media events include organization_id from authenticated session