| name | abridge-reference-architecture |
| description | Implement Abridge reference architecture for clinical AI integration.
Use when designing a new Abridge deployment, reviewing project structure,
or planning multi-site health system rollouts with EHR integration.
Trigger: "abridge architecture", "abridge project structure",
"abridge system design", "abridge multi-site".
|
| allowed-tools | Read, Write, Edit |
| version | 1.4.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","healthcare","ai","abridge","architecture"] |
| compatibility | Designed for Claude Code |
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 # 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
