ABDM Integration

Purpose: ABDM (Ayushman Bharat Digital Mission) integration for Indian healthcare digital health records, ported from legacy parts/abdm to the new domain-driven architecture under domains/integration/. Schema: integration (PostgreSQL) Tenant Scoped: Yes (all tables except abdm_hip_registry) RLS Enabled: Yes Primary Keys: UUIDv7 Timestamps: TIMESTAMPTZ

Table of ContentsCopy Anchor Link

1. Overview
2. Architecture
3. Database Schema
4. API Endpoints
5. Webhook Flow
6. State Machines
7. Security
8. Frontend Integration
9. Background Jobs
10. Migration from Legacy

OverviewCopy Anchor Link

What is ABDMCopy Anchor Link

ABDM (Ayushman Bharat Digital Mission) is India's national digital health infrastructure. It enables standardized health data exchange between healthcare providers, patients, and health information users. The core concepts are:

• ABHA (Ayushman Bharat Health Account): A unique health ID for every Indian citizen, created via Aadhaar or mobile OTP verification.
• HIP (Health Information Provider): A facility that holds patient health records (e.g., a clinic with prescriptions and encounter data).
• HIU (Health Information User): A facility that requests health records from other facilities, subject to patient consent.
• PHR (Personal Health Record): A patient-facing app where patients manage their health data, approve consent requests, and initiate discovery of their records.
• Consent Manager (CM): The ABDM layer that mediates consent between patients, HIPs, and HIUs.

Why We IntegrateCopy Anchor Link

Kulcare facilities operating in India need to:

• Register as HIP/HIU with the ABDM network
• Create ABHA accounts for patients during clinic visits
• Link clinical records (prescriptions, encounters, diagnostic reports) to patient ABHA identities
• Respond to patient-initiated discovery requests from the PHR app
• Manage consent lifecycle for health data sharing between facilities
• Exchange encrypted FHIR R4 bundles for health data transfer

All of this targets the ABDM Gateway V3 API.

Integration PhasesCopy Anchor Link

The integration is implemented in four phases:

ArchitectureCopy Anchor Link

Domain StructureCopy Anchor Link

ABDM Gateway V3
     |
     |  Outbound API calls (token, link, consent, data)
     v
+----------------------------------------------+
|  Integration::Abdm::ApiClient                |
|  - Lazy token refresh via GatewayTokenService |
|  - Retry with exponential backoff (3 retries) |
|  - Circuit breaker (5 failures / 60s timeout) |
|  - Automatic logging to AbdmApiLog           |
+----------------------------------------------+
     |
     v
+----------------------------------------------+
|  domains/integration/                        |
|  +-- models/         14 ActiveRecord models  |
|  +-- controllers/    REST + webhook endpoints|
|  +-- services/       Business logic          |
|  +-- jobs/           Sidekiq async workers   |
|  +-- blueprints/     Blueprinter serializers |
|  +-- policies/       Pundit authorization    |
|  +-- routes.rb       Route definitions       |
+----------------------------------------------+
     ^
     |  Inbound webhooks (JWT-verified)
     |
ABDM Gateway Callbacks

File LocationsCopy Anchor Link

Key PatternsCopy Anchor Link

BaseRecord: All integration models inherit from Integration::BaseRecord which sets the schema prefix:

class Integration::BaseRecord < ApplicationRecord
  self.abstract_class = true
  self.table_name_prefix = 'integration.'
end

TenantScoped: All tenant-aware models include Shared::Concerns::TenantScoped for automatic tenant filtering.

Result Pattern: All services return a consistent Result struct:

Result = Struct.new(:success?, :data, :errors, keyword_init: true)

Blueprinter Serialization: Each model has a blueprint with normal and detailed views for API responses.

Key ServicesCopy Anchor Link

Webhook HandlersCopy Anchor Link

Database SchemaCopy Anchor Link

All tables reside in the integration PostgreSQL schema. All tables use UUIDv7 primary keys and TIMESTAMPTZ for timestamps.

Phase 1: Infrastructure TablesCopy Anchor Link

integration.abdm_gateway_tokensCopy Anchor Link

Per-tenant JWT tokens for ABDM Gateway V3 API authentication. Tokens are refreshed lazily by ApiClient when expired or within 5 minutes of expiry.

Key methods: self.current(provider:), expired?, near_expiry?, needs_refresh?

