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

# Synheart Core Architecture

> Deep dive into the Core SDK module system and HSI Runtime

## System Overview

Synheart Core SDK is a modular, on-device human state intelligence system that collects multi-modal signals and fuses them into a unified state representation via the Synheart runtime (native).

```mermaid theme={null}
flowchart TB
    subgraph SDK["Synheart Core SDK (your app process)"]
        W["Wear module<br/>HR / HRV / sleep / motion"]
        P["Phone module<br/>motion / screen / app context"]
        B["Behavior module<br/>tap / scroll / typing / app switch"]
    end

    subgraph RT["Synheart Runtime (native, on-device)"]
        FP[Feature pipeline<br/>60s window, 5s step]
        IE[Inference engine<br/>6 heads + MotionState]
        FX[Flux<br/>HSV[] → HSI 1.3 JSON]
        FP --> IE --> FX
    end

    APP[Your app<br/>onHSIUpdate / onStateUpdate]
    CC[Cloud connector<br/>consent + capability gated]
    CLOUD[(Synheart Cloud<br/>api.synheart.ai)]

    W --> FP
    P --> FP
    B --> FP
    FX --> APP
    FX --> CC
    CC -.consent-gated.-> CLOUD
```

The same pipeline runs whether you've enabled one module or all three. Modules feed raw samples across the native bridge into the runtime's feature pipeline; the SDK side only sees the HSI envelope (and a typed projection of it) coming back.

## Module System

### Signal Collection Modules

#### 1. Wear Module

Collects biosignals from wearable devices.

**Data Sources:**

* Heart rate (HR)
* Heart rate variability (HRV)
* Sleep stages
* Motion/activity
* Skin temperature (if available)

**Output:**

* Derived signals only (no raw biosignals)
* 30s, 5m, 1h, 24h aggregations
* Quality metrics and confidence scores

**Platform Support:**

* iOS: HealthKit
* Android: Health Connect
* Multi-device: Apple Watch, Fitbit, WHOOP, Garmin, Samsung

```dart theme={null}
// Example: Wear module output
{
  "hr_mean": 72,
  "hr_std": 8,
  "hrv_rmssd": 45,
  "hrv_sdnn": 62,
  "quality_score": 0.95,
  "window": "30s"
}
```

#### 2. Phone Module

Collects device-level signals.

**Data Sources:**

* Motion (accelerometer, gyroscope)
* Screen state (on/off, brightness)
* App context (coarse categories)
* Location context (stay/move, no coordinates)

**Privacy:**

* No fine-grained location
* No app names (only categories: social, productivity, etc.)
* No notification content

```dart theme={null}
// Example: Phone module output
{
  "motion_state": "stationary",
  "screen_on": true,
  "screen_brightness": 0.8,
  "app_category": "productivity",
  "context": "work"
}
```

#### 3. Behavior Module

Captures interaction patterns.

**Data Sources:**

* Tap frequency and pressure
* Scroll speed and direction
* Typing cadence
* App switching frequency
* Screen unlock patterns

**Privacy:**

* No content (what you type/read)
* Only patterns (how you interact)

```dart theme={null}
// Example: Behavior module output
{
  "tap_frequency": 12.5,
  "scroll_velocity_mean": 0.4,
  "typing_cadence": 3.2,
  "app_switches_per_min": 2.1,
  "interaction_stability": 0.82
}
```

### HSI Runtime (Synheart Runtime)

The Synheart Runtime is the native binary you install with `synheart install runtime` and the only thing the SDKs link against. It owns:

* Storage, crypto, sync, consent, capability gating, cloud connector, lab mode, sensor adapters, native binding surface.
* The sample-ingest seam (`push_rr`, `push_hr`, `push_accel`, `push_behavior`).

The full pipeline:

```text theme={null}
feature pipeline ──►  FeatureSet                 (60s window, 5s step)
inference engine ──►  HSV[] + 64D embedding      (six cognitive/physio heads + MotionState)
flux             ──►  HSI 1.3 JSON               (canonical wire format)
```

The SDK pushes raw signals across the native bridge and receives HSI JSON on `tick()`. HSV is the typed in-runtime intermediate — see [HSV Specification](/synheart-core/hsv-specification) for the canonical structure. Flux is what packs HSV into HSI for the wire.

**Core Functions:**

1. **Signal Ingestion**: `push_rr()`, `push_hr()`, `push_accel()`, `push_behavior()` accept raw samples and feed the Synheart Runtime's FeatureSet builder.
2. **HSV Inference**: the inference engine runs six canonical heads (Emotion, Focus, Capacity, Sleep, Recovery, Strain) plus MotionState. Each emits an `Hsv` with quality-adjusted, tier-capped confidence based on physiological signal fidelity.
3. **Time Windows**: 60s sliding window, 5s emit step (configurable).
4. **64D Embedding**: the Synheart Runtime computes a deterministic, L2-normalized, non-invertible Johnson-Lindenstrauss projection over the HSV bundle (`synheart-jl-64`, 64 dims, `float32`). Privacy-preserving: the original HSVs cannot be reconstructed from the embedding.
5. **HSI Packing**: `flux` builds the HSI 1.3 envelope from `InferenceOutput`, propagating axis readings, source provenance, tier bundles, and the embedding (when capability level + HSI version permit).

