orvo-abha Documentation

Welcome. This is the complete guide to orvo-abha — the backend service that connects the Orvo product family to India's ABDM (Ayushman Bharat Digital Mission) national health data network.

If you're non-technical: start with Architecture Overview — it explains what this service does and why, in plain language, before getting into any code-level detail.

If you're an engineer integrating against this service: the Integration Contract is the concrete guide for wiring up the main Orvo system (its database and API) to orvo-abha — identity mapping, which endpoints to call and when, ownership boundaries.

If you need the exact request/response shape of a specific endpoint or inbound ABDM callback: use the API reference below, or the interactive Swagger/OpenAPI UI (schema-only, no narrative — this guide is the narrative companion to it).

Contents

Start here

• Architecture Overview — what orvo-abha is, why it's a separate service, the ABDM actor glossary (HIP/HIU/PHR/HPR/CM), the module map, the data model, the runtime reliability patterns (sessions, gateway client, error mapping, idempotency), and the security model.
• Integration Contract — the concrete guide for connecting main Orvo's database/API to orvo-abha: identity linking, ownership boundaries, call sequences, realtime events, error-handling contract.
• Operations Guide — local setup, environment variables, testing, build/deployment (Docker/Compose/Bitbucket Pipelines), runtime internals, BridgeConfig secret rotation, and troubleshooting — the guide for actually running this service, not just reading its code.
• Health Locker Validation — the ABDM Health Locker lifecycle, a code-backed validation of orvo-abha and orvo-phr, identified gaps, required sandbox scenarios, and the remediation order.

API Reference (endpoints + inbound ABDM callbacks, with real examples)

• PHR App — the patient's own ABHA app experience: enrollment, login, profile, consent, records timeline (LHR), notifications, settings, health locker.
• HIP Identity & Linking — facility-side ABHA creation/lookup for walk-in patients, ABDM facility/provider directory search, and both HIP-initiated and patient-initiated care-context linking (plus their inbound callbacks).
• Patient Share & HPR — the scan-a-QR-at-reception flow, and the Healthcare Professional Registry (doctor registration, separate from patient ABHA).
• Consent & Health Data Exchange — the core of the system: consent lifecycle (request/grant/deny/revoke/expire), the actual encrypted FHIR record transfer between facilities, health-document upload, the normalized record timeline (LHR), and standing subscriptions.
• NHCX & Platform — insurance claims (eligibility/pre-auth/claims/payments), facility settings, operator reports, the notification bell, the realtime (Pusher) channel-resolution pattern, and operational logs.

Related

• PHR Realtime Events — event-by-event reference for the Pusher channel a PHR patient app subscribes to (superseded in general shape by the Realtime section of the NHCX & Platform doc, but kept for its per-event payload detail).
• ABDM Error Matrix — every ABDM error phrase pulled from its Swagger/Postman artifacts, grouped by area (auth, discovery/linking, consent, data transfer), with whether this codebase's normalizer already maps it.
• ABDM Error Coverage Checklist — the flat list of already-mapped vs. still-unmapped error phrases, for checking a specific one quickly.
• Swagger / OpenAPI UI — the machine-generated schema reference (request/response JSON Schema for every documented route), useful for client codegen or a quick field-level lookup once you already know which endpoint you need.

How to read the API reference docs

Every endpoint entry follows the same shape:

• METHOD /path and a one-line, plain-English description of what it's for.
• Who calls this — our own frontend (with which auth header/token) or the ABDM gateway itself calling back asynchronously (marked Inbound ABDM callback).
• A realistic example request, using real field names from the actual validation schema.
• A realistic example response.
• What triggers it and what happens next — since almost everything in this system is asynchronous, this is usually the most important part of each entry.

A recurring pattern worth internalizing before reading further: this backend plays both ABDM roles (HIP and HIU) depending on which facility/flow is involved, and almost every outbound call gets an immediate acknowledgement (202 Accepted) with the real result delivered later via a separate inbound callback. See Architecture Overview for why, and the Integration Contract for how to observe those async results without polling.