Synheart Core Architecture

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.

​

System Overview

┌────────────────────────────────────────────────────────┐
│                 Synheart Core SDK                      │
├────────────────────────────────────────────────────────┤
│                                                        │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐     │
│  │   Wear   │  │  Phone   │  │    Behavior    │     │
│  │  Module  │  │  Module  │  │     Module     │     │
│  └─────┬────┘  └─────┬────┘  └────────┬───────┘     │
│        │             │                 │              │
│        └─────────────┼─────────────────┘              │
│                      ▼                                │
│              ┌───────────────┐                        │
│              │  HSI Runtime  │                        │
│              │  (On-device)  │                        │
│              └───────┬───────┘                        │
│                      │                                │
│                      │                                │
│              ┌───────▼────────┐                       │
│              │ Cloud Connector│                       │
│              │ (consent-gated)│                       │
│              └────────────────┘                       │
│                                                        │
└────────────────────────────────────────────────────────┘

​

Module System

​

Signal Collection Modules

​

1. Wear Module

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

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

• 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

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

• 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

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

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

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

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)

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

{
  "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": "2025-01-15T10:30:00Z",
    "end": "2025-01-15T10:30:30Z"
  },
  "timestamp": "2025-01-15T10:30:30Z"
}

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

​

Inference heads

• 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

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

• 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

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

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

​

Capability System

​

Capability Levels

​

Capability Matrix

​

Enforcement

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

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

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

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

​

Storage

​

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

​

Cloud Storage

• Requires explicit cloudUpload consent + valid JWT.
• Only HSI snapshots leave the device (lab session JSON when explicitly enabled).
• Transit: TLS via rustls.
• Hardware-backed X-Synheart-Proof per request — see Synheart Auth — Signing.

​

Performance

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

​

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

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

• 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 - the canonical inference output (Hsv struct, six heads, 64D embedding)
• Capability System - Access level details
• Consent System - Permission model
• Cloud Protocol - Upload protocol specification