Piramal ↔ Prodigi EMR Lite Integration

1. Introduction

1.1 Purpose

This document describes the high-level design for integrating the Piramal application with Prodigi EMR Lite via its External Integration API. It covers the system architecture, key components, data flow, and integration interfaces. Detailed field mappings, schemas, and error handling will be covered in the Low-Level Design (LLD).

1.2 Scope

In Scope

• Authentication with Prodigi EMR Lite (login + token lifecycle).

• Pushing patient / visit / order data to Prodigi EMR Lite.

• Retrieving order results (X-ray + CAD, and TrueNat MTB family).

• Storing returned report assets (PDF / images).

Out of Scope

• Internal CAD processing logic of Prodigi EMR Lite (handled by the vendor).

• UI changes within Prodigi EMR Lite.

• Any non-order data exchange not described in the API contract.

2. System Overview

Piramal acts as the external integration client. It sends patient/visit/order data into Prodigi EMR Lite and later retrieves the diagnostic results. Prodigi EMR Lite performs the diagnostics (and internally triggers CAD for chest X-rays) and exposes results through its result API.

+------------------+        HTTPS / REST / JWT        +-------------------------+
|                  |  1. Login (get token)            |                         |
|     Piramal      | -------------------------------> |   Prodigi EMR Lite      |
|   Application    |  2. Push Order                   |   Integration API       |
|                  | -------------------------------> |                         |
|  (Integration    |  3. Get Result (polling)         |  - Patient/Visit/Order  |
|     Client)      | -------------------------------> |  - X-ray + CAD engine   |
|                  | <------------------------------- |  - TrueNat (MTB) engine |
+--------+---------+                                  +-------------------------+
         |
         | store report assets
         v
+------------------+
|   S3 / Object    |
|     Storage      |
+------------------+

3. Architecture

3.1 Key Components

3.2 Technology / Interface

• Protocol: HTTPS REST, JSON request/response.

• Auth: JWT Bearer token (Authorization: Bearer <accessToken>).

• Base path: /api/integrations/v1

• Common response envelope:

{
  "Result": "",
  "Data": {},
  "Message": ""
}

4. Integration Interfaces

4.1 Supported Order Types

• XRAY_CHEST

• MTB

• MTB_PLUS

• MTB_RIF

For XRAY_CHEST, Prodigi EMR Lite automatically runs CAD internally. Piramal does not create a separate CAD order; results are pulled using the original externalOrderId.

5. Data Flow

5.1 End-to-End Sequence

Piramal                         Prodigi EMR Lite
   |                                   |
   |---- POST /login/ ---------------->|
   |<--- accessToken, refreshToken ----|
   |                                   |
   |---- POST /orders/ (order data) -->|
   |<--- orderId, status=PENDING ------|
   |                                   |  (X-ray + CAD / TrueNat processing)
   |                                   |
   |---- POST /orders/result/ -------->|   <-- polling
   |<--- status=IN_PROGRESS -----------|
   |            ...                    |
   |---- POST /orders/result/ -------->|
   |<--- status=COMPLETED + assets ----|
   |                                   |
   | store assets in S3                |
   v                                   |

5.2 Order States

PENDING → IN_PROGRESS → COMPLETED (or FAILED)

5.3 Result Retrieval Strategy

Results are retrieved by polling the pull API (POST /orders/result/).

After an order is pushed, the Result Ingestion Service periodically polls using the original externalOrderId until the status reaches COMPLETED or FAILED. A configurable polling interval with back-off is applied to limit load on both systems and to avoid unnecessary calls while an order is still PENDING/IN_PROGRESS.

A vendor-initiated push (webhook) is not used: the Piramal app runs as a local/on-prem server at the CSMP location, behind NAT/firewall with no public inbound endpoint, so Prodigi cannot call into it. Polling keeps the connection initiated outward from Piramal, which works through the firewall.

6. Asset / Report Storage

Results may include assets (report PDFs, secondary-capture images). The contract currently returns these as inline base64 (includeAssets: "base64").

Design decision: Piramal will store assets in S3 / object storage, keeping only references (URLs/keys) in the database rather than large base64 blobs.

Preferred enhancement: The API returns a downloadable / pre-signed URL per asset so files can be streamed directly to S3 without DB bloat.

7. Non-Functional Considerations

8. Assumptions & Dependencies

• Prodigi EMR Lite exposes a stable base URL per environment (test / prod).

• Credentials for the integration client are provisioned by the vendor.

• Network connectivity / IP allow-listing is in place between systems.

• S3 (or equivalent) is available on the Piramal side for asset storage.

9. Open Questions / Clarifications Pending from Vendor

1. Refresh Token API – No documented endpoint to exchange refreshToken for a new accessToken. Need spec (path, request/response).

2. Order type handling – Does each orderType need a separate order, or can multiple types share one order/visit? For a visit needing both X-ray and TrueNat, one order or two?

3. includeAssets behavior – With "base64", are all assets always returned inline? With "none", is it metadata-only or no assets array at all?

4. Asset storage – Can the API return a downloadable/pre-signed URL per asset (instead of/along with base64) to support direct S3 storage?

10. Open Items / To Be Detailed in LLD

• Exact field-level mapping (Piramal ↔ Prodigi payloads).

• Polling interval and retry/back-off policy.

• Detailed error codes and handling matrix.

• Database schema for order mapping and asset references.