Synheart Core Architecture - Synheart Documentation

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

// 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

// 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)

// 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:

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 for the canonical structure. Flux is what packs HSV into HSI for the wire. Core Functions:

Signal Ingestion: push_rr(), push_hr(), push_accel(), push_behavior() accept raw samples and feed the Synheart Runtime’s FeatureSet builder.
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.
Time Windows: 60s sliding window, 5s emit step (configurable).
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.
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:

{
  "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 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 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.

Manages permissions and data masking. Responsibilities:

Permission requests
Consent tracking
Data masking based on consent
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:

// 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 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:

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

// 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

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)

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

HSI State → Focus Module → Focus Estimate
HSI State → Emotion Module → Emotion State

4. Output

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:

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.

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

Encryption
- Local storage: AES-256
- Network: TLS 1.3
- Key storage: Platform keychain
Access Control
- Capability-based access
- App signature validation
- Tenant ID verification
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

HSV Specification - the canonical inference output (Hsv struct, six heads, 64D embedding)
Capability System - Access level details
Consent System - Permission model
Cloud Protocol - Upload protocol specification

​System Overview

​Module System

​Signal Collection Modules

​1. Wear Module

​2. Phone Module

​3. Behavior Module

​HSI Runtime (Synheart Runtime)

​Inference heads

​Cloud Connector

​Consent Module

​Capability System

​Capability Levels

​Capability Matrix

​Enforcement

​Data Flow

​1. Signal Collection

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

​3. Interpretation

​4. Output

​Thread Model

​Storage

​Local Storage

​Cloud Storage

​Performance

​Security

​Data Protection

​Threat Model

​Platform-Specific Notes

​iOS

​Android

​Flutter/Dart

​Related Documentation