Tether

In Plain English

The problem

Roughly one in five patients sent home from a hospital ends up back in the emergency room within 30 days. The main reasons are not surprising: people forget medication doses, miss the early signs that things are going wrong, or do not know whether a symptom is normal recovery or a real warning. Doctors give a printed discharge summary, but it sits in a drawer. Family caregivers want to help but rarely have visibility.

What Tether does

Tether is three things in one app:

• A pocket version of the discharge plan. The doctor writes the plan once. The patient sees daily medications, daily activities, red-flag symptoms to watch for, and follow-up dates. Everything is in plain language and can be read out loud in their language.
• An AI assistant that only knows the doctor's plan. The patient asks "Can I take Tylenol?" or "Should I worry about this chest pain?" and the assistant answers using only what is in the plan. It never makes up medical advice. If the question matches a red-flag symptom the doctor listed, the answer is marked urgent.
• A voice check that listens for trouble. The patient records 10 seconds of their voice. A signal-processing engine running on Cloudflare's edge servers measures breathing rate, cough patterns, voice fatigue, and clinical voice-quality markers (jitter, shimmer, HNR). Numbers track over time, so a small change today against the patient's own baseline can flag a problem the patient does not notice.

Who is in the loop

• Patients get the daily guidance and assistant chat.
• Doctors see a recovery score dashboard sorted by risk, plus the patient's biomarker trends and adherence history.
• Family caregivers get a read-only dashboard if the patient invites them by email. They can see the plan, the last few biomarker readings, and which medication doses were taken.

Why it works without violating privacy

Voice recordings never leave the device except as raw PCM audio sent to the analysis endpoint, and even there they are not stored after analysis. Only the numerical biomarker results are saved. The chat AI runs through a Cloudflare Worker that never sees the patient's account credentials. Passwords are hashed on-device using expo-crypto. Caregiver access is opt-in and revocable by the patient.

What it does not do

• It is not a replacement for a doctor. The assistant cannot prescribe, diagnose, or give advice outside the published plan.
• It is not a medical device. Current biomarker accuracy is good enough to spot trends and prompt human review, not to make standalone clinical decisions.
• It is not a HIPAA-certified product yet. The technical foundation is correct (encryption, no PHI in logs) but the compliance audit and BAAs are part of the funded roadmap.

How It Works

Tether keeps patients and doctors connected after a hospital discharge. Here is the simple version:

Architecture

Tether follows a privacy-first architecture. API keys never ship in the mobile bundle — all LLM requests and biomarker analysis are proxied through a Cloudflare Worker at the edge.

Quickstart

Prerequisites

• Node.js 18+
• Expo CLI (npm install -g expo-cli)
• iOS Simulator (Xcode) or Android Emulator
• Rust + wasm-pack (for biomarker engine development)

Setup

git clone https:
cd tether
npm install
cp src/lib/config.template.ts src/lib/config.ts
npm run ios

That's it. The config template comes pre-configured with the shared Tether API — no API keys or environment variables needed. The Groq key lives on the Cloudflare Worker and is never exposed to the client.

Worker Setup

# Deploy the Cloudflare Worker
cd worker
npm install
npx wrangler secret put GROQ_API_KEY
npx wrangler deploy

Features

Auth

• Login / signup with role selection (doctor or patient)
• Passwords hashed with SHA-256 (expo-crypto)
• Session persistence — reopening the app skips login
• Terms/privacy consent on signup

Doctor Workspace

• Create/edit patient recovery plans (diagnosis, vitals, meds, instructions, red flags, follow-up)
• Set AI tone (calm, direct, reassuring)
• Publish plans to a specific patient email (validates account exists)
• Draft auto-saves locally
• View and reply to patient messages

Patient Companion

• View the recovery plan assigned to your email
• Vitals summary, daily instructions, red flags
• AI chat powered by Groq with keyword-matching fallback
• Quick prompt buttons ("What should I do today?", "When should I call?", etc.)
• Voice input via speech recognition
• Voice output (text-to-speech on AI replies, toggleable)
• Urgency badges on AI responses (routine / contact clinician / urgent)
• Flesch-Kincaid readability score on every AI response (grade level badge)
• Handoff suggestion when AI can't fully answer
• Direct messaging to doctor (real-time via Durable Objects)
• Multilingual support (English, Spanish, Hindi, Mandarin, French, Arabic)
• Voice biomarker analysis (breathing rate, cough detection, vocal tremor, voice energy)
• Biomarker status levels (normal / monitor / alert) with alert popup
• Biomarker trending — historical chart showing trends over time
• Engine connection — biomarker data injected into AI context automatically
• Patient Journal — daily journal entries that feed into AI context for more personalized responses
• Medication Adherence Tracker — daily yes/no medication logging with 7-day streak visualization
• Time-aware prompting — AI adapts advice based on days since discharge (early/mid/extended recovery)

