Skip to content
Circadify Circadify Circadify

Architecture Overview

Circadify is a hybrid client-server platform for contactless vital signs measurement using remote photoplethysmography (rPPG). The client performs real-time face detection and on-device preprocessing; our inference engine runs the rPPG model on the preprocessed RGB tensor and returns vital signs in the API response. No health data is stored on Circadify’s side.

System Architecture

Section titled “System Architecture”
Circadify architecture diagram showing data flow from your app through the SDK or REST API to Circadify Cloud

The platform has three primary layers:

Client Layer

The @circadify/web-sdk runs in the browser. It captures video via the camera, detects facial landmarks, extracts regions of interest (ROIs), and encodes them into a structured tensor for upload. No raw video leaves the device.

API Layer

Serverless API endpoints handle authentication, rate limiting, session management, and secure upload URL generation. Session state is short-lived and encrypted. Developer accounts, API keys, and usage data are stored in a managed database.

Inference Engine

The inference engine processes the uploaded RGB tensor through our rPPG signal processing model, extracts physiological signals, and returns calibrated vital signs in the API response. The tensor is discarded after inference; no health data is stored.

Two Integration Paths

Section titled “Two Integration Paths”

You can integrate Circadify in two ways: using the SDK (recommended) or calling the REST API directly.

The SDK handles the entire pipeline — camera access, face detection, preprocessing, upload, and result polling — in a single async call:

import { CircadifySDK } from '@circadify/web-sdk';


const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  onProgress: (p) => console.log(`${p.phase}: ${p.percent}%`),
});


const result = await sdk.measureVitals({
  videoElement: document.getElementById('preview') as HTMLVideoElement,
});


console.log('Heart Rate:', result.heartRate, 'BPM');
console.log('SpO2:', result.spo2, '%');

The SDK is ~38 KB (ESM). WASM dependencies (~12 MB total) are lazy-loaded and cached by the browser.

Design Principles

Section titled “Design Principles”
  • Privacy-first — The SDK transmits only the preprocessed RGB tensor extracted from skin regions, never raw video or frames. No biometric imagery touches our servers.
  • No health-data storage — Vital sign results are returned in the API response and not stored on our side. Uploaded RGB tensors are processed and discarded. The only artifact retained from a scan is a usage record (one scan credit consumed) for billing and quota.
  • Secure by default — API keys are hashed before storage. All traffic is TLS-encrypted. Failed auth attempts trigger automatic lockout.
  • Graceful degradation — When inference fails, the system returns fallback values with confidence: 0.0 so the client always gets a response. Always check the confidence score.

Authentication and Rate Limiting

Section titled “Authentication and Rate Limiting”

All SDK and API requests are authenticated with API keys in the format ck_live_{hex}. Keys are passed via the X-API-Key header. Each request is validated against:

  1. Key validity — Is the key active, not revoked, not expired?
  2. Developer status — Is the developer account active and email verified?
  3. Rate limit — Has the developer exceeded their hourly request limit?

Rate limit headers are returned on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1712000000

All measurements return all six vitals: heart rate, respiratory rate, HRV, SpO2, systolic BP, and diastolic BP.

Next Steps

Section titled “Next Steps”