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 preprocessing, while the backend runs GPU-accelerated inference to extract vital signs from the preprocessed data.

System Architecture

The platform has three primary layers:

Client Layer

The @circadify/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

GPU-accelerated compute processes the uploaded tensor through the rPPG signal processing model, extracting physiological signals and returning calibrated vital signs. The inference layer scales on demand.

Two Integration Paths

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

With @circadify/sdk

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

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

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

const result = await sdk.measureVitals({
  container: document.getElementById('scan-container'),
});

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.

Without the SDK (REST API)

If you cannot use the npm package (e.g., native mobile, server-side, or custom preprocessing), you can call the REST API directly. You are responsible for camera access, preprocessing, and upload:

# 1. Start a session
curl -X POST https://api.circadify.com/sdk/session/start \
  -H "X-API-Key: ck_test_your_key_here" \
  -H "Content-Type: application/json"

# Response: { "session_id": "...", "upload_url": "...", "expires_at": ... }

# 2. Upload preprocessed tensor to the secure upload URL
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/webm" \
  --data-binary @tensor.bin

# 3. Notify the backend that upload is complete
curl -X POST https://api.circadify.com/sdk/session/$SESSION_ID/upload-complete \
  -H "X-API-Key: ck_test_your_key_here"

# 4. Poll for results
curl https://api.circadify.com/sdk/session/$SESSION_ID/result \
  -H "X-API-Key: ck_test_your_key_here"

Caution

The direct API path requires you to produce the same binary format the SDK generates. Contact support@circadify.com for the format specification.

Design Principles

• Privacy-first — The SDK transmits preprocessed skin region data, never raw video. No biometric imagery touches our servers.
• Short-lived data — Uploaded data is auto-deleted after 7 days. Session state expires within minutes. Nothing persists long-term.
• Secure by default — API keys are hashed before storage. All traffic is TLS 1.3. 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

All SDK and API requests are authenticated with API keys in the format ck_{environment}_{hex}:

• Test keys (ck_test_*) — For development and testing
• Live keys (ck_live_*) — For production use

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?
4. Usage quota — Has the developer exceeded their monthly scan limit?

Rate limit headers are returned on every response:

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

Plan Tiers

	Starter	Pro	Enterprise
Monthly scans	500	5,000	50,000
Requests/hour	300	1,000	5,000
API keys	3	5	10
Vitals	All 6	All 6	All 6

All plans include heart rate, respiratory rate, HRV, SpO2, systolic BP, and diastolic BP.

Next Steps

• Data Flow — Step-by-step walkthrough of how data moves through the system
• On-Device Processing — How the SDK preprocesses video frames locally
• Authentication — API key management and security best practices
• REST API Overview — Complete API reference