Doctor Workspace (continued)

• Discharge date — set per patient to enable time-aware recovery guidance
• Recovery Score Dashboard — composite 0-100 score per patient (biomarker + adherence + engagement + journal), sorted by risk

Onboarding

• 5-step tutorial on first launch (welcome, doctors, patients, voice biomarkers, safety)
• Skip button and dot indicators
• Only shows once (stored in AsyncStorage)

Infrastructure

• Cloudflare Worker proxy — API key stays server-side, never ships in the app
• Durable Objects backend — accounts, plans, messages, biomarker history persist across devices
• Rust WASM biomarker engine runs at the edge inside the worker
• AI requests routed through worker, falls back to direct Groq, then keyword matching

Authentication

Users sign up with a role (Doctor or Patient) and are routed to the appropriate workspace after login. Sessions persist across app restarts via AsyncStorage.

• Password hashing: SHA-256 via expo-crypto — plaintext passwords are never stored
• Session restore: On launch, the app checks AsyncStorage for an active session and skips login if found
• Role-based routing: Doctors see the workspace; patients see the companion
• Validation: Email format, password strength (8+ chars with a number), and terms acceptance

Doctor Workspace

Doctors create, edit, and publish recovery plans for specific patients. Plans are the foundation of the entire patient experience — the AI, the UI, and the messaging system all derive from the published plan.

Plan Fields

Messaging

Doctors see all patient message threads, sorted by most recent. They can select a thread and reply directly. When a patient sends a message (or the AI suggests a handoff), it appears here.

Patient Companion

The patient screen surfaces the published recovery plan and provides multiple channels for getting help: AI chat, voice input, quick prompts, biomarker analysis, and direct doctor messaging.

Caregiver Portal

Adult children of elderly patients, partners, and family members often need visibility into post-discharge recovery without being clinical providers. The caregiver portal is a third login type that gives trusted contacts a read-only dashboard for any patient who explicitly links them.

How linking works

1. The caregiver creates a Tether account with the caregiver role at sign-up.
2. The patient adds the caregiver's email to their account → triggers POST /api/caregiver/link.
3. The caregiver logs in and sees a dashboard of every patient who linked them.
4. Either side can revoke the link at any time.

What the caregiver sees

Privacy model

Caregivers can read but cannot send messages, edit plans, or post journal entries on the patient's behalf. The patient remains the data owner — every link is opt-in and removable. The doctor is not notified of caregiver links by default; the patient controls who sees what.

Data flows

GET /api/caregiver/patients?email=<caregiver-email>
→ [
    {
      patientEmail, patientName,
      latestPlan,
      recentBiomarkers,
      recentAdherence
    },
    ...
  ]

Protocol Library

Doctors don't write a recovery plan from scratch every time. The protocol library ships five clinically-grounded templates, each one a complete DoctorPlan shape — diagnosis text, medications with dosing, daily instructions, red flags, follow-up timing, and recommended tone.

Included templates (v1)

How a doctor uses it

1. Open the Doctor Workspace → "Publish Patient Plan" section.
2. Click any protocol chip — fields auto-fill with the template defaults.
3. Edit anything that's patient-specific (medications, follow-up timing, tone).
4. Add the patient's name and email → publish.

Why this matters

A solo physician can publish 5–10 plans per evening with the protocol library, vs. 1–2 from scratch. More importantly: the templates encode best-practice red flags ("weight gain >1 kg in a day" for CHF, "rescue inhaler more than every 4 hours" for COPD) that an under-the-gun doctor might forget to write. The templates are clinically reviewable and version-controlled in src/lib/protocols.ts.

Extending

Adding a new condition is one object in the PROTOCOL_TEMPLATES array — the UI picks it up automatically. The schema is { id, label, emoji, conditionICD10, defaults }, where defaults is a Partial<DoctorPlan>.

AI Chat System

The AI is powered by Groq's LLaMA 3.3 70B model, accessed through a Cloudflare Worker proxy. Every response is grounded in the doctor's published care plan.

System Prompt

A dynamic system prompt is built from the care plan that includes the patient's diagnosis, medications, instructions, red flags, and the doctor's preferred tone. The AI is instructed to:

• Only answer from documented care plan data
• Flag red-flag symptoms as "urgent"
• Suggest messaging the doctor when information is missing
• Return structured JSON with message, urgency, supporting points, and handoff flag

