Abridge Core Workflow B — Patient-Facing Documentation

Overview

Secondary workflow: generating plain-language patient summaries from the same clinical encounter captured in Workflow A. Abridge produces both clinician notes and patient-friendly after-visit summaries (AVS), supporting 28+ languages and multiple reading levels.

Prerequisites

• Completed abridge-core-workflow-a (encounter-to-note pipeline)
• Patient portal integration configured (Epic MyChart, Athena Patient Portal)
• Understanding of health literacy requirements

Instructions

Step 1: Request Patient Summary from Completed Session

// src/workflows/patient-summary.ts
import axios, { AxiosInstance } from 'axios';

interface PatientSummary {
  summary_id: string;
  session_id: string;
  language: string;                    // ISO 639-1 code
  reading_level: 'basic' | 'intermediate' | 'advanced';
  sections: {
    visit_reason: string;              // Plain-language chief complaint
    what_we_discussed: string;         // Key discussion points
    your_diagnosis: string;            // Explained at target reading level
    next_steps: string;                // Action items for patient
    medications: Array<{
      name: string;
      instructions: string;           // "Take 1 pill by mouth twice daily"
      warnings: string;
    }>;
    follow_up: {
      when: string;                    // "Come back in 2 weeks"
      why: string;                     // "To check if your cough improved"
      scheduling_instructions: string;
    };
    questions_to_ask: string[];        // AI-suggested questions for next visit
  };
  source_encounter: {
    date: string;
    provider_name: string;
    department: string;
  };
}

async function generatePatientSummary(
  api: AxiosInstance,
  sessionId: string,
  language: string = 'en',
  readingLevel: PatientSummary['reading_level'] = 'basic'
): Promise<PatientSummary> {
  const { data } = await api.post(`/encounters/sessions/${sessionId}/patient-summary`, {
    language,
    reading_level: readingLevel,
    include_medications: true,
    include_follow_up: true,
    include_suggested_questions: true,
  });

  return data;
}

Step 2: Push to Patient Portal via FHIR

// src/workflows/patient-portal-push.ts
interface FhirCommunication {
  resourceType: 'Communication';
  status: 'completed';
  category: Array<{ coding: Array<{ system: string; code: string }> }>;
  subject: { reference: string };
  encounter: { reference: string };
  payload: Array<{ contentString: string }>;
  sent: string;
}

