devsofttech_hms_ci4/docs/ABDM_GATEWAY_ARCHITECTURE.md

ABDM Integration Architecture - With Middleware Gateway

Date: May 12, 2026
Setup: Two Gateway Options (CSNOtk vs Custom)

---

🏗️ System Architecture

┌─────────────────┐
│   HMS CI4       │
│  (PHP/CI4)      │
└────────┬────────┘
         │
         │ ABDM API Calls
         │
         ▼
    ┌────────────────────────────────────┐
    │  Middleware Gateway (Node.js)      │
    │  https://abdm-bridge.e-atria.in    │
    │  (Your Custom Gateway)             │
    └────────┬───────────┬─────┬─────────┘
             │           │     │
    ┌────────▼─┐  ┌──────▼──┐  │
    │  ABDM    │  │ SNOMED  │  │ (Alternative: CSNOtk Public)
    │ M3 API   │  │ Service │  │
    └──────────┘  └─────────┘  │
                                 │
                    ┌────────────▼────────────┐
                    │  CSNOtk Public Gateway  │
                    │  (csnotk.e-atria.in)    │
                    │  (Fallback Option)      │
                    └─────────────────────────┘

---

🔀 Two Gateway Options

Option 1: CSNOtk Public Gateway (Current - No Setup Needed)

HMS → CSNOtk Gateway → ABDM M3 API

Pros:

• ✅ No infrastructure setup required
• ✅ Pre-configured and stable
• ✅ Shared bearer token approach

Cons:

• ❌ Shared infrastructure (potential bottleneck)
• ❌ No audit trail for your organization
• ❌ Limited customization
• ❌ Vendor dependency

Configuration:

BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge

---

Option 2: Custom Middleware Gateway (New - Recommended for Production)

HMS → Your Gateway (abdm-bridge.e-atria.in) → ABDM M3 API
                              ↓
                        Your Infrastructure

Pros:

• ✅ Full control and customization
• ✅ Detailed logging and audit trail
• ✅ Custom rate limiting per client
• ✅ Advanced monitoring and alerting
• ✅ Dedicated infrastructure
• ✅ Better performance for your use case
• ✅ Future extensibility

Cons:

• ⚠️ Requires Ubuntu server setup
• ⚠️ Ongoing maintenance responsibility
• ⚠️ SSL certificate renewal

Configuration:

BRIDGE_SYNC_URL = https://abdm-bridge.e-atria.in/api/v3

---

📋 Comparison Matrix

Feature	CSNOtk Public	Your Gateway
Setup Time	5 min (edit .env)	15 min (deploy script)
Audit Trail	Limited	Full audit logs
Rate Limiting	Global	Per-HMS instance
Performance	Shared	Dedicated
Monitoring	By CSNOtk	Full control
Customization	No	Full Node.js code
Cost	Included	Server cost only
SLA	Vendor SLA	Your responsibility
Latency	Depends on CSNOtk	Depends on your server

---

🎯 Recommendation

Use Your Gateway (Option 2) if:

• ✅ Production deployment planned
• ✅ High transaction volume expected
• ✅ Compliance/audit trail required
• ✅ Want full control over integration
• ✅ Planning to scale beyond sandbox

Use CSNOtk Public (Option 1) if:

• ✅ Testing/sandbox only
• ✅ Low transaction volume
• ✅ Want zero infrastructure setup
• ✅ Short-term PoC

---

🚀 Deployment Scenarios

Scenario 1: Quick Testing (This Week)

Step 1: Keep CSNOtk gateway
Step 2: Test OPD consult → SNOMED → ABHA → Consent
Step 3: Run full 7-step test sequence
Status: Fastest path to validation

Scenario 2: Prepare for Production

Step 1: Deploy your gateway to Ubuntu server
        - Use deploy.sh for automation
        - Takes ~15 minutes
Step 2: Configure HMS to use your gateway
        - Edit .env: BRIDGE_SYNC_URL
Step 3: Run full test sequence again
Step 4: Monitor logs and performance
Status: Ready for production deployment

Scenario 3: Hybrid (Recommended)

Phase 1 (Week 1):
  - Use CSNOtk for immediate testing
  - Complete 7-step validation
  
Phase 2 (Week 2):
  - Deploy your gateway in parallel
  - Run alongside CSNOtk
  
Phase 3 (Week 3):
  - Switch to your gateway
  - Keep CSNOtk as fallback
  
Phase 4 (Month 2+):
  - Production operations
  - Retire CSNOtk if desired

---

🔧 Switching Between Gateways

From CSNOtk to Your Gateway

Step 1: Gateway already deployed at abdm-bridge.e-atria.in

Step 2: Update HMS .env

# Before
BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge

# After
BRIDGE_SYNC_URL = https://abdm-bridge.e-atria.in/api/v3

Step 3: Restart HMS

# If using Docker
docker-compose restart hms-app

# Or PHP-FPM
sudo systemctl restart php-fpm

Step 4: Verify

# Test health
curl https://abdm-bridge.e-atria.in/api/v3/health

# Test OPD save
# Should work without any HMS code changes

---

📊 Request Flow Comparison

Using CSNOtk Gateway

HMS
  └─ POST /api/v3/abha/validate
      └─ BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge
          └─ CSNOtk Gateway
              └─ ABDM M3 API
                  └─ Returns response

Using Your Gateway

HMS
  └─ POST /api/v3/abha/validate
      └─ BRIDGE_SYNC_URL = https://abdm-bridge.e-atria.in/api/v3
          └─ Your Node.js Gateway
              └─ ABDM M3 API
                  └─ Returns response
              └─ Logs request to /logs/combined.log
              └─ Tracks metrics (response time, errors)