Response Urgency Levels

Fallback Chain

1. Cloudflare Worker → Groq API (primary)
2. Direct Groq API call (if worker fails)
3. Keyword matching (if no API configured)

Voice Biomarkers

Tether's biomarker system records a short voice sample from the patient, extracts PCM audio data, and sends it to a Rust WASM engine running on the Cloudflare Worker for real-time signal processing.

How It Works

1. Patient taps "Start Voice Check" — expo-audio begins recording in WAV/PCM format at 16kHz
2. Patient speaks naturally for 10-15 seconds, then taps "Stop & Analyze"
3. Recording is read as an ArrayBuffer, PCM samples extracted from WAV headers
4. Samples sent to Worker's /analyze endpoint as JSON
5. Rust WASM engine processes samples and returns a BiomarkerReport
6. Results displayed as a card with status badge (normal / monitor / alert)
7. Report saved to Durable Objects for historical trending

Biomarker Trending

Every biomarker report is stored server-side with a timestamp. The patient's biomarker card shows a trend view of the last 10 readings with bar charts for breathing rate, voice energy, and cough events. Alert/monitor/normal counts are summarized as colored pills. This turns a single snapshot into a longitudinal monitoring system that can detect deterioration over days.

Clinical Voice Quality Card

Below the core metrics the card surfaces the clinical voice quality section: Mean Pitch (Hz), Jitter %, Shimmer %, and HNR (dB), each annotated with the healthy reference range. These are the same metrics used by Praat (the academic reference tool for voice biology). The section appears only when the engine successfully extracted enough voiced cycles, so it does not show on whisper-only or breath-only recordings.

Engine Connection

Tether's two AI engines — NLP (Groq LLM) and Bio-Acoustic (Rust WASM) — share context automatically:

• The latest biomarker report (including confidence score and all 5 metrics) is injected into the AI system prompt before every chat request
• When the patient asks "how am I doing?", the AI references actual biomarker readings (breathing rate, cough events, energy levels, zero-crossing rate)
• If biomarkers are in "alert" status, the AI proactively warns the patient and recommends contacting their care team
• The AI knows the analysis confidence level and can qualify its answers accordingly ("Your latest voice check had moderate confidence — consider recording again in a quieter space")
• One engine listens to the body, the other explains what it means in plain language

Automatic Alert Escalation

When a biomarker recording returns alert status (2+ flags), Tether automatically sends a care message to the assigned doctor — no patient action needed. The message includes:

• Full biomarker summary with actual values and normal ranges
• Confidence score for the analysis
• A note that the message was sent automatically by the biomarker system

The patient sees "Health Alert — Doctor Notified" confirming the escalation happened. This means a patient could record a voice check, trigger an alert, and their doctor sees it in their inbox within seconds — all without the patient needing to understand or act on the medical data themselves.

Readability Scoring

Every AI response is scored using the Flesch-Kincaid Grade Level formula. A badge on each message shows the grade level (e.g., "Grade 4.2 - Very Easy"). This proves the health literacy claim with data:

• Grade 0-5: Very Easy — 5th grader can understand
• Grade 6-8: Easy — middle school level
• Grade 9-12: Moderate — high school level
• Grade 13+: Complex — college level (AI is prompted to stay below 6)

Patient Journal

Patients can write daily journal entries describing how they feel. This serves two purposes:

• Patient self-reflection: Writing about symptoms, mood, and progress helps patients track their own recovery
• AI context enrichment: The 3 most recent journal entries are injected into the AI system prompt, allowing responses to account for the patient's current emotional and physical state

Entries are stored server-side via Durable Objects (max 100 per patient, 2000 character limit). The patient sees their entries in reverse chronological order. The journal also contributes to the Recovery Score (up to 20 points).

Medication Adherence Tracker

A simple daily check-in that asks patients: "Did you take all your medicines today?" with Yes/No buttons.

• One log per day: Duplicate entries for the same day are prevented
• 7-day streak: Colored dots show recent adherence (green = taken, red = missed)
• AI awareness: Adherence records are injected into the AI prompt — if the patient has missed 2+ days, the AI gently reminds them about medication importance
• Recovery Score input: Adherence contributes up to 30 points to the composite score

Time-aware Prompting

Doctors can set a discharge date on each patient's plan. The AI system prompt then calculates days since discharge and adjusts its approach:

A "Day X since discharge" badge appears on the patient's journal section for awareness.

Recovery Score

A composite 0-100 score calculated per patient, visible to doctors on their workspace. Patients are sorted lowest-first so the most at-risk patients get attention first.

