> ## 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 🍜 overview

> Real-time event delivery backplane — how clients subscribe to vendor and platform events

**RAMEN 🍜** (**R**eal-time **A**synchronous **M**essage **E**vent **N**etwork) 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. Broker-side internals are not part of the public surface — only the subscribe / delivery contract is.

## 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](/lab/overview).

## 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 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.

## Consent and capabilities

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](/synheart-core/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 your own wearable webhook handler.

If you only need periodic snapshots, the standard `/ingest/v1/hsi` POST flow + a polling read-API is simpler.