---

🛠️ Your Gateway Capabilities

Once deployed, your gateway provides:

1. Request/Response Logging

# Every API call logged with:
# - Request ID
# - Timestamp
# - Authorization status
# - Response time
# - Error details (if any)

sudo docker logs -f abdm-bridge-gateway | grep "ABHA validation"

2. Performance Monitoring

# Response times for each endpoint
docker stats abdm-bridge-gateway

# Memory usage
free -h

3. Custom Metrics

• Total requests per hour
• ABHA validations succeeded/failed
• Average response time
• Error rates by endpoint

4. Security Features

• Rate limiting (100 req/15min per IP)
• Bearer token authentication
• Request ID tracking
• SSL/TLS encryption
• CORS policy

5. Future Extensibility

• Add JWT token support
• Implement caching layer
• Add request signing
• Custom consent workflows
• FHIR bundle transformation

---

📈 Performance Expectations

CSNOtk Gateway

• Avg Response Time: 500-1000ms
• Rate Limit: Shared with all users
• Latency: Depends on CSNOtk load

Your Gateway (Dedicated Server)

• Avg Response Time: 100-300ms (faster)
• Rate Limit: 100 per 15 min (per HMS instance)
• Latency: Controlled infrastructure

---

🔐 Security Considerations

Token Management

CSNOtk:     Shared bearer token
            └─ Single point of failure
            └─ Limited audit trail

Your Gateway: Individual tokens per service
             └─ Rotate quarterly
             └─ Full audit trail
             └─ Can revoke per-HMS

Audit Trail

CSNOtk:     Minimal logging
            └─ No visibility into errors
            └─ Compliance unclear

Your Gateway: Complete logging
             └─ Every request tracked
             └─ Full error details
             └─ Compliance-ready

---

💰 Cost Comparison

CSNOtk Public (Option 1)

• Server Cost: $0 (shared)
• Maintenance: Vendor responsibility
• Setup Time: 5 min
• Annual Cost: $0

Your Gateway (Option 2)

• Server Cost: $10-50/month (Ubuntu VPS)
• Maintenance: Your responsibility
• Setup Time: 15 min (automated)
• Annual Cost: $120-600

ROI: Worth it for production; skip for PoC

---

🎓 Implementation Roadmap

Week 1: Testing Phase
├─ Use CSNOtk gateway
├─ Complete 7-step test sequence
└─ Validate ABDM integration works

Week 2: Production Prep
├─ Deploy your gateway (15 min)
├─ Test both gateways in parallel
├─ Verify identical responses
└─ Performance benchmark

Week 3: Migration
├─ Switch to your gateway
├─ Keep CSNOtk as fallback
├─ Monitor for issues
└─ Document any differences

Week 4+: Production
├─ Run on your gateway only
├─ Setup monitoring/alerting
├─ Prepare disaster recovery
└─ Plan scaling strategy

---

✅ Decision Matrix

Quick Decision Tree

Question 1: Is this production?
├─ YES  → Deploy your gateway → Option 2
└─ NO   → Continue with CSNOtk → Option 1

Question 2: High transaction volume expected?
├─ YES (>1000/day) → Your gateway → Option 2
└─ NO  (<1000/day) → CSNOtk OK   → Option 1

Question 3: Compliance/audit requirements?
├─ YES → Must have your gateway → Option 2
└─ NO  → CSNOtk sufficient       → Option 1

Question 4: Budget for infrastructure?
├─ YES → Deploy your gateway → Option 2
└─ NO  → Use CSNOtk for now  → Option 1

---

📞 Making the Switch

If You Decide to Deploy Your Gateway Later

1. Create Ubuntu Server

   VPS provider: DigitalOcean, Linode, AWS, etc.
   OS: Ubuntu 20.04+ 
   Size: 1GB RAM, 25GB SSD
   

2. Copy Files

   scp -r middleware-gateway/ root@SERVER_IP:/opt/
   

3. Run Deploy Script

   ssh root@SERVER_IP
   cd /opt/middleware-gateway
   sudo ./deploy.sh
   

4. Update HMS .env

   BRIDGE_SYNC_URL = https://abdm-bridge.e-atria.in/api/v3
   

5. Restart HMS & Test Done! Fully automatic upgrade path.

---

🎯 Recommendation for Your Project

Current Status: May 12, 2026

• ✅ ABDM credentials ready (SBXID_033661)
• ✅ OPD form ABDM-compliant
• ✅ CSNOtk gateway accessible
• ✅ Your gateway code ready to deploy

Immediate Next (This Week)

Use CSNOtk Gateway:
1. Quick testing of OPD → ABDM flow
2. Validate SNOMED integration
3. Complete 7-step test sequence
Duration: 2-3 days

Future (Production Ready)

Deploy Your Gateway:
1. Use automated deploy.sh
2. Takes 15 minutes
3. Seamless switch for HMS
4. Full control + audit trail
Recommended: Before live usage

---

Status: 🟢 Both options ready
Quick Start: CSNOtk (no setup)
Production Ready: Your Gateway (15 min setup)
Recommendation: Start with CSNOtk, upgrade to your gateway in Week 2

---

📚 Next Steps

1. This Week: Use CSNOtk, run tests, validate ABDM integration
2. Next Week: Review this document, decide on production path
3. Before Go-Live: Deploy your gateway using deploy.sh
4. Post-Go-Live: Monitor, optimize, scale as needed

---

Questions? Reference the detailed guides:

• Quick Start: docs/ABDM_QUICK_START.md
• Full Deployment: middleware-gateway/DEPLOYMENT_GUIDE.md
• Custom Gateway: middleware-gateway/README.md