Scoring Breakdown

Risk Levels

• 0-39: At Risk — needs immediate attention
• 40-69: Recovering — progressing but needs monitoring
• 70-100: On Track — recovery going well

Multilingual Support

Patients can select their preferred language from: English, Spanish, Hindi, Mandarin, French, or Arabic. The language preference is stored server-side and affects:

• AI chat responses — the system prompt instructs the LLM to respond in the selected language at a 5th grade reading level
• Voice output — text-to-speech uses the correct language code
• The setting persists across devices via Durable Objects

Cloudflare Worker

The Worker serves as the secure API proxy and data backend. It exposes AI endpoints and a full data API backed by Durable Objects:

API Endpoints

Durable Objects Backend

All application data (accounts, plans, messages, biomarker history) is stored in a Cloudflare Durable Object (TetherData). This replaces the previous AsyncStorage-only approach and provides:

• Cross-device sync — a doctor publishes a plan on their laptop, the patient sees it on their phone instantly
• Strong consistency — single-instance guarantee means no stale reads across regions
• Edge persistence — data persists in Cloudflare's global network with automatic replication
• Privacy — password hashes are stored server-side (SHA-256), never exposed to clients

The DO seeds itself with starter accounts on first access. AsyncStorage is only used for local session state (which user is logged in on this device).

Rust WASM Engine

The biomarker engine is written in Rust, compiled to WebAssembly via wasm-pack, and loaded as an ES module inside the Cloudflare Worker. This gives near-native signal processing performance at the edge.

Entry Points

pub fn analyze_audio(samples_i16: &[i16], sample_rate: u32) -> String
pub fn analyze_audio_typed(samples_i16: &[i16], sample_rate: u32, recording_type: &str) -> String

Accepts raw PCM samples and sample rate. analyze_audio_typed additionally takes a recording type ("speech" or "breathing") and tunes the envelope window accordingly. Returns a JSON-encoded BiomarkerReport.

Signal Quality & Preprocessing

• Duration Gate — Recordings shorter than 1.5 seconds are rejected outright rather than analyzed with poor statistics.
• Signal Quality Gate — Computes SNR from quartile energy ratios. Recordings with SNR below threshold are rejected with a "record in a quieter environment" message instead of producing misleading results.
• Clipping Gate — Recordings with more than 1% of samples saturated at the digital ceiling are rejected. The threshold is fraction-based rather than max-sample so a single peak does not invalidate an otherwise good recording.
• VAD-style Silence Stripping — Splits audio into 20ms frames, computes adaptive noise floor at the 20th percentile energy, and additionally checks per-frame ZCR. Frames with high ZCR (fricatives, breath noise) are dropped along with silence. This isolates clean voiced speech for downstream pitch and quality metrics.
• Confidence Scoring — 0 to 1 composite: 30% signal quality + 25% recording duration + 25% active speech ratio + 20% pitch detection hit rate. Shown to patients as High, Moderate, or Low badge.

Signal Processing Pipeline

• RMS Energy — Root mean square of silence-stripped samples. Detects fatigue (low energy).
• Zero-Crossing Rate — Frequency of sign changes on active speech. Detects breathy or labored speech.
• Breathing Rate — 200ms energy envelope, moving-average low-pass smoothing, peak detection with hysteresis (1.2x and 0.8x thresholds). The smoothing step separates real breathing rhythm from speech cadence.
• YIN Pitch Detection — Implementation of the YIN algorithm (de Cheveigne and Kawahara, 2002), the standard for monophonic pitch estimation. Per-frame cumulative mean normalized difference function with parabolic interpolation around the period minimum. Substantially more accurate than basic autocorrelation: detects 200 Hz sine at 200.01 Hz.
• Jitter — Mean absolute period-to-period frequency variation across YIN-extracted cycles, normalized by mean period. Clinical reference threshold 1.04% (Teixeira et al., 2013). Elevated in tremor and neurological conditions.
• Shimmer — Mean absolute amplitude difference across consecutive voiced cycles, normalized by mean amplitude. Clinical reference threshold 3.81%. Elevated in laryngeal pathology and breathy voice.
• HNR (Harmonics-to-Noise Ratio) — Computed as 10 * log10(r / (1 - r)) where r is the mean YIN voicing strength. Reported in dB. Healthy voice typically > 20 dB; values below 7 dB suggest dysphonia.
• Mean Pitch and Voiced Fraction — Average fundamental frequency in Hz across all voiced cycles, plus the fraction of the recording where pitch could be reliably extracted.
• Pitch Variability (CV) — Coefficient of variation across YIN-detected pitches. Detects vocal tremor.
• Cough Detection — 30ms frames, sharp energy spikes (> 4x mean) followed by silence (< 0.5x mean within 150ms), plus a broadband check (frame ZCR > 0.20) to discriminate cough from sustained tones. Skip-ahead prevents double-counting. Note: current sensitivity is 13.8% on Coswara. Path to ~92% is YAMNet integration, see Roadmap.

