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

# How it fits together

> A single mental model of Synheart — sensors, SDKs, runtime, cloud, and LLM — and which pieces are mandatory vs optional.

If you're trying to figure out which pieces of Synheart your app actually needs, read this page first. Everything else in the docs assumes the shape laid out below.

## The mental model

Synheart is a stack with four layers. Most apps use one or two of them; very few use all four.

```mermaid theme={null}
flowchart TB
    subgraph S["1 · Sensors"]
        S1[Wearable device<br/>Apple Watch, WHOOP, Garmin, Fitbit, BLE HRM]
        S2[Phone sensors<br/>motion, screen, foreground app]
        S3[User interactions<br/>tap, scroll, typing rhythm]
    end

    subgraph SDK["2 · SDKs (your app)"]
        SDK1[Synheart Wear]
        SDK2[Synheart Behavior]
        SDK3[Synheart Session]
        SDK4[Synheart Core<br/>fuses Wear + Behavior + Phone]
    end

    subgraph RT["3 · Synheart Runtime (on-device, native)"]
        RT1[Feature pipeline]
        RT2[HSV inference<br/>6 cognitive/physio heads + MotionState]
        RT3[Flux → HSI 1.3 JSON]
    end

    subgraph OUT["4 · Outputs"]
        APP[Your app<br/>HSI stream / typed state]
        SYNI[Syni<br/>on-device LLM<br/>persona-conditioned]
        CLOUD[Synheart Cloud<br/>ingest / RAMEN events]
    end

    S1 --> SDK1
    S2 --> SDK4
    S3 --> SDK2
    S1 -.standalone.-> APP
    S3 -.standalone.-> APP
    SDK1 --> SDK4
    SDK2 --> SDK4
    SDK3 --> APP
    SDK4 --> RT
    RT --> APP
    APP -.optional.-> SYNI
    APP -.consent-gated.-> CLOUD

    classDef optional stroke-dasharray: 5 5
```

The dotted arrows are optional paths. Solid arrows are the default flow for an app using Synheart Core.

## What each layer does

**1. Sensors** are the data sources. You bring these — a paired wearable, the phone the app is running on, the user typing or scrolling inside your app. Synheart does not capture any of this without an SDK in your app code.

**2. SDKs** are the per-language entry points that capture data. They live in your app process. Four of them ship today:

* [**Synheart Wear**](/synheart-wear/overview) — normalises HR, HRV, sleep, motion from any supported wearable into one API.
* [**Synheart Behavior**](/synheart-behavior/overview) — content-free interaction events (taps, scrolls, typing cadence, app context).
* [**Synheart Session**](/synheart-session/overview) — watch-driven session capture with pluggable biosignal and behavior providers. Use this when the watch is computing session frames locally and streaming them to the phone.
* [**Synheart Core**](/synheart-core/overview) — the fusion SDK. Consumes Wear + Behavior + phone signals and produces a single human-state stream.

Each standalone SDK can be used **on its own**. You only need Core if you want fused human-state output.

**3. The Synheart Runtime** is a native binary (the artifact you install with `synheart install runtime`) that does the heavy lifting: features → inference → packing into HSI. Only Synheart Core links to it. The standalone SDKs don't. See [Architecture](/synheart-core/architecture) for the full pipeline.

**4. Outputs** are how data leaves the runtime:

* **Your app** is always an output. The SDK exposes HSI envelopes and typed projections via reactive streams (e.g. `Synheart.onHSIUpdate` / `onStateUpdate`).
* [**Syni**](/syni/overview) is the optional on-device LLM. It consumes HSI as a conditioning input on inference requests, but works without it.
* **The cloud** is optional and consent-gated. With `cloudUpload` consent granted, HSI envelopes are uploaded to `api.synheart.ai` (or your enterprise gateway). [RAMEN](/ramen/overview) is the other direction: cloud → app, for real-time vendor and platform events.

## Mandatory vs optional

The smallest useful Synheart app is one SDK and your code. Everything else is opt-in.

| Piece                                 | When you need it                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| One of Wear / Behavior / Session SDKs | Every app — pick the one that matches your data source.                                                |
| Synheart Core SDK                     | When you want fused, multimodal human-state output (HSI, the six axes). Skip if one channel is enough. |
| Synheart Runtime (native)             | Only when using Synheart Core. Installed via `synheart install runtime`.                               |
| Platform account + CLI                | Only when using Core (the runtime is gated). Standalone SDKs don't require either.                     |
| Cloud upload                          | Only if you want HSI off-device. Pure local-only Core apps don't need it.                              |
| Syni                                  | Only if your app does LLM inference and wants persona contracts + HSI-conditioned prompts.             |
| RAMEN                                 | Only if your app consumes real-time vendor / platform events (cross-device fan-out, vendor webhooks).  |

## How the concepts relate

A few terms recur across the docs. Holding these in mind makes the rest of the site easier to skim:

* **HSI (Human State Interface)** — the JSON wire contract. Version `1.3` today. See [HSI overview](/hsi/overview).
* **HSV (Human State Vector)** — the typed in-runtime representation. The inference engine produces `HSV[]`.
* **Flux** — the runtime step that packs `HSV[]` into an HSI envelope on the wire.
* **Capability tier** — what your *app* is entitled to (`core`, `extended`, `research`).
* **Consent type** — what the *user* allows (`biosignals`, `behavior`, `phoneContext`, `cloudUpload`, `vendorSync`, `research`).
* **Data access requires both** the capability tier and the user consent. See [Capability system](/synheart-core/capability-system) and [Consent system](/synheart-core/consent-system).

A more compact list lives in the [Glossary](/guides/glossary).

## Two common paths

**Path A — "I just want wearable readings."** Add `synheart_wear` (or the Kotlin / Swift equivalent). No CLI, no platform account, no runtime. Stream HR / HRV / sleep into your own code. Stop here.

**Path B — "I want a focus / capacity / recovery score."** Add Synheart Core. Install the runtime (`synheart install runtime`), authenticate the CLI, ship the SDK in your app. The runtime fuses whatever modules you've enabled (Wear + Behavior + Phone) into HSI. Subscribe to `onHSIUpdate` or `onStateUpdate`.

If you're not sure which path you're on, the [Quickstart](/quickstart) has a one-sentence filter at the top and side-by-side code for both.

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Pick a track and run code in 10 minutes.
  </Card>

  <Card title="Synheart Core architecture" icon="diagram-project" href="/synheart-core/architecture">
    The runtime's internal pipeline (features → HSV → HSI) in depth.
  </Card>

  <Card title="Glossary" icon="book" href="/guides/glossary">
    One-line definitions of every product and concept.
  </Card>

  <Card title="HSI specification" icon="file-code" href="/hsi/overview">
    The wire format your app receives.
  </Card>
</CardGroup>