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.

Prerequisites

An approved data-flow diagram, BAA-covered deployment environment, and a named security and clinical owner for each planned site.
Confirmed EHR sandbox access and SMART-on-FHIR registration for each adapter that will be implemented.
Synthetic fixtures and FHIR validation tests so the architecture can be exercised without production PHI.

Instructions

Select the EHR adapter and site configuration for one sandbox site first.
Implement the session, webhook, FHIR, security, and monitoring boundaries shown in the project structure; keep PHI redaction and audit logging shared rather than reimplementing them per site.
Validate the synthetic note-to-DocumentReference path, including webhook idempotency and authenticated health checks, before adding another site.
Promote a site only after its clinical, privacy, and operations owners sign the readiness evidence and rollback plan.

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        # TLS 1.3 enforcement
│   ├── monitoring/
│   │   ├── health.ts            # Health check endpoint
│   │   ├── metrics.ts           # Performance metrics collector
│   │   └── alerts.ts            # Quality and latency alerts
│   └── server.ts                # Express server entry point
├── tests/
│   ├── unit/                    # Unit tests (no API calls)
│   ├── integration/             # Sandbox API tests
│   └── fhir-validation/         # FHIR resource schema tests
├── fixtures/
│   └── transcripts/             # Synthetic encounter transcripts
├── scripts/
│   ├── deploy-cloud-run.sh      # GCP Cloud Run deployment
│   ├── readiness-check.ts       # Production readiness validation
│   └── diagnostic.sh            # Debug data collection
├── Dockerfile                   # HIPAA-compliant container
├── .env.example                 # Environment template (no secrets)
└── package.json

Key Design Decisions

Decision	Choice	Rationale
Language	TypeScript	Type safety for healthcare data
EHR adapter	Strategy pattern	Swap EHR backends without changing core
Error handling	Custom error class	HIPAA-safe: never log PHI
Authentication	SMART on FHIR	Standard for healthcare OAuth
Deployment	Cloud Run	HIPAA BAA, auto-scaling, managed
Secrets	GCP Secret Manager	HIPAA-compliant, audited access
Monitoring	Custom health endpoint	Abridge + FHIR connectivity checks

Data Flow

1. Provider opens encounter on device
2. Abridge app captures ambient audio
3. Audio streams to Abridge Cloud via WebSocket
4. Real-time transcript fragments returned
5. Provider closes encounter
6. Abridge generates structured clinical note (10-30s)
7. Webhook fires: encounter.session.completed
8. Integration service fetches note via API
9. Note pushed to EHR via FHIR DocumentReference
10. Patient summary generated and pushed to portal
11. Provider reviews, edits, and signs note in EHR
12. Webhook fires: encounter.note.signed

Multi-Site Deployment

// src/config/multi-site.ts
interface SiteConfig {
  siteId: string;
  siteName: string;
  ehrType: 'epic' | 'athena' | 'cerner';
  fhirBaseUrl: string;
  abridgeOrgId: string;
  specialties: string[];
  providerCount: number;
  goLiveDate: Date;
}

const sites: SiteConfig[] = [
  {
    siteId: 'main-campus',
    siteName: 'Main Hospital',
    ehrType: 'epic',
    fhirBaseUrl: 'https://fhir.main-hospital.epic.com/interconnect-fhir-oauth',
    abridgeOrgId: 'org_main_campus',
    specialties: ['internal_medicine', 'cardiology', 'pulmonology'],
    providerCount: 200,
    goLiveDate: new Date('2026-06-01'),
  },
  {
    siteId: 'community-clinic',
    siteName: 'Community Clinic Network',
    ehrType: 'athena',
    fhirBaseUrl: 'https://api.athenahealth.com/fhir/r4',
    abridgeOrgId: 'org_community',
    specialties: ['family_medicine', 'pediatrics'],
    providerCount: 50,
    goLiveDate: new Date('2026-09-01'),
  },
];

Output

Complete project structure for Abridge integration
EHR adapter pattern supporting Epic, Athena, and Cerner
Multi-site deployment configuration
End-to-end data flow documentation

Examples

Start with a single synthetic Epic sandbox site using the main-campus configuration shape, a secret-managed sandbox organization ID, and a mock webhook event. Trace the event from session completion through the idempotency store to a locally validated DocumentReference, recording only resource IDs and aggregate timings. A successful architecture test proves that the adapter, security, and monitoring boundaries cooperate without exposing patient text. If signature verification, FHIR validation, or the health check fails, prevent the note push, retain the redacted failure evidence, and correct that boundary before enabling another site or real traffic.

Error Handling

Failure	Architecture response
Webhook signature is invalid	Reject the event before it reaches the event router.
Duplicate completion event arrives	Use the idempotency record and return a safe duplicate response.
FHIR validation fails	Do not write the note; surface a redacted integration failure to the operator.
Site configuration is incomplete	Keep the site disabled until its EHR, secret, and ownership requirements are verified.

Resources

Next Steps

Start implementation with abridge-install-auth, then follow the skill sequence through production deployment.