Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

RAMEN 🍜 (Real-time Asynchronous Message Event Network) is the streaming backplane the Synheart platform uses to push events to connected clients in real time. Clients open a long-lived gRPC stream, subscribe to event types, and receive ordered events with at-least-once delivery and a replay window for catching up after disconnects. This page covers what hosts and apps need to know to consume RAMEN events. Service-internal details (queue layout, fan-out workers, Redis state shape) live in the platform reference.

​
What you can subscribe to

The most common subscriptions:
  • Vendor webhooks normalized to HSI — WHOOP, Garmin, Fitbit events arrive as HSI snapshots once normalized.
  • HSI snapshots ingested from your own SDK — useful for cross-device fan-out (e.g. desktop dashboard reading state pushed from a phone).
  • Lab session export confirmations — when running Lab Mode.

​
Endpoints

  • Gateway: gRPC on :8083 via the platform endpoint.
  • Subscribe: bidirectional gRPC stream. Clients send a subscription envelope with app_id, subject_id, and a list of event types and providers; RAMEN streams matching events back.
  • Replay: unary gRPC. Provide the last sequence you saw; RAMEN returns events with seq > last_seq from the wear-service replay store, then you resume the live stream.

​
Connection lifecycle

  1. Authenticate with a JWT or app API key.
  2. Subscribe with desired filters; you receive a connection_id and a starting sequence.
  3. Heartbeat every ~30 s to keep the connection registered. Missed heartbeats reap the connection after 5 minutes.
  4. On disconnect, call Replay with your last seq before reopening the subscription to avoid gaps.
RAMEN is gated by both:
  • Capability: cloud capability tier on the consent token (subscribing without the token returns 401).
  • Per-type consent: vendorSync for vendor-webhook subscriptions, cloudUpload for the rest.
See Consent System for the wire strings.

​
Backpressure and ordering

  • Events are delivered per app_id + subject_id in seq order.
  • Slow consumers get backpressured by the fan-out worker pool; the platform will drop the connection if the consumer falls more than 5 minutes behind, expecting Replay on reconnect.
  • At-least-once delivery — clients are expected to dedupe by seq (monotonic, gap-free per stream).

​
When to use RAMEN

  • You’re building a real-time dashboard or live coaching surface.
  • You’re replicating Synheart-Core HSI streams across multiple devices owned by the same subject.
  • You’re consuming WHOOP / Garmin webhook events server-side without running the wear-service yourself.
If you only need periodic snapshots, the standard /ingest/v1/hsi POST flow + a polling read-API is simpler.