**Output:**

```dart theme={null}
{
  "affect": {
    "arousal_index": 0.72,      // 0.0-1.0
    "valence_index": 0.15,      // -1.0 to 1.0
    "intensity": 0.68           // 0.0-1.0
  },
  "engagement": {
    "engagement_stability": 0.81,
    "cognitive_load": 0.65,
    "attention_level": 0.73
  },
  // Optional embedding fields (presence and dimension depend on capability level + HSI version)
  "window": {
    "duration": "30s",
    "start": "2026-01-15T10:30:00Z",
    "end": "2026-01-15T10:30:30Z"
  },
  "timestamp": "2026-01-15T10:30:30Z"
}
```

**Update Frequency:**

* 30s window: Updated every 30 seconds
* 5m window: Updated every minute
* 1h window: Updated every 5 minutes
* 24h window: Updated every 15 minutes

**Performance:**
The runtime is designed for low overhead — sub-100ms HSI emission and a single-digit-percent CPU budget on a typical mid-range device. These are design targets, not measurements. Profile your app and read `Synheart.runtimeDiagnostics()` for live counters.

### Inference heads

The engine emits typed HSV (Human State Vector) heads — there are no separate "Focus Module" or "Emotion Module" SDK products. Each head is one entry inside the HSI envelope's axis readings. The canonical head set lives in `synheart-engine`. See [HSV Specification](/synheart-core/hsv-specification) for the head taxonomy and value ranges.

The SDK exposes the engine output two ways:

* `Synheart.onHSIUpdate` — raw HSI 1.3 JSON envelope (authoritative).
* `Synheart.onStateUpdate` — typed `HSIState` projection of the same JSON. See the per-platform pages for the typed shape.

### Cloud Connector

Securely uploads HSI snapshots to Synheart Platform with user consent. The connector lives inside the runtime — the SDK feeds the runtime, which owns the queue and signing.

**Features:**

* Consent-gated uploads (via `cloudUpload` consent + per-request JWT).
* Persistent SQLite queue (offline-resilient).
* Automatic retry with backoff.
* Hardware-backed request signing (`X-Synheart-Proof`).
* Tenant-isolated routing by `org_id`.

**Wire payload:** the engine's HSI 1.3 JSON envelope, with the runtime adding `X-Consent-Token` and `X-Synheart-Proof` headers. See [Cloud Protocol](/synheart-core/cloud-protocol) for the full spec.

**Privacy:**

* No raw signals (only HSI snapshots).
* No personally identifiable information (`subject_id` is hashed before upload).
* User can revoke at any time; the connector pauses on the next flush.

### Consent Module

Manages permissions and data masking.

**Responsibilities:**

1. Permission requests
2. Consent tracking
3. Data masking based on consent
4. Runtime enforcement

**Consent Levels:**

| Module   | Permission               | Data Access               |
| -------- | ------------------------ | ------------------------- |
| Wear     | Health data              | Derived biosignals        |
| Phone    | Motion & sensors         | Coarse context only       |
| Behavior | Accessibility (optional) | Interaction patterns only |
| Cloud    | Network upload           | HSI snapshots only        |

**Example:**

```dart theme={null}
// Request consent — opens the cloud consent flow if a service is configured.
final token = await Synheart.requestConsent();

// Coarse status (granted | pending | expired | denied)
final status = await Synheart.consentStatus();

// Fine-grained per-type check
final canUpload = await Synheart.hasConsent('cloudUpload');

// Revoke a specific consent type or everything
await Synheart.revokeConsentType('cloudUpload');
await Synheart.revokeConsent();
```

See [Consent System](/synheart-core/consent-system) for the seven consent types, granular channels, and JWT flow.

## Capability System

Different apps get different levels of access based on app signature and tenant ID.

### Capability Levels

| Level        | Access                            | Who Gets It                                |
| ------------ | --------------------------------- | ------------------------------------------ |
| **None**     | No access                         | Default before a token loads               |
| **Core**     | Basic HSI fields, derived signals | Third-party apps                           |
| **Extended** | Full HSI fields, higher frequency | Enterprise customers and approved partners |
| **Research** | Raw streams, full fusion vectors  | Authorized research apps                   |

### Capability Matrix

| Module          | Core                       | Extended                              | Research                                  |
| --------------- | -------------------------- | ------------------------------------- | ----------------------------------------- |
| **Wear**        | Derived biosignals         | Higher-frequency windows              | Raw HR/HRV streams                        |
| **Phone**       | Motion, screen state       | Advanced app context                  | Full context                              |
| **Behavior**    | Basic metrics (aggregated) | Extended metrics                      | Event-level timing streams                |
| **HSI Runtime** | Basic state                | Full embedding fields in HSI envelope | Full fusion vectors + intermediate states |
| **Cloud**       | Ingest endpoint (HSI 1.3)  | Extended endpoint payloads            | Research endpoints                        |

### Enforcement

Capability checks happen at:

