devsofttech_hms_ci4/ACTION_PLAN_DUAL_BRIDGE.md

ABDM Integration Summary & Action Plan (May 13, 2026)

Clarification Received

The user corrected a critical misunderstanding:

✅ What Was Clarified

There are TWO separate, equally important bridges in the HMS ABDM architecture:

1. CSNOtk Bridge (https://csnotk.e-atria.in/api/bridge)

• Primary Purpose: Terminology validation & FHIR formatting
• Function: Receives medical terms (fever, cough, etc.) → validates against SNOMED CT → returns FHIR-coded data
• Use Case: When HMS needs to ensure medical terminology is standardized per SNOMED CT
• Event Types: snomed.diagnosis.validate, snomed.medication.validate
• Data Source: SnomedCT_InternationalRF2_PRODUCTION_20260501T120000Z (SNOMED CT International Release Files)
• Documentation: CSNOtk_API_v9.0/ folder + docs/CSNOTK_API_REFERENCE.md

2. ABDM Bridge (https://abdm-bridge.e-atria.in/api/v1/bridge)

• Primary Purpose: ABDM M1 communication (patient health record sharing)
• Function: Centralized gateway for multiple HMS installations to submit/retrieve data from ABDM Live/Sandbox
• Use Case: When HMS needs to share patient records with ABDM (e.g., OPD prescriptions, lab reports, consent management)
• Event Types: abdm.abha.validate, abdm.fhir.share.requested, abdm.consent.requested, etc.
• Architecture: Multiple HMS instances (deployed at client sites) → Single ABDM Bridge → ABDM M1 servers
• Benefit: Centralized token management, compliance, audit trail

---

What Was WRONG (and Corrected)

❌ Previous Understanding

• Assumed we should replace CSNOtk with ABDM Bridge
• Thought both bridges did the same thing (ABDM communication)

✅ Corrected Understanding

• Both bridges must coexist
• They serve fundamentally different purposes
• Event routing logic needed to distinguish them

---

Current State

Documentation Created

• ✅ DUAL_BRIDGE_ARCHITECTURE.md - Full architecture explanation
• ✅ ABDM_GATEWAY_PHP_DEPLOYMENT.md - PHP gateway deployment steps
• ✅ BRIDGE_SYNC_SERVICE_IMPLEMENTATION.md - Code implementation guide
• ✅ .copilot-instructions - System prompt (auto-loaded for workspace)

Configuration Status

BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge  # ✅ CORRECT (keep as is)
BRIDGE_SYNC_TOKEN =                                      # ⏳ Needs value
ABDM_BRIDGE_URL = https://abdm-bridge.e-atria.in/api/v1/bridge  # ⏳ Needs to be added
ABDM_BRIDGE_TOKEN =                                      # ⏳ Needs value
BRIDGE_SOURCE_CODE = SBXID_033661                        # ✅ CORRECT

Code Status

• ✅ CsnotkTerminologyService exists (direct REST API integration for autocomplete)
• ✅ BridgeSyncService exists (core queue processing)
• ❌ BridgeSyncService routing logic NOT YET updated for dual-bridge support
  • Need: Conditional routing by event_type prefix (snomed.* vs abdm.*)

---

Immediate Action Items (In Order)

Phase 1: Configuration (No Code Changes)

Task 1.1: Generate TWO bearer tokens

# Token for CSNOtk Bridge
openssl rand -hex 32
# Result: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

# Token for ABDM Bridge
openssl rand -hex 32
# Result: f2e1d0c9b8a7z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1

Task 1.2: Update HMS .env

# Keep existing (no change)
BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge
BRIDGE_SYNC_TOKEN = a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

# Add new config keys
ABDM_BRIDGE_URL = https://abdm-bridge.e-atria.in/api/v1/bridge
ABDM_BRIDGE_TOKEN = f2e1d0c9b8a7z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1

---

Phase 2: Code Implementation

Task 2.1: Update app/Libraries/BridgeSyncService.php

• Modify buildDispatchContext() to route by event_type prefix
• Rename buildBridgeDispatchContext() → buildCsnotkDispatchContext()
• Add new buildAbdmDispatchContext() method
• Reference: BRIDGE_SYNC_SERVICE_IMPLEMENTATION.md

Task 2.2: Update app/Config/AbdmConnector.php

• Add two new config keys for ABDM bridge:

  public string $abdmBridgeUrl = 'https://abdm-bridge.e-atria.in/api/v1/bridge';
  public string $abdmBridgeToken = '';
  

Task 2.3: Testing & Validation

• Queue test snomed.diagnosis.validate event
• Queue test abdm.abha.validate event
• Verify they route to correct endpoints
• Check abdm_api_logs.channel is 'csnotk' or 'abdm' respectively

---

Phase 3: Deployment

Task 3.1: Deploy PHP ABDM Gateway

• Copy gateway-php-ci4/ to server /opt/abdm-gateway
• Run composer install
• Configure .env with:
  • MySQL credentials
  • GATEWAY_BEARER_TOKEN = HMS ABDM_BRIDGE_TOKEN
  • ABDM M1 credentials
• Run migrations
• Configure Apache/SSL
• Reference: ABDM_GATEWAY_PHP_DEPLOYMENT.md

Task 3.2: Test End-to-End

cd /opt/hms-ci4
php spark bridge:sync --limit 10

# Should show both CSNOTK and ABDM events processed

---

Deliverables Created (For User Reference)

Documentation Files

1. DUAL_BRIDGE_ARCHITECTURE.md

   • Complete architecture overview
   • Event routing table
   • Configuration requirements
   • CSNOtk vs ABDM contract details
   • Database schema implications

2. BRIDGE_SYNC_SERVICE_IMPLEMENTATION.md

   • Exact code changes needed (with line numbers)
   • Step-by-step implementation guide
   • Testing procedures
   • Code review checklist

3. ABDM_GATEWAY_PHP_DEPLOYMENT.md

   • 10-step server deployment
   • Configuration template
   • Health check & smoke tests
   • Troubleshooting guide
   • Rollback procedures

4. .copilot-instructions

   • System prompt loaded automatically for this workspace
   • Captures critical architecture requirements
   • Prevents future confusion

Memory Files

• /memories/session/php-gateway-architecture.md - Session working notes (auto-populated)

---

FAQ (From User Clarifications)

Q: Why are there TWO bridges? A: CSNOtk handles terminology (SNOMED CT coding), ABDM handles patient data sharing. They're separate concerns.

Q: What's the advantage of centralized ABDM Bridge? A: Multiple HMS instances at different client sites all connect through one ABDM Bridge for:

• Centralized token management
• Audit trail consolidation
• Simplified client deployment

Q: Can CSNOtk events bypass the bridge? A: Yes, CsnotkTerminologyService calls CSNOtk REST API directly (/rest/search/suggest) for autocomplete. The bridge is used for formal event processing.

Q: Focus on M1 first? A: Yes, ABDM M1 is the priority. M2 (privacy) and M3 (interoperability) can be added later.

---

Next Steps

1. Generate bearer tokens (Task 1.1)
2. Update HMS .env (Task 1.2)
3. Implement BridgeSyncService routing (Task 2.1-2.3)
4. Test both event types (Task 2.3)
5. Deploy PHP gateway (Task 3.1)
6. Run end-to-end test (Task 3.2)

---

Questions for User (Before Implementation)

1. Should we prioritize CSNOtk bridge testing first, or ABDM bridge?
2. Are there existing test events in bridge_sync_queue to use for routing validation?
3. Should legacy event types (no prefix) still route to CSNOtk as fallback?
4. Is the PHP gateway already accessible at https://abdm-bridge.e-atria.in, or does it need to be deployed?

---

Architecture Diagram (ASCII)

                       HMS CI4 (Main Application)
                               |
                    BridgeSyncService.processPending()
                      (Routes by event_type)
                               |
                    ___________|___________
                   |                       |
            snomed.* events         abdm.* events
                   |                       |
        [CSNOtk Bridge]          [ABDM Bridge]
             v                         v
    /api/bridge                   /api/v1/bridge
(CSNOtk Terminology)      (PHP Gateway at e-atria.in)
             v                         v
   SNOMED CT Database         (/api/v3/* handlers)
   (Validate & Code)                  v
             v                   ABDM M1 Server
  Return SNOMED-coded        (Live/Sandbox)
    FHIR Format                       
             |                         |
             └─────────────────────────┘
                        |
              [Patient Health Data]

---

Status: Architecture clarified, documentation created, awaiting implementation.