async function pushToMyChart(
  fhirBaseUrl: string,
  accessToken: string,
  summary: {
    patient_id: string;
    encounter_id: string;
    conten

Abridge Cost Tuning

Overview

Abridge pricing is enterprise, sales-led, and per-provider. Cost optimization focuses on maximizing provider adoption (to justify per-provider cost), reducing wasted sessions, and choosing the right tier for your org size.

Pricing Model (Enterprise)

Instructions

Step 1: Provider Utilization Tracking

// src/cost/provider-utilization.ts
interface ProviderUsage {
  providerId: string;
  enrolledDate: Date;
  sessionsThisMonth: number;
  lastSessionDate: Date | null;
  adoptionStatus: 'active' | 'low_usage' | 'dormant' | 'never_used';
}

function classifyProviderUsage(provider: ProviderUsage): string {
  if (provider.sessionsThisMonth === 0 && !provider.lastSessionDate) return 'never_used';
  if (provider.sessionsThisMonth === 0) return 'dormant';

  const daysSinceEnrolled = (Date.now() - provider.enrolledDate.getTime()) / 86400000;
  const sessionsPerDay = provider.sessionsThisMonth / Math.min(daysSinceEnrolled, 30);

  if (sessionsPerDay < 1) return 'low_usage';
  return 'active';
}

function generateUtilizationReport(providers: ProviderUsage[]): {
  total: number;
  active: number;
  lowUsage: number;
  dormant: number;
  neverUsed: number;
  wastedLicenseCost: string;
} {
  const classified = providers.map(p => ({ ...p, status: classifyProviderUsage(p) }));

  const active = classified.filter(p => p.status === 'active').length;
  const lowUsage = classified.filter(p => p.status === 'low_usage').length;
  const dormant = classified.filter(p => p.status === 'dormant').length;
  const neverUsed = classified.filter(p => p.status === 'never_used').length;
  const wastedPercent = ((dormant + neverUsed) / providers.length * 100).toFixed(1);

  return {
    total: providers.length,
    active,
    lowUsage,
    dormant,
    neverUsed,
    wastedLicenseCost: `${wastedPercent}% of licenses are unused`,
  };
}

Step 2: Session Waste Detection

// src/cost/session-waste.ts
interface SessionMetrics {
  sessionId: string;
  d

Abridge Debug Bundle

Overview

Collect HIPAA-safe diagnostic data for Abridge support tickets. All PHI is automatically redacted before bundle creation.

Prerequisites

• Abridge credentials configured
• Access to application logs
• Node.js or bash for running diagnostic scripts

Instructions

Step 1: Generate Debug Bundle

// src/debug/abridge-debug-bundle.ts
import fs from 'fs';
import { execSync } from 'child_process';

interface DebugBundle {
  timestamp: string;
  environment: Record<string, string>;
  connectivity: Record<string, any>;
  recentErrors: any[];
  sessionDiagnostics: any[];
  fhirStatus: any;
}

async function generateDebugBundle(): Promise<DebugBundle> {
  const bundle: DebugBundle = {
    timestamp: new Date().toISOString(),
    environment: collectEnvironment(),
    connectivity: await testConnectivity(),
    recentErrors: await collectRecentErrors(),
    sessionDiagnostics: await collectSessionDiagnostics(),
    fhirStatus: await checkFhirStatus(),
  };

  // Redact PHI before saving
  const sanitized = redactPhi(JSON.stringify(bundle, null, 2));
  const filename = `abridge-debug-${Date.now()}.json`;
  fs.writeFileSync(filename, sanitized);
  console.log(`Debug bundle saved: ${filename}`);

  return bundle;
}

function collectEnvironment(): Record<string, string> {
  return {
    nodeVersion: process.version,
    platform: process.platform,
    abridgeBaseUrl: process.env.ABRIDGE_BASE_URL || 'NOT SET',
    orgId: process.env.ABRIDGE_ORG_ID ? 'SET (redacted)' : 'NOT SET',
    clientSecret: process.env.ABRIDGE_CLIENT_SECRET ? 'SET (redacted)' : 'NOT SET',
    fhirBaseUrl: process.env.EPIC_FHIR_BASE_URL || 'NOT SET',
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  };
}

async function testConnectivity(): Promise<Record<string, any>> {
  const results: Record<string, any> = {};
  const endpoints = [
    { name: 'abridge_api', url: `${process.env.ABRIDGE_BASE_URL}/health` },
    { name: 'fhir_server', url: `${process.env.EPIC_FHIR_BASE_URL}/metadata` },
  ];

  for (const ep of endpoints) {
    try {
      const start = Date.now();
      const res = await fetch(ep.url, { signal: AbortSignal.timeout(5000) });
      results[ep.name] = { status: res.status, latency_ms: Date.now() - start };
    } catch (err) {
      results[ep.name] = { status: 'UNREACHABLE', error: (err as Error).message };
    }
  }
  return results;
}

function redactPhi(text: string): string {
  return text
    .replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN-REDACTED]')
    .replace(/\b\d{10}\b/g, '[MRN-REDACTED]')
    .replace(/"(name|patient_name|given|family)":\s*"[^"]+"/g, '"$1": "[REDACTED]"')
    .replace(/\b\d{1,2}\/\d{1,2}\/\d{2,4}\b/g,

Abridge Deploy Integration

Overview

Deploy Abridge clinical AI integration to HIPAA-compliant cloud infrastructure. Healthcare deployments require BAA-covered cloud services, encrypted secrets, audit trails, and VPC-restricted networking.

Prerequisites

• Completed abridge-prod-checklist
• BAA-covered cloud account (GCP, AWS, or Azure)
• Container registry access
• Abridge production credentials from partner portal

Instructions

Step 1: HIPAA-Compliant Dockerfile

# Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
  ca-certificates curl && rm -rf /var/lib/apt/lists/*

# Run as non-root (HIPAA best practice)
RUN groupadd -r abridge && useradd -r -g abridge abridge
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

USER abridge
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

Step 2: GCP Cloud Run Deployment (HIPAA BAA)

#!/bin/bash
# deploy-cloud-run.sh

PROJECT_ID="${GCP_PROJECT_ID}"
SERVICE_NAME="abridge-integration"
REGION="us-central1"

# Build container
gcloud builds submit --tag "gcr.io/${PROJECT_ID}/${SERVICE_NAME}"

# Deploy to Cloud Run with HIPAA controls
gcloud run deploy "${SERVICE_NAME}" \
  --image "gcr.io/${PROJECT_ID}/${SERVICE_NAME}" \
  --region "${REGION}" \
  --platform managed \
  --no-allow-unauthenticated \
  --min-instances 1 \
  --max-instances 10 \
  --memory 1Gi \
  --cpu 2 \
  --timeout 120 \
  --set-secrets="ABRIDGE_CLIENT_SECRET=abridge-client-secret:latest,ABRIDGE_ORG_ID=abridge-org-id:latest,EPIC_CLIENT_SECRET=epic-client-secret:latest" \
  --vpc-connector "projects/${PROJECT_ID}/locations/${REGION}/connectors/abridge-vpc" \
  --vpc-egress all-traffic \
  --set-env-vars="NODE_ENV=production,NODE_TLS_MIN_VERSION=TLSv1.3,AUDIT_LOG_ENABLED=true"

# Verify health
SERVICE_URL=$(gcloud run services describe "${SERVICE_NAME}" --region="${REGION}" --format='value(status.url)')
curl -s "${SERVICE_URL}/health" -H "Authorization: Bearer $(gcloud auth print-identity-token)"

Step 3: Health Check Endpoint

// src/server/health.ts
import express from 'express';

const app = express();

app.get('/health', async (req, res) => {
  const checks = {
    server: 'healthy',
    abridge: await checkAbridgeApi(),
    fhir: await 

Abridge Hello World

Overview

Minimal working example demonstrating Abridge's ambient clinical documentation. This creates a simulated encounter session, sends audio/transcript data, and receives a structured clinical note.

Prerequisites

• Completed abridge-install-auth setup
• Abridge sandbox credentials configured
• Node.js 18+ with TypeScript

Instructions

Step 1: Create Project Structure

mkdir abridge-hello-world && cd abridge-hello-world
npm init -y
npm install axios dotenv typescript @types/node
npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext

Step 2: Build the Encounter Session Client

// src/encounter-session.ts
import axios, { AxiosInstance } from 'axios';

interface EncounterSession {
  session_id: string;
  patient_id: string;
  provider_id: string;
  encounter_type: 'outpatient' | 'inpatient' | 'emergency';
  status: 'active' | 'processing' | 'completed';
  created_at: string;
}

interface ClinicalNote {
  note_id: string;
  session_id: string;
  sections: {
    chief_complaint: string;
    history_present_illness: string;
    review_of_systems: string;
    physical_exam: string;
    assessment: string;
    plan: string;
  };
  icd10_codes: Array<{ code: string; description: string }>;
  cpt_codes: Array<{ code: string; description: string }>;
  confidence_score: number;
  source_citations: Array<{
    section: string;
    text: string;
    audio_timestamp_start: number;
    audio_timestamp_end: number;
  }>;
}

class AbridgeClient {
  private api: AxiosInstance;

  constructor() {
    this.api = axios.create({
      baseURL: process.env.ABRIDGE_SANDBOX_URL || 'https://sandbox.api.abridge.com/v1',
      headers: {
        'Authorization': `Bearer ${process.env.ABRIDGE_CLIENT_SECRET}`,
        'X-Org-Id': process.env.ABRIDGE_ORG_ID!,
        'Content-Type': 'application/json',
      },
      timeout: 30000,
    });
  }

  async createSession(
    patientId: string,
    providerId: string,
    encounterType: EncounterSession['encounter_type'] = 'outpatient'
  ): Promise<EncounterSession> {
    const { data } = await this.api.post('/sessions', {
      patient_id: patientId,
      provider_id: providerId,
      encounter_type: encounterType,
      specialty: 'internal_medicine',
      language: 'en',
    });
    return data;
  }

  async submitTranscript(sessionId: string, transcript: string): Promise<void> {
    await this.api.post(`/sessions/${sessionId}/transcript`, {
      text: transcript,
      format: 'plain_text',
    });
  }

  async generateNote(sessionId: string): Promise<ClinicalNote> {
    // Trigger note generation
    await this.api.p

Abridge Install & Auth

Overview

Configure Abridge ambient AI platform credentials and EHR integration tokens. Abridge is an enterprise clinical documentation platform — it does not have a public npm/pip SDK. Integration happens through EHR-embedded workflows (Epic Pal, Athena, eClinicalWorks) and partner API access.

Prerequisites

• Healthcare organization with Abridge contract
• EHR system access (Epic, Athena, eClinicalWorks, Cerner, or AllScripts)
• Abridge Partner Portal credentials from your sales engineer
• HIPAA-compliant infrastructure (required for PHI handling)

Instructions

Step 1: Obtain Abridge Partner Credentials

# Abridge uses partner-issued credentials, not self-service API keys
# Contact your Abridge sales engineer for:
# 1. Partner API client_id and client_secret
# 2. Organization ID (org_id)
# 3. Sandbox environment URL

# Store credentials securely (never in source control)
cat > .env.local << 'EOF'
ABRIDGE_CLIENT_ID=partner_xxxxxxxxxxxx
ABRIDGE_CLIENT_SECRET=secret_xxxxxxxxxxxx
ABRIDGE_ORG_ID=org_xxxxxxxxxxxx
ABRIDGE_BASE_URL=https://api.abridge.com/v1
ABRIDGE_SANDBOX_URL=https://sandbox.api.abridge.com/v1
EOF

chmod 600 .env.local
echo ".env.local" >> .gitignore

Step 2: Configure Epic EHR Integration (Most Common Path)

// src/config/abridge-ehr.ts
// Abridge is Epic's first "Pal" — integration uses Epic's FHIR R4 APIs

interface AbridgeEpicConfig {
  epicClientId: string;           // From Epic App Orchard registration
  epicFhirBaseUrl: string;        // e.g., https://fhir.epic.com/interconnect-fhir-oauth
  abridgeOrgId: string;           // From Abridge partner portal
  abridgeApiBaseUrl: string;      // Partner API endpoint
  smartLaunchUrl: string;         // SMART on FHIR launch URL
}

const config: AbridgeEpicConfig = {
  epicClientId: process.env.EPIC_CLIENT_ID!,
  epicFhirBaseUrl: process.env.EPIC_FHIR_BASE_URL!,
  abridgeOrgId: process.env.ABRIDGE_ORG_ID!,
  abridgeApiBaseUrl: process.env.ABRIDGE_BASE_URL!,
  smartLaunchUrl: `${process.env.EPIC_FHIR_BASE_URL}/oauth2/authorize`,
};

export default config;

Step 3: Authenticate via OAuth 2.0 (SMART on FHIR)

// src/auth/smart-fhir-auth.ts
import axios from 'axios';

interface SmartTokenResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
  scope: string;
  patient?: string;         // Patient context from EHR launch
  encounter?: string;       // Encounter context from EHR launch
}

async function getAbridgeToken(
  authCode: string,
  redirectUri: string
): Promise<SmartTokenResponse> {
  const tokenUrl = `${process.env.EPIC_FHIR_BASE_URL}/oauth2/token`;

  const response = await axios.post(tokenUrl, new URLSearchParams({
    grant_type: &#

Abridge Local Dev Loop

Overview

Local development workflow for Abridge clinical AI integrations. Uses a local HAPI FHIR server for EHR simulation, synthetic patient data from Synthea, and Abridge sandbox APIs. Never use real PHI in development.

Prerequisites

• Completed abridge-install-auth setup
• Docker installed (for local FHIR server)
• Node.js 18+ with TypeScript
• Abridge sandbox credentials

Instructions

Step 1: Start Local FHIR Server

# Run HAPI FHIR R4 server locally
docker run -d --name hapi-fhir \
  -p 8080:8080 \
  -e hapi.fhir.default_encoding=json \
  hapiproject/hapi:latest

# Verify
curl -s http://localhost:8080/fhir/metadata | jq '.fhirVersion'
# → "4.0.1"

# Seed synthetic patient
curl -X POST http://localhost:8080/fhir/Patient \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Patient","name":[{"given":["Jane"],"family":"Doe"}],"birthDate":"1985-03-15","gender":"female"}'

Step 2: Create Dev Environment Configuration

// src/config/dev.ts
interface DevConfig {
  abridge: { baseUrl: string; clientSecret: string; orgId: string };
  fhir: { baseUrl: string };
  fixtures: { transcriptsDir: string };
}

const devConfig: DevConfig = {
  abridge: {
    baseUrl: process.env.ABRIDGE_SANDBOX_URL || 'https://sandbox.api.abridge.com/v1',
    clientSecret: process.env.ABRIDGE_CLIENT_SECRET!,
    orgId: process.env.ABRIDGE_ORG_ID!,
  },
  fhir: { baseUrl: 'http://localhost:8080/fhir' },
  fixtures: { transcriptsDir: './fixtures/transcripts' },
};

export default devConfig;

Step 3: Build Transcript Fixtures

// fixtures/transcripts/index.ts
export const CARDIOLOGY_VISIT = {
  specialty: 'cardiology',
  segments: [
    { speaker: 'provider', text: 'I see you are here for a blood pressure follow-up.', timestamp_ms: 0 },
    { speaker: 'patient', text: 'Yes, I have been taking the lisinopril like you prescribed.', timestamp_ms: 3500 },
    { speaker: 'provider', text: 'Your BP today is 138 over 85. Better, but still elevated. Let us increase lisinopril from 10 to 20mg.', timestamp_ms: 7200 },
    { speaker: 'patient', text: 'Okay. Should I be worried?', timestamp_ms: 15000 },
    { speaker: 'provider', text: 'Not at all. Come back in four weeks.', timestamp_ms: 18000 },
  ],
};

export const DERMATOLOGY_VISIT = {
  specialty: 'dermatology',
  segments: [
    { speaker: 'provider', text: 'What brings you in today?', timestamp_ms: 0 },
    { speaker: 'patient', text: 'I have this mole on my back that

Abridge Performance Tuning

Overview

Performance optimization for high-volume Abridge deployments. Large health systems process thousands of encounters daily — latency in note generation directly impacts clinical workflow throughput.

Performance Targets

Instructions

Step 1: Audio Streaming Optimization

// src/performance/audio-optimizer.ts
// Optimize audio chunk size and streaming for lowest latency

interface AudioStreamMetrics {
  chunkSize: number;
  sendInterval: number;
  bufferUtilization: number;
  latencyP50: number;
  latencyP99: number;
}

class OptimizedAudioStream {
  private buffer: Buffer[] = [];
  private metrics: AudioStreamMetrics = {
    chunkSize: 3200,       // 100ms at 16kHz 16-bit mono = 3200 bytes
    sendInterval: 100,     // Send every 100ms
    bufferUtilization: 0,
    latencyP50: 0,
    latencyP99: 0,
  };

  constructor(
    private ws: WebSocket,
    private sampleRate: number = 16000,
  ) {}

  // Optimal chunk size: 100ms for low latency, 500ms for bandwidth efficiency
  processAudioChunk(chunk: Buffer): void {
    this.buffer.push(chunk);

    const totalSize = this.buffer.reduce((sum, b) => sum + b.length, 0);
    if (totalSize >= this.metrics.chunkSize) {
      const combined = Buffer.concat(this.buffer);
      this.buffer = [];

      if (this.ws.readyState === WebSocket.OPEN) {
        const start = performance.now();
        this.ws.send(combined);
        this.recordLatency(performance.now() - start);
      }
    }
  }

  private recordLatency(ms: number): void {
    // Track P50/P99 for monitoring
    this.metrics.latencyP50 = ms; // Simplified — use histogram in production
  }

  getMetrics(): AudioStreamMetrics {
    return { ...this.metrics };
  }
}

Step 2: Note Generation Pipeline Optimization

// src/performance/note-pipeline.ts
// Pre-warm note generation and parallelize post-processing

interface PipelineStage {
  name: string;
  durationMs: number;
  parallel: boolean;
}

async function optimizedNotePipeline(
  api: any,
  sessionId: string,
): Promise<{ note: any; metrics: PipelineStage[] }> {
  const stages: PipelineStage[] = [];

  // Stage 1: Finalize session (triggers AI processing)
  const t1 = performance.now();
  await api.post(`/encounters/sessions/${sessionId}/finalize`);
  stages.push({ name: 'finalize', durationMs: performance.now() - t1, paral

Abridge Production Checklist

Overview

Production readiness checklist for deploying Abridge clinical AI in a healthcare organization. Clinical documentation systems are safety-critical — this checklist covers HIPAA compliance, EHR integration validation, provider onboarding, and rollback procedures.

Pre-Launch Checklist

Legal & Compliance

• [ ] BAA signed — Business Associate Agreement executed with Abridge
• [ ] HIPAA risk assessment — Completed and documented
• [ ] Data flow diagram — PHI flow mapped: microphone → Abridge → EHR
• [ ] Breach notification plan — 60-day notification procedure documented
• [ ] Patient consent — State-specific recording consent requirements met
• [ ] Medical staff approval — Clinical AI usage approved by medical staff committee

Infrastructure

• [ ] TLS 1.3 — Enforced on all Abridge API connections
• [ ] Secrets management — Credentials in secret manager (not env files)
• [ ] Audit logging — All PHI access logged with 6-year retention
• [ ] Monitoring — Health checks, latency alerts, error rate dashboards
• [ ] Backup connectivity — Fallback for Abridge outages (manual documentation)

EHR Integration

• [ ] FHIR R4 endpoint — Verified DocumentReference POST works
• [ ] Epic SmartPhrases — Mapped to Abridge note templates
• [ ] Provider enrollment — All go-live providers registered in Abridge
• [ ] Specialty configuration — Licensed specialties configured per contract
• [ ] Note templates — SOAP/H&P/Progress templates validated with clinical leads

Validation Script

// src/prod/readiness-check.ts
interface ReadinessResult {
  check: string;
  status: 'pass' | 'fail' | 'warn';
  detail: string;
}

async function runReadinessChecks(): Promise<ReadinessResult[]> {
  const results: ReadinessResult[] = [];

  // 1. API connectivity
  try {
    const res = await fetch(`${process.env.ABRIDGE_BASE_URL}/health`, {
      headers: { 'Authorization': `Bearer ${process.env.ABRIDGE_CLIENT_SECRET}` },
    });
    results.push({ check: 'API Health', status: res.ok ? 'pass' : 'fail', detail: `HTTP ${res.status}` });
  } catch (err) {
    results.push({ check: 'API Health', status: 'fail', detail: (err as Error).message });
  }

  // 2. FHIR endpoint
  try {
    const res = await fetch(`${process.env.EPIC_FHIR_BASE_URL}/metadata`);
    results.push({ check: 'FHIR Server', status: res.ok ? 'pass' : 'fail', detail: `HTTP ${res.st

Abridge Rate Limits

Overview

Abridge enforces rate limits per organization to ensure platform stability across thousands of concurrent clinical encounters. Limits vary by contract tier and are enforced at the org_id level.

Rate Limit Tiers

Response Headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1711234567
Retry-After: 30

Instructions

Step 1: Rate Limit Aware Client

// src/abridge/rate-limiter.ts
interface RateLimitState {
  remaining: number;
  limit: number;
  resetAt: Date;
  retryAfter?: number;
}

class AbridgeRateLimiter {
  private state: RateLimitState = {
    remaining: Infinity,
    limit: Infinity,
    resetAt: new Date(),
  };
  private queue: Array<{ resolve: () => void; reject: (err: Error) => void }> = [];
  private processing = false;

  updateFromHeaders(headers: Record<string, string>): void {
    if (headers['x-ratelimit-remaining']) {
      this.state.remaining = parseInt(headers['x-ratelimit-remaining']);
    }
    if (headers['x-ratelimit-limit']) {
      this.state.limit = parseInt(headers['x-ratelimit-limit']);
    }
    if (headers['x-ratelimit-reset']) {
      this.state.resetAt = new Date(parseInt(headers['x-ratelimit-reset']) * 1000);
    }
    if (headers['retry-after']) {
      this.state.retryAfter = parseInt(headers['retry-after']);
    }
  }

  async waitForSlot(): Promise<void> {
    if (this.state.remaining > 0) {
      this.state.remaining--;
      return;
    }

    // Wait until rate limit resets
    const waitMs = Math.max(0, this.state.resetAt.getTime() - Date.now());
    console.log(`Rate limited — waiting ${waitMs}ms for reset`);
    await new Promise(r => setTimeout(r, waitMs));
    this.state.remaining = this.state.limit;
  }

  get utilizationPercent(): number {
    return ((this.state.limit - this.state.remaining) / this.state.limit) * 100;
  }
}

export { AbridgeRateLimiter };

Step 2: Concurrent Session Manager

// src/abridge/session-pool.ts
import Bottleneck from 'bottleneck';

// Manage concurrent encounter sessions within org limits
const sessionLimiter = new Bottleneck({
  maxConcurrent: 50,          // Stay under tier limit
  minTime: 100,               // 100ms between session creates
  reservoir: 50,              // Burst capacity
  reservoirRefreshInterval: 60000,  // 

Abridge Reference Architecture

Overview

Reference architecture for Abridge clinical AI integration in a multi-site health system. Covers data flow, component design, EHR integration patterns, and HIPAA-compliant infrastructure.

System Architecture

                    Health System Network
┌──────────────────────────────────────────────────────┐
│                                                       │
│  ┌─────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │ Provider │───▶│ Abridge App  │───▶│ Integration  │ │
│  │ Device   │    │ (Ambient AI) │    │ Service      │ │
│  │ (mobile/ │    │              │    │ (your code)  │ │
│  │ desktop) │    └──────┬───────┘    └──────┬───────┘ │
│  └─────────┘           │                    │         │
│                        │                    │         │
│              ┌─────────▼─────────┐          │         │
│              │ Abridge Cloud API │          │         │
│              │ (Partner API)     │          │         │
│              │ - Session mgmt    │          │         │
│              │ - Note generation │          │         │
│              │ - Patient summary │          │         │
│              └─────────┬─────────┘          │         │
│                        │                    │         │
│              ┌─────────▼─────────┐  ┌──────▼───────┐ │
│              │ Webhook Events    │  │ EHR System   │ │
│              │ - Note completed  │──│ (Epic/Athena)│ │
│              │ - Quality alerts  │  │ FHIR R4 API  │ │
│              └───────────────────┘  └──────────────┘ │
│                                                       │
└──────────────────────────────────────────────────────┘

Project Structure

abridge-integration/
├── src/
│   ├── config/
│   │   ├── abridge.ts           # Abridge API configuration
│   │   ├── ehr.ts               # EHR/FHIR endpoint config
│   │   └── index.ts             # Environment-based config loader
│   ├── abridge/
│   │   ├── client.ts            # API client singleton
│   │   ├── errors.ts            # HIPAA-safe error handling
│   │   ├── retry.ts             # Retry with backoff
│   │   └── session-manager.ts   # Encounter session lifecycle
│   ├── ehr/
│   │   ├── fhir-client.ts       # FHIR R4 API wrapper
│   │   ├── epic-adapter.ts      # Epic-specific mappings
│   │   ├── athena-adapter.ts    # Athena-specific mappings
│   │   └── note-pusher.ts       # DocumentReference creation
│   ├── webhooks/
│   │   ├── handler.ts           # Express webhook endpoint
│   │   ├── signature.ts         # HMAC signature verification
│   │   ├── event-router.ts      # Event type → handler mapping
│   │   └── idempotency.ts       # Duplicate event prevention
│   ├── security/
│   │   ├── audit-logger.ts      # HIPAA audit trail
│   │   ├── phi-redactor.ts      # PHI detection and redaction
│   │   ├── rbac.ts              # Role-based access control
│   │   └── tls-config.ts       

Abridge SDK Patterns

Overview

Production-ready patterns for Abridge clinical AI integration. Since Abridge operates via partner APIs (not a public SDK), these patterns wrap the REST API with type-safe clients, HIPAA-compliant logging, and healthcare-specific error handling.

Prerequisites

• Completed abridge-install-auth setup
• TypeScript project with strict mode enabled
• Understanding of HIPAA audit logging requirements

Instructions

Step 1: Type-Safe API Client Singleton

// src/abridge/client.ts
import axios, { AxiosInstance, AxiosError } from 'axios';

interface AbridgeConfig {
  baseUrl: string;
  clientSecret: string;
  orgId: string;
  timeoutMs?: number;
  maxRetries?: number;
}

class AbridgeApiClient {
  private static instance: AbridgeApiClient | null = null;
  private api: AxiosInstance;
  private config: AbridgeConfig;

  private constructor(config: AbridgeConfig) {
    this.config = config;
    this.api = axios.create({
      baseURL: config.baseUrl,
      timeout: config.timeoutMs || 30000,
      headers: {
        'Authorization': `Bearer ${config.clientSecret}`,
        'X-Org-Id': config.orgId,
        'Content-Type': 'application/json',
        'X-Request-Source': 'partner-integration',
      },
    });

    // Request/response interceptors for audit logging
    this.api.interceptors.request.use((req) => {
      req.headers['X-Correlation-Id'] = crypto.randomUUID();
      this.auditLog('request', req.method!, req.url!, req.headers['X-Correlation-Id']);
      return req;
    });

    this.api.interceptors.response.use(
      (res) => { this.auditLog('response', res.config.method!, res.config.url!, res.status); return res; },
      (err) => { this.auditLog('error', err.config?.method, err.config?.url, err.response?.status); throw err; }
    );
  }

  static getInstance(): AbridgeApiClient {
    if (!AbridgeApiClient.instance) {
      AbridgeApiClient.instance = new AbridgeApiClient({
        baseUrl: process.env.ABRIDGE_BASE_URL!,
        clientSecret: process.env.ABRIDGE_CLIENT_SECRET!,
        orgId: process.env.ABRIDGE_ORG_ID!,
      });
    }
    return AbridgeApiClient.instance;
  }

  // HIPAA-compliant audit log — never log PHI
  private auditLog(type: string, method: string, url: string, detail: any): void {
    const entry = {
      timestamp: new Date().toISOString(),
      type,
      method: method?.toUpperCase(),
      endpoint: url?.replace(/\/sessions\/[^/]+/, '/sessions/{id}'), // Redact IDs
      detail: typeof detail === 'number' ? `status:${detail}` : `id:${detail}`,
    };
    console.log(JSON.stringify(entry));
  }

  get http(): AxiosInstance { return this.api; }
}

export { AbridgeApiClient };

Step 2: HIPAA-Safe Error Handler