integration.abdm_facility_registrationsCopy Anchor Link

HIP/HIU service registrations per facility. A facility can have separate HIP and HIU registrations. Changes are automatically synced to abdm_hip_registry via a database trigger.

Key methods: self.hip_for_facility(id), self.hiu_for_facility(id)

integration.abdm_hip_registryCopy Anchor Link

Non-RLS lookup table for resolving webhook X-HIP-ID / X-HIU-ID headers to tenant and facility context. This table does NOT use TenantScoped because it must be queryable before RLS context is established during webhook pre-authentication. Automatically synced from abdm_facility_registrations via a PostgreSQL trigger.

Key method: self.resolve(service_id) -- used by WebhookBaseController to establish RLS context.

integration.abdm_api_logsCopy Anchor Link

Audit log of all outbound ABDM API requests. Created automatically by ApiClient for every API call. Partitioned by month for high-volume deployments.

integration.abdm_callbacksCopy Anchor Link

Inbound webhook payload audit log with idempotent processing pipeline.

Key methods: claim! (atomic claim for processing), mark_processed!, mark_failed!(error_code:, error_message:). Retry uses exponential backoff: 30s, 60s, 120s, etc.

Phase 2: ABHA Registration TablesCopy Anchor Link

integration.abdm_patient_profilesCopy Anchor Link

ABHA identity linked to a patient. A patient has one ABHA identity regardless of facility. Unique constraint on (tenant_id, patient_id). The profile_data JSONB column contains PII (name, DOB, gender, address) and is encrypted at the application level using encrypts :profile_data.

Key methods: self.find_by_abha(number), self.find_by_address(address), registered?, active?

integration.abdm_auth_sessionsCopy Anchor Link

Multi-step authentication and registration flow state machine with TTL (default 15 minutes). The step_data JSONB column may contain PII and is encrypted at the application level using encrypts :step_data.

Session Types: registration_aadhaar, registration_mobile, registration_enrollment, login_mobile, login_email, login_abha_address, login_abha_number, login_aadhaar, hip_auth

Key methods: transition_to!(status, **attrs), expire_if_needed!, self.find_active_by_txn(txn_id)

Phase 3: HIP Linking TablesCopy Anchor Link

integration.abdm_link_requestsCopy Anchor Link

HIP-initiated linking flow. Consolidates legacy hip_link_requests + hip_link_token_requests since V3 uses a unified flow.

Associations: belongs_to :facility, belongs_to :patient, has_many :care_contexts

integration.abdm_discovery_requestsCopy Anchor Link

Patient-initiated discovery and linking. Created when ABDM sends a discover callback. The patient_demographics JSONB contains name, gender, yearOfBirth, and verified identifiers from the webhook payload.

Key method: generate_verification_code! -- generates random 6-digit code for link confirmation.

integration.abdm_care_contextsCopy Anchor Link

Linked care contexts with FHIR bundles. Core record linking clinical data to ABDM.

The care_context_reference is environment-aware to prevent cross-environment collisions:

• Production: CC-PR-{id}
• Staging: CC-PR-STG-{id}
• Development: CC-PR-DEV-{id}

Key methods: self.generate_reference(type, id), self.generate_display(type, created_at)

Phase 4: Consent and Data Exchange TablesCopy Anchor Link

integration.abdm_consentsCopy Anchor Link

Unified consent lifecycle for both HIP and HIU directions. Status transitions are automatically logged to AbdmConsentAuditLog.

Associations: has_many :consent_artefacts, has_many :data_transfers, has_many :audit_logs

integration.abdm_consent_artefactsCopy Anchor Link

Detailed consent artefacts received from ABDM (primarily HIU side). The artefact_id is globally unique per the ABDM specification. The fhir_records JSONB is erased when data_erase_at is reached.

Key method: erase_data! -- nulls out fhir_records, care_contexts, sets fetch_status='erased'

integration.abdm_data_transfersCopy Anchor Link

Tracks encrypted data transfers in both directions. The key_material JSONB stores ECDH key pairs for Fidelius encryption/decryption.

integration.abdm_consent_audit_logsCopy Anchor Link

Immutable append-only audit trail for consent status transitions. Required for ABDM regulatory compliance. No UPDATE or DELETE operations are permitted (enforced by PostgreSQL RULEs and the readonly? method on persisted records).

ERDCopy Anchor Link