Rich Summary Generation

Instead of bare flag names, summaries include actual values and normal ranges. Examples:

• "Breathing rate is 28/min (normal range: 12–20/min). 3 cough events detected. Consider contacting your care team."
• "Voice biomarkers are within normal ranges." (with confidence note if recording quality was moderate)

Building

cd biomarker
wasm-pack build --target web --out-dir ../worker/wasm --release
# Output: tether_biomarker_bg.wasm (~83KB) + JS bindings

Biomarker Metrics Reference

Core signals

Clinical voice quality (new)

These are the same metrics used by Praat, the academic reference tool for voice biology. Thresholds drawn from Teixeira et al. (2013) and the GRBAS scale.

Status Logic

Validation

The engine has been benchmarked against the Coswara dataset (Indian Institute of Science, Bangalore) using a randomly sampled batch of 29 patient recordings (cough-heavy and sustained vowel-a). Validation script lives at scripts/validate_biomarker.py and runs against the deployed analyze endpoint.

Pitch detection (sine reference)

200 Hz sine wave detected at 200.01 Hz. Pitch accuracy on clean voiced segments: ~99.99%.

Cough detection (Coswara, n=29)

Voice quality (vowel-a) grouped by COVID status

Mean pitch (121.8 Hz) for the healthy adult cohort matches published vocal fold frequencies for adult males. Healthier statuses trend toward higher HNR (cleaner voice) and lower jitter, consistent with clinical literature. Absolute jitter is elevated above published clinical thresholds because Coswara is home-recorded smartphone audio, not clinic-grade. This is a recording-condition floor that controlled capture would address.

Roadmap

No-cost improvements (in progress)

• Per-patient baselining: each user's first 5 recordings establish a personal voice baseline. Subsequent recordings are flagged on deviation from the personal mean (Z-score > 2) rather than absolute clinical thresholds. This compensates for natural inter-speaker variation and dramatically reduces false-positive alerts.
• Client-side audio quality pre-check: before uploading samples, the mobile app verifies sample count, peak amplitude, and basic spectral spread. Bad recordings fail fast with a clear retry message.
• Multi-recording median: optional capture mode that takes three short readings and stores the median across all metrics, reducing variance from noise or single-cough artifacts.
• FFT-based cough discrimination: extends the spike detector with a 1024-point FFT energy ratio check (high-frequency energy > 60% of total during the spike). Targets ~30% lift over the current heuristic without external models.
• Validation harness in CI: scripts/validate_biomarker.py can be wired into GitHub Actions so every engine change auto-reports Coswara accuracy deltas.

Low-cost upgrades (small one-time spend)

• YAMNet via Modal free tier: Modal.com gives $30 per month free compute. Host YAMNet ONNX behind a Modal endpoint; worker calls it for cough/sneeze/breath classification. Closes the cough sensitivity gap from 14% to ~92% without paying for Cloudflare Workers Paid.
• Cloudflare Workers Paid ($5/mo): alternative path that bundles YAMNet ONNX (~15MB) directly into the worker. Lower latency than Modal, same accuracy gain.
• BC-ResNet fine-tuned on COUGHVID (~$50 one-time): specialized 5MB cough detector trained on 25,000 labeled coughs. Projected ~95% sensitivity. Fits on free Workers bundle.

Funded roadmap ($6,000 plus $99/year Apple Developer Program)

• Clinical validation pilot with 50 patients and a part-time clinical advisor.
• HIPAA infrastructure audit, BAAs with all third-party vendors.
• Indie-tier penetration test.
• App Store and Google Play deployment.
• Natural-sounding TTS in six additional languages.

Security

Tech Stack

Onboarding

First-time users see a 5-step tutorial before reaching the login screen. The tutorial covers:

1. Welcome — What Tether does and who it's for
2. For Doctors — How to create and publish recovery plans
3. For Patients — How to use AI chat, voice, and messaging
4. Voice Biomarkers — How voice analysis works and what it detects
5. Safety First — Tether is not a replacement for emergency care

Onboarding completion is stored in AsyncStorage under the key tether-onboarding-complete. The tutorial only shows once.