# Milestone One (M1) - ABHA & Identity Layer

**Context**\
Milestone One (M1) was the starting point of AMRIT’s ABDM integration. In this milestone, we built and validated the ABHA identity flows: creating and verifying ABHAs (Ayushman Bharat Health Accounts), mapping them to AMRIT beneficiaries, and implementing the sandbox’s required v0.5 OTP-based care context linking.

The implementation was delivered within AMRIT’s **FHIR-API module**, with persistence across **MySQL/Postgres** and **MongoDB**. OTP tracking and linking were also added for sandbox compliance.

### 1. Objectives of M1

* Register AMRIT facility and services in ABDM sandbox.
* Set up secure session management with ABDM Gateway.
* Implement ABHA creation & verification APIs (QR, Aadhaar-assisted, manual).
* Map ABHA ↔ AMRIT beneficiary records.
* Implement the v0.5 OTP flow for care context linking (for sandbox compliance).

### 2. Architecture & System Context

**Modules & Services**

* `HealthIDServiceImpl` → Implements ABHA creation & verification (methods like `ndhmGenerateOTP`, `ndhmCreateHealthID`, `ndhmVerifyHealthID`).
* `ABHAServiceImpl` → Orchestrates Aadhaar-assisted enrollment flows.
* `CareContextService` → Implements v0.5 OTP care-context linking (`generateOTPForCareContext`, `addCareContext`).

**Entities**

* `HealthIDResponse` → Maps to relational table `t_healthid`.
* `BenHealthIDMapping` → Handles beneficiary ↔ ABHA mapping (prevents duplicates).

**Tech stack**

* Spring Boot REST APIs
* Quartz scheduler (integrated here; extended in M2 for bundle generation)
* MySQL/Postgres (ABHA identities, link requests, OTP records)
* MongoDB (ABDM callbacks & sandbox payloads)
* Redis (introduced here for token caching; heavier usage in M2)

### 3. Sandbox Registration

* AMRIT facility registered in **HFR (Health Facility Registry)**.
* HIP and HIU IDs provisioned via sandbox portal.
* Sandbox credentials (`CLIENT_ID`, `CLIENT_SECRET`) stored in `common_ci.properties`.
* `X-CM-ID` set to `sbx` (sandbox).

### 4. Session Management

* API: `POST /sessions` → retrieves JWT session token (valid \~15 min).
* Tokens managed via `fire-api` module (automatic refresh + retry).
* Required headers in every call:
  * `Authorization: Bearer <session-token>`
  * `X-Request-ID: <uuid>`
  * `X-HIP-ID: <AMRIT_HIP_ID>`
  * `X-HIU-ID: <AMRIT_HIU_ID>`
  * `X-CM-ID: sbx`
  * `Content-Type: application/json`

### 5. ABHA Creation & Verification

**Implemented Flows**

* **QR Scan Flow**: Scan ABHA QR → verify via `/search` & `/verify`.
* **Manual Entry Flow**: Enter ABHA manually → verified.
* **Aadhaar-Assisted Flow**: Enter Aadhaar → ABDM generates ABHA → OTP verified.

**Service Mapping**

* `HealthIDServiceImpl` → OTP generation & creation APIs.
* `ABHAServiceImpl` → Aadhaar-assisted OTP flows.

**Transaction ID Usage**

* Each `/generateOtp`, `/verifyOtp`, `/createHealthID` call included a `txnId`.
* Persisted in `HealthIDResponse.txnId` to tie together multi-step flows.
* Provided auditability across retries and callbacks.

### 6. Database Entities

#### Relational (Postgres/MySQL)

* **`OtpRequests`** (otpservice schema)
  * Tracks OTP lifecycle (ABHA creation, OTP-based linking).
  * Key fields: `request_id`, `abha_number`, `otp_sent_to`, `status`, `created_at`.
* **`InitiatedLinkRequest`** (hipservice schema)
  * Tracks care-context link initiation in v0.5 OTP flow.
  * Fields: `request_id`, `txn_id`, `link_reference_number`, `status`, `created_at`.
* **`t_healthid`**
  * Stores ABHA profiles returned after verification.
  * Populated via `HealthIDResponse` entity.
* **`m_benhealthidmapping`**
  * Maps `beneficiaryRegId` ↔ `healthIdNumber`.
  * Prevents duplicate ABHA registrations.

#### MongoDB (AmritHRP)

* **`GenerateTokenAbdmResponses`**
  * Stores sandbox responses to `/generateToken` requests.
  * Includes link token, ABHA address, txnId.
* **`PatientCareContexts`**
  * Persists ABHA ↔ care-context mappings established via OTP linking.
* **`NDHMResponses`**
  * Stores raw sandbox callbacks for audit/debugging.

### 7. API Endpoints (FHIR-API)

* `/healthID/generateOTP`
* `/healthID/verifyOTPAndGenerateHealthID`
* `/healthID/getBenhealthID`
* `/healthID/getBenIdForhealthID`
* `/healthIDRecord/mapHealthIDToBeneficiary`
* `/healthIDRecord/addHealthIdRecord`

These were exposed via `HealthIDController` and implemented in `HealthIDServiceImpl`.

### 8. v0.5 OTP Care Context Linking

**Flow**

1. `CareContextService.generateOTPForCareContext()` → calls ABDM `/init`.
2. ABDM sends OTP → logged in `OtpRequests`.
3. User verifies OTP → `CareContextService.addCareContext()` attaches context.
4. ABDM confirms success → persisted in Mongo (`PatientCareContexts`).

**Example Init Callback**

```json
{
  "requestId": "uuid-123",
  "timestamp": "2025-09-22T10:00:00Z",
  "transactionId": "txn-12345",
  "abhaNumber": "ABHA-987654321000"
}

```

### 9. Error Handling & Edge Cases

* **Duplicate ABHA**: Prevented via `existsByHealthIdNumber`.
* **Existing ABHA**: Linked instead of recreated.
* **OTP Blocking**: Sandbox blocked after \~3 OTP/day → caching + retry logic.
* **TxnId persistence**: Always stored to avoid orphaned flows.
* **Callback failures**: Logged into `NDHMResponses` (Mongo) for replay/debug.

### 10. Repo / Service Mapping

* **Services**:
  * `HealthIDServiceImpl` → OTP, create, verify.
  * `ABHAServiceImpl` → Aadhaar-assisted flows.
  * `CareContextService` → OTP linking.
* **Entities**:
  * `HealthIDResponse` → table `t_healthid`.
  * `BenHealthIDMapping` → ABHA ↔ beneficiary mapping (`m_benhealthidmapping)`.
* **Modules**:
  * `fhir-api` → Gateway session management.
  * `otpservice` → OTP tracking (Postgres).
  * `hipservice` → Link initiation tracking (Postgres).
  * `AmritHRP` → ABDM responses, tokens, care contexts (Mongo).
  * `Redis` → caching of session/OTP data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://piramal-swasthya.gitbook.io/amrit/architecture/integrations/abdm-fhir-developer-intro/amrit-abdm-integration/milestone-one-m1-abha-and-identity-layer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.