API EndpointsCopy Anchor Link

File: domains/integration/routes.rb

All routes are nested under /integration/abdm. Authenticated endpoints require a valid user session and tenant context. Webhook endpoints use ABDM JWT authentication instead.

Phase 1: Facility RegistrationCopy Anchor Link

Phase 2: ABHA Registration and PHR LoginCopy Anchor Link

ABHA Registration (Aadhaar OTP flow):

ABHA Profile Management:

PHR Session Management:

Phase 3: HIP Linking and Care ContextsCopy Anchor Link

Phase 4: Consent Management and Data ExchangeCopy Anchor Link

Consent (HIP/HIU):

Consent Management (patient-facing CM operations):

Webhooks (ABDM JWT Auth, No User Session)Copy Anchor Link

Webhook FlowCopy Anchor Link

Request Processing PipelineCopy Anchor Link

All ABDM webhooks follow the same pipeline, implemented in WebhookBaseController:

ABDM Gateway
    |
    | POST /integration/abdm/webhooks/{scope}/{action}
    | Headers: Authorization: Bearer <JWT>, X-HIP-ID or X-HIU-ID
    v
+----------------------------------------------------+
| 1. verify_webhook_signature                        |
|    - Extract Bearer token from Authorization header |
|    - Verify JWT signature against ABDM JWKS endpoint|
|    - Check replay protection (5-minute window)      |
|    - On failure: 401 Unauthorized                   |
+----------------------------------------------------+
    |
    v
+----------------------------------------------------+
| 2. resolve_tenant_from_service_id                  |
|    - Read X-HIP-ID or X-HIU-ID from headers        |
|    - Query AbdmHipRegistry.resolve(service_id)      |
|    - On not found: 404 Unknown service ID           |
|    - Extracts: tenant_id, facility_id               |
+----------------------------------------------------+
    |
    v
+----------------------------------------------------+
| 3. set_webhook_rls_context                         |
|    - SET app.current_tenant_id = tenant_id          |
|    - Set Shared::Current.tenant for app scoping     |
+----------------------------------------------------+
    |
    v
+----------------------------------------------------+
| 4. log_and_enqueue_callback                        |
|    - Create AbdmCallback record with:               |
|      callback_type, request_id, transaction_id,     |
|      payload, idempotency_key, status='received'    |
|    - Handle duplicates via RecordNotUnique           |
|    - Enqueue ProcessCallbackJob                      |
+----------------------------------------------------+
    |
    v
+----------------------------------------------------+
| 5. Return 202 Accepted                             |
+----------------------------------------------------+

Callback Processing (async in Sidekiq)Copy Anchor Link

ProcessCallbackJob
    |
    v
+----------------------------------------------------+
| CallbackProcessor.new(callback).process!           |
|                                                    |
| 1. callback.claim!                                 |
|    - Atomic UPDATE WHERE status='received'          |
|    - Returns false if another worker claimed it     |
|                                                    |
| 2. resolve_handler                                 |
|    - Lookup callback_type in HANDLER_REGISTRY       |
|    - Returns [HandlerClass, :method_name]           |
|                                                    |
| 3. Execute handler.method(callback)                |
|    - Handler processes business logic               |
|    - Returns Result(success?, errors)               |
|                                                    |
| 4. Update status                                   |
|    - Success: callback.mark_processed!              |
|    - Failure: callback.mark_failed!(...)            |
|    - After max_attempts: status -> 'dead_letter'    |
+----------------------------------------------------+

Handler RegistryCopy Anchor Link

IdempotencyCopy Anchor Link

Duplicate webhook deliveries are handled at two levels:

1. Database level: The idempotency_key column ({callback_type}:{request_id}) has a uniqueness constraint. Duplicate inserts raise ActiveRecord::RecordNotUnique, which WebhookBaseController catches and returns the existing callback.
2. Processing level: claim! uses an atomic UPDATE WHERE status='received' so only one worker can process a callback even if multiple ProcessCallbackJob instances are enqueued.

State MachinesCopy Anchor Link

All state machines use validated transitions via transition_to! methods. Invalid transitions add an error to the model and return false.

AbdmAuthSessionCopy Anchor Link

initiated --> otp_sent --> otp_verified --> address_suggested --> completed
                                       \-> completed (no address step)
Any state --> expired (TTL, default 15 minutes)
Any state --> failed (error)