1. **SDK Initialization**: Validates app signature and tenant ID
2. **Module Enable**: Checks capability for requested module
3. **Data Access**: Masks/filters data based on capability
4. **Cloud Upload**: Routes to appropriate endpoint

```dart theme={null}
// Core capability (default)
Synheart.initialize(
  userId: userId,
  config: SynheartConfig(
    capabilityToken: coreToken
  )
);

// Extended capability (Synheart apps only)
Synheart.initialize(
  userId: userId,
  config: SynheartConfig(
    capabilityToken: extendedToken
  )
);
```

## Data Flow

### 1. Signal Collection

```text theme={null}
Wearable Device → Wear Module → Derived Signals
Phone Sensors → Phone Module → Coarse Context
User Interactions → Behavior Module → Patterns
```

### 2. HSV inference and HSI packing (Synheart Runtime)

```text theme={null}
Derived Signals + Coarse Context + Patterns
        │
        ▼
feature pipeline → FeatureSet (60s window, 5s step, signal tiers)
        │
        ▼
inference engine → HSV[] (6 heads + MotionState) + 64D embedding
        │
        ▼
flux → HSI 1.3 JSON envelope
```

### 3. Interpretation

```text theme={null}
HSI State → Focus Module → Focus Estimate
HSI State → Emotion Module → Emotion State
```

### 4. Output

```text theme={null}
HSI State → App Callbacks
Focus Estimate → App Callbacks
Emotion State → App Callbacks
HSI Snapshots → Cloud Connector (signed + consent-gated) → Synheart Platform
```

## Thread Model

The SDK uses a multi-threaded architecture for performance:

```text theme={null}
Main Thread
│
├─ UI Updates (callbacks)
│
Worker Threads
│
├─ Signal Collection Thread
│  └─ Wear, Phone, Behavior modules
│
├─ HSI Processing Thread
│  └─ Fusion, state calculation
│
├─ Interpretation Thread
│  └─ Focus, Emotion modules
│
└─ Cloud Upload Thread
   └─ Batching, encryption, upload
```

**Thread Safety:**

* All callbacks delivered on main thread
* Internal state protected by locks
* Async operations use platform-native concurrency (Coroutines, Combine, async/await)

## Storage

### Local Storage

The runtime owns local persistence (SQLite via `synheart-storage`):

* **Sessions and HSI windows**: bounded by retention (default platform-specific).
* **Vendor events**: backlog from `synheart-wear` adapters.
* **Consent snapshot + token**: per `subject_id`.
* **Upload queue**: persistent SQLite at `<data_dir>/ingest_upload_queue_<subject_id>.sqlite`.
* **SRM snapshot**: longitudinal state restored from `srm_<subject_id>.json` and platform secure storage.

Encryption-at-rest is on by default. Hosts on mobile typically wire native secure storage (Keychain / EncryptedSharedPreferences) into the runtime via `synheart_core_set_storage_callbacks`.

### Cloud Storage

* Requires explicit `cloudUpload` consent + valid JWT.
* Only HSI snapshots leave the device (lab session JSON when explicitly enabled).
* Transit: TLS (modern cipher suites only, no fallback to legacy versions).
* Hardware-backed `X-Synheart-Proof` per request — see [Synheart Auth — Signing](/synheart-auth/signing).

## Performance

The runtime is designed for low-overhead background operation. The exact CPU / memory / battery footprint depends on:

* Sample rate (BLE HRM at 1 Hz is much cheaper than 50 Hz raw motion).
* Active modules (motion-state inference is the heaviest single load when enabled).
* Cloud upload cadence (offline operation costs almost nothing).

For live counters in your build, read `Synheart.runtimeDiagnostics()`. Profile your app on the device classes you ship to — overall footprint will vary with the choices above.

## Security

### Data Protection

1. **Encryption**
   * Local storage: AES-256
   * Network: TLS 1.3
   * Key storage: Platform keychain

2. **Access Control**
   * Capability-based access
   * App signature validation
   * Tenant ID verification

3. **Privacy**
   * No raw content
   * No personal identifiers
   * Consent-gated access

### Threat Model

**Protected Against:**

* Unauthorized data access
* Man-in-the-middle attacks
* Local storage compromise
* Malicious apps accessing data

**Not Protected Against:**

* Device compromise (jailbreak/root)
* Physical device access
* Platform-level vulnerabilities

## Platform-Specific Notes

### iOS

* Uses HealthKit for biosignals
* CoreMotion for motion sensors
* Combine for reactive streams
* Background delivery supported

### Android

* Uses Health Connect for biosignals
* SensorManager for motion sensors
* Kotlin Coroutines and Flow
* WorkManager for background tasks

### Flutter/Dart

* Platform channels for native access
* Streams for reactive updates
* Async/await for operations
* Cross-platform consistency

## Related Documentation

* [HSV Specification](/synheart-core/hsv-specification) - the canonical inference output (`Hsv` struct, six heads, 64D embedding)
* [Capability System](/synheart-core/capability-system) - Access level details
* [Consent System](/synheart-core/consent-system) - Permission model
* [Cloud Protocol](/synheart-core/cloud-protocol) - Upload protocol specification