AbdmPatientProfile (registration_status)Copy Anchor Link

pending --> aadhaar_verified --> mobile_verified --> registered --> active
                                                                   |
                                                                   v
                                                              deactivated

Note: This uses simple status updates rather than a formal transition_to! method.

AbdmLinkRequestCopy Anchor Link

initiated --> auth_pending --> auth_confirmed --> token_generated --> contexts_adding --> completed
                            \-> failed (auth denied)
Any active state --> expired (TTL)
Any active state --> failed (error)

Terminal statuses: completed, failed, expired

AbdmDiscoveryRequestCopy Anchor Link

pending --> matched --> link_initiated --> link_confirmed
        \-> not_found
Any active state --> failed (error)

Terminal statuses: link_confirmed, not_found, failed

AbdmCareContext (sync_status)Copy Anchor Link

linked --> pending_transfer --> transferred
                            \-> failed
                            \-> expired

Note: This uses simple status updates rather than a formal transition_to! method.

AbdmConsentCopy Anchor Link

requested --> granted --> revoked
          \-> denied
granted --> expired (TTL or consent_expiry reached)

Terminal statuses: denied, revoked, expired

Every transition is automatically logged to AbdmConsentAuditLog with triggered_by (abdm_callback, user_action, system_expiry).

AbdmConsentArtefact (fetch_status)Copy Anchor Link

pending --> fetching --> fetched
                     \-> failed
fetched --> erased (data erasure compliance)

AbdmDataTransferCopy Anchor Link

HIP (outbound):

requested --> acknowledged --> key_generated --> encrypting --> transferring --> completed

HIU (inbound):

requested --> acknowledged --> key_generated --> transferring --> completed

Any active state can transition to failed or partial.

Terminal statuses: completed, failed, partial

AbdmCallbackCopy Anchor Link

received --> processing --> processed
                        \-> failed --> dead_letter (after max_attempts)

Retry uses exponential backoff: 30s, 60s, 120s, etc.

SecurityCopy Anchor Link

Row-Level Security (RLS)Copy Anchor Link

All integration tables (except abdm_hip_registry) have standard tenant isolation RLS:

ALTER TABLE integration.[table] ENABLE ROW LEVEL SECURITY;
ALTER TABLE integration.[table] FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON integration.[table]
  FOR ALL
  USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid)
  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid);

The abdm_hip_registry table has no RLS because it is queried during webhook pre-authentication before tenant context is established. It is a read-only lookup table synced automatically via a database trigger from abdm_facility_registrations.

Webhook AuthenticationCopy Anchor Link

ABDM webhooks are authenticated via JWT signature verification using the WebhookAuthenticator:

1. JWT verification: Token from Authorization: Bearer <token> header is verified against ABDM's JWKS endpoint using RS256 algorithm.
2. JWKS caching: Public keys are cached for 1 hour (JWKS_CACHE_TTL). On verification failure, keys are automatically refreshed (handles key rotation).
3. Replay protection: Request timestamps must be within a 5-minute window (REPLAY_WINDOW).
4. Standard auth skipped: WebhookBaseController skips require_authentication!, set_tenant_from_session, and set_rls_context from the normal controller chain.

PII EncryptionCopy Anchor Link

Two models encrypt sensitive JSONB fields at the application level using Rails encrypts:

• AbdmPatientProfile.profile_data -- Contains name, DOB, gender, address
• AbdmAuthSession.step_data -- Contains suggested addresses, partial identifiers

ECDH Encryption (Fidelius)Copy Anchor Link

All health data transfers use ECDH curve25519 encryption via an external Fidelius HTTP sidecar service:

The service includes a circuit breaker (3 failures / 30s timeout). Base URL is configured via credentials.abdm.fidelius_url (default: http://localhost:8090).

HIP data transfer flow:

1. Acknowledge data request to ABDM Gateway
2. Generate ECDH sender keys via Fidelius
3. Encrypt each care context's FHIR bundle
4. Push encrypted data to HIU's dataPushUrl
5. Notify ABDM of transfer completion with per-context status

HIU data fetch flow:

1. Generate ECDH receiver keys via Fidelius
2. Send data request to ABDM with key material and dataPushUrl
3. Receive encrypted data pushed by HIP
4. Decrypt using Fidelius and store FHIR records in AbdmConsentArtefact

Circuit BreakersCopy Anchor Link

Both external service clients include circuit breakers to handle outages gracefully:

Immutable Audit LogCopy Anchor Link

AbdmConsentAuditLog is an append-only table for regulatory compliance:

• PostgreSQL RULEs prevent UPDATE and DELETE operations
• The model returns readonly? for persisted records
• Every consent state transition automatically creates an audit entry

Data Erasure ComplianceCopy Anchor Link

Mandatory compliance with ABDM data_erase_at dates. The DataErasureJob runs daily and erases:

Frontend IntegrationCopy Anchor Link

TypeScript TypesCopy Anchor Link

File: frontend/apps/cms/src/types/abdm.ts

Defines all type interfaces for the ABDM integration, organized by phase. Each entity has a base interface and a Detailed variant with additional fields:

Union types for status values (matching backend constants exactly):

type AbdmConsentStatus = 'requested' | 'granted' | 'denied' | 'revoked' | 'expired'
type AbdmLinkRequestStatus = 'initiated' | 'auth_pending' | 'auth_confirmed' | 'token_generated' | 'contexts_adding' | 'completed' | 'failed' | 'expired'
type AbdmDataTransferStatus = 'requested' | 'acknowledged' | 'key_generated' | 'encrypting' | 'transferring' | 'completed' | 'failed' | 'partial'

Request parameter types: AbdmConsentCreateParams, AbdmFacilityRegistrationCreateParams, AbdmLinkRequestCreateParams, AbdmAbhaRegistrationParams

Generic API response wrapper:

interface AbdmApiResponse<T> {
  data: T
  meta?: { total: number; page: number; per_page: number }
}

ConstantsCopy Anchor Link

File: frontend/apps/cms/src/constants/abdm.ts

Maps backend enum values to display labels and ABDM specification codes.

Consent purpose options (with ABDM codes):

ABDM_PURPOSE_OPTIONS = [
  { value: 'care_management', code: 'CAREMGT', label: 'Care Management' },
  { value: 'break_the_glass', code: 'BTG', label: 'Break The Glass' },
  { value: 'public_health', code: 'PUBHLTH', label: 'Public Health' },
  { value: 'healthcare_payment', code: 'HPAYMT', label: 'Healthcare Payment' },
  { value: 'disease_research', code: 'DSRCH', label: 'Disease Specific Healthcare Research' },
  { value: 'patient_requested', code: 'PATRQT', label: 'Patient Request' },
]

Health information types:

ABDM_HI_TYPES = [
  { code: 'OPConsultation', label: 'OP Consultation' },
  { code: 'DiagnosticReport', label: 'Diagnostic Reports' },
  { code: 'DischargeSummary', label: 'Discharge Summary' },
  { code: 'Prescription', label: 'Prescription' },
  { code: 'ImmunizationRecord', label: 'Immunization Record' },
  { code: 'HealthDocumentRecord', label: 'Health Document Record' },
]

Terminal status arrays (for UI state checks):

ABDM_CONSENT_TERMINAL_STATUSES: ['denied', 'revoked', 'expired']
ABDM_TRANSFER_TERMINAL_STATUSES: ['completed', 'failed', 'partial']
ABDM_LINK_TERMINAL_STATUSES: ['completed', 'failed', 'expired']
ABDM_DISCOVERY_TERMINAL_STATUSES: ['link_confirmed', 'not_found', 'failed']

API Endpoint PathsCopy Anchor Link

All paths are defined in ABDM_API_PATHS for use with the shared API client:

ABDM_API_PATHS = {
  // Phase 1
  facilityRegistrations: '/integration/abdm/facility_registrations',
  // Phase 2
  abhaRegistrationSendOtp: '/integration/abdm/abha/registrations/send_otp',
  abhaRegistrationVerifyOtp: '/integration/abdm/abha/registrations/verify_otp',
  abhaRegistrationSuggestAddress: '/integration/abdm/abha/registrations/suggest_address',
  abhaRegistrationCreateAddress: '/integration/abdm/abha/registrations/create_address',
  abhaProfiles: '/integration/abdm/abha/profiles',
  phrSessionSendOtp: '/integration/abdm/phr/sessions/send_otp',
  phrSessionVerifyOtp: '/integration/abdm/phr/sessions/verify_otp',
  phrSessionVerifyUser: '/integration/abdm/phr/sessions/verify_user',
  phrSessionRefreshToken: '/integration/abdm/phr/sessions/refresh_token',
  // Phase 3
  linkRequests: '/integration/abdm/link_requests',
  linkRequestsFetchModes: '/integration/abdm/link_requests/fetch_modes',
  linkRequestsAuthInit: '/integration/abdm/link_requests/auth_init',
  linkRequestsAuthConfirm: '/integration/abdm/link_requests/auth_confirm',
  linkRequestsAddContexts: '/integration/abdm/link_requests/add_contexts',
  careContexts: '/integration/abdm/care_contexts',
  // Phase 4
  consents: '/integration/abdm/consents',
  healthRecords: '/integration/abdm/health_records',
  cmConsents: '/integration/abdm/cm/consents',
  cmArtefacts: '/integration/abdm/cm/artefacts',
}

API ClientCopy Anchor Link

File: frontend/apps/cms/src/services/abdmApiV2.ts

Wraps all ABDM endpoints using the shared API client. Methods map 1:1 to the paths above. Used by the React Query hooks below.

React Query HooksCopy Anchor Link

Queries (frontend/apps/cms/src/hooks/useAbdmV2Queries.ts):

All queries are facility-scoped via currentFacilityId from useProfile() and use 30-second stale time.

Mutations (frontend/apps/cms/src/hooks/useAbdmV2Mutations.ts):

All mutations invalidate relevant query caches on success.

Query keys are namespaced under cmsQueryKeys.abdmV2 in frontend/apps/cms/src/lib/queryKeys.ts.

UI ComponentsCopy Anchor Link

All ABDM UI components live in frontend/apps/cms/src/components/abdm/.

ABHA Registration ComponentsCopy Anchor Link

AbhaProfileCard -- Displays a patient's ABHA profile with formatted number (XX-XXXX-XXXX-XXXX), color-coded status badge, and PHR linked status.

<AbhaProfileCard profile={abhaProfile} />

AbhaRegistrationFlow -- Multi-step wizard for creating a new ABHA via Aadhaar OTP. Steps: enter Aadhaar (auto-formatted, masked after send) -> verify OTP (60s resend timer) -> select ABHA address (API suggestions + custom) -> success.

<AbhaRegistrationFlow
  onComplete={(profile) => handleCreated(profile)}
  onCancel={() => close()}
/>

AbhaLinkButton -- Dropdown action button. Shows "Register new ABHA" and "Link via HIP" when no active ABHA exists; shows AbhaProfileCard when ABHA is active.

<AbhaLinkButton
  patientId={patientId}
  abhaProfile={profile}
  onProfileCreated={handleCreated}
  onLinkComplete={handleLinked}
/>

HIP Linking ComponentsCopy Anchor Link

HipLinkingModal -- Multi-step modal for clinic-initiated linking. Steps: fetch auth modes -> select mode (MOBILE_OTP/AADHAAR_OTP) -> OTP verification -> care context selection (checkboxes) -> success.

<HipLinkingModal
  open={isOpen}
  onOpenChange={setIsOpen}
  patientId={patientId}
  abhaAddress="user@abdm"
  onLinkComplete={() => refetch()}
/>

CareContextList -- Filterable list of care contexts linked to a patient. Shows reference, display text, resource type, date, and sync status.

<CareContextList patientId={patientId} />

LinkingStatusBadge -- Color-coded badge for AbdmLinkRequestStatus. Green for completed, blue for in-progress, red for failed/expired.

<LinkingStatusBadge status="contexts_linked" />

Health Record ComponentsCopy Anchor Link

HealthRecordViewer -- Tabbed viewer for FHIR records. Groups records by resourceType with specialized sub-renderers:

FHIR records are typed as Record<string, unknown>[]. Safe extraction helpers handle missing/malformed fields.

<HealthRecordViewer records={fhirRecords} />

DataFetchStatus -- Progress stepper showing data transfer pipeline stages: requested -> acknowledged -> key_generated -> encrypting -> transferring -> completed. Shows timestamps, progress count, and error details with retry.

<DataFetchStatus transfer={dataTransfer} onRetry={handleRetry} />

Consent Management Components (Patient Detail)Copy Anchor Link

AbdmConsentsTabV2 -- Consent list with direction filter (All/HIP/HIU), table display, and actions (approve, deny, revoke for HIP consents).

ConsentRequestModalV2 -- Modal for creating new HIU consent requests with purpose, date range, HI types, and expiry.

ConsentDetailModalV2 -- Modal showing consent details with context-sensitive actions.

Real-Time EventsCopy Anchor Link

File: frontend/apps/cms/src/hooks/useAbdmRealtimeEvents.ts

Subscribes to the private-abdm-{facilityId} Ably channel (defined as CHANNEL_NAMES.ABDM in packages/api-client/src/services/realtime/types.ts).

// Activated in AbdmSectionV2 - active when ABDM tab is visible
useAbdmRealtimeEvents({ enabled: true })

The backend must broadcast to this channel when these entities change. Event payloads should include at minimum the entity ID and new status.

Patient Detail IntegrationCopy Anchor Link

File: frontend/apps/cms/src/features/patientDetail/components/AbdmSectionV2.tsx

The ABDM tab in PatientDetailPage renders AbdmSectionV2, which provides four sub-tabs:

The component also activates useAbdmRealtimeEvents for live cache updates.

Error HandlingCopy Anchor Link

ABHA errors use frontend/apps/cms/src/utils/abhaErrorHandler.ts which maps ABDM error codes to user-friendly messages via ABHA_ERROR_MAPPINGS. The isRetryableError helper identifies transient failures.

OTP flows show inline error alerts. Failed data transfers show error details from AbdmDataTransferDetailed.error_message with a retry button.

Background JobsCopy Anchor Link

All ABDM jobs are in domains/integration/jobs/abdm/ and inherit from Shared::ApplicationJob with Shared::Concerns::TenantAwareJob.

ProcessCallbackJobCopy Anchor Link

File: domains/integration/jobs/abdm/process_callback_job.rb Queue: abdm_callbacks Retries: 3 with exponential backoff

Enqueued by WebhookBaseController after logging an inbound callback. Loads the AbdmCallback record and delegates to CallbackProcessor for idempotent routing and execution.

Integration::Abdm::ProcessCallbackJob.perform_later(callback_id)

HipDataTransferJobCopy Anchor Link

File: domains/integration/jobs/abdm/hip_data_transfer_job.rb Queue: abdm Retries: 3 with exponential backoff

Enqueued by HipDataHandler when a data request webhook is received. Encrypts FHIR bundles and pushes them to the requesting HIU via DataTransferService. Skips processing if the transfer is already in a terminal state.

Integration::Abdm::HipDataTransferJob.perform_later(data_transfer_id)

HiuDataFetchJobCopy Anchor Link

File: domains/integration/jobs/abdm/hiu_data_fetch_job.rb Queue: abdm Retries: 3 with exponential backoff

Enqueued by HiuConsentHandler when a consent artefact is received. Requests health records from the source HIP via DataFetchService. Skips processing if the artefact is already fetched or erased.

Integration::Abdm::HiuDataFetchJob.perform_later(consent_artefact_id)

DataErasureJobCopy Anchor Link

File: domains/integration/jobs/abdm/data_erasure_job.rb Queue: abdm Schedule: Daily (via Sidekiq cron)

Periodic compliance job that erases health data when data_erase_at is reached. Processes three categories:

1. Consent artefacts: Erases fhir_records and care_contexts, sets fetch_status='erased'
2. Consents: Nulls consent_artifact JSONB on granted/revoked consents past erasure date
3. Care contexts: Nulls fhir_bundle JSONB on transferred/expired contexts linked to expired consents

Integration::Abdm::DataErasureJob.perform_later

Migration from LegacyCopy Anchor Link

The new ABDM integration under domains/integration/ replaces the legacy implementation in parts/abdm/. This section documents the key differences.

Structural ChangesCopy Anchor Link

Model ConsolidationCopy Anchor Link

Architecture ImprovementsCopy Anchor Link

Credential ConfigurationCopy Anchor Link

ABDM credentials are stored in Rails credentials under the abdm namespace:

abdm:
  client_id: "..."
  client_secret: "..."
  gateway_url: "https://dev.abdm.gov.in"     # or production URL
  cm_id: "sbx"                                # or production CM ID
  jwks_url: "https://dev.abdm.gov.in/gateway/v0.5/certs"
  fidelius_url: "http://localhost:8090"       # Fidelius sidecar URL

See AlsoCopy Anchor Link

• Schema Overview -- Full domain schema architecture
• Notification System -- How to send notifications from the integration domain
• Teleconsultation -- Another domain integration example