HTPI MongoDB Service

Central database service for the HTPI healthcare platform. All microservices communicate with MongoDB through this service via NATS messaging.

Overview

This service provides:

• Centralized database operations via NATS
• Multi-tenant data isolation
• Automatic audit logging
• Soft delete functionality
• Connection pooling and optimization
• Index management

Architecture

┌─────────────────┐     NATS Messages      ┌──────────────────┐
│   Microservice  │ ─────────────────────▶ │  MongoDB Service │
│  (Patient, etc) │ ◀───────────────────── │                  │
└─────────────────┘    Response/Events     └────────┬─────────┘
                                                     │
                                                     ▼
                                            ┌──────────────────┐
                                            │     MongoDB      │
                                            └──────────────────┘

NATS Topics

Request Topics

• db.request.{operation} - Database operation requests

Response Topics

Responses are sent back to the requesting service's reply topic.

Supported Operations

• insert - Insert single document
• insert_many - Insert multiple documents
• find - Find documents with filtering, sorting, pagination
• find_one - Find single document
• update - Update single document
• update_many - Update multiple documents
• delete - Soft delete single document
• delete_many - Soft delete multiple documents
• count - Count documents
• aggregate - Run aggregation pipeline
• create_index - Create collection index

Message Format

Request Format

{
  "request_id": "unique-request-id",
  "org_id": "organization-id",
  "collection": "collection-name",
  "operation": "operation-type",
  "document": {...},  // For insert
  "filter": {...},    // For find/update/delete
  "update": {...},    // For update operations
  "projection": {...}, // For find operations
  "sort": [...],      // For find operations
  "limit": 10,        // For find operations
  "skip": 0           // For find operations
}

Response Format

{
  "success": true,
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "request_id": "unique-request-id",
    "success": true,
    "inserted_id": "document-id",  // For insert
    "documents": [...],            // For find
    "count": 10,                   // For count/find
    "matched_count": 1,            // For update
    "modified_count": 1,           // For update
    "deleted_count": 1             // For delete
  }
}

Collections

Automatically Created Indexes

Patients Collection

• org_id + _id - Compound index for multi-tenant queries
• org_id + email - Unique email per organization
• org_id + mrn - Unique MRN per organization
• org_id + deleted_at - Soft delete queries
• Text index for full-text search

Insurance Collection

• org_id + _id - Compound index
• org_id + patient_id - Patient insurance queries
• org_id + policy_number - Policy lookups
• org_id + deleted_at - Soft delete queries

Forms Collection

• org_id + _id - Compound index
• org_id + patient_id - Patient forms queries
• org_id + status - Status filtering
• org_id + created_at - Date sorting
• org_id + deleted_at - Soft delete queries

Claims Collection

• org_id + _id - Compound index
• org_id + form_id - Form claims queries
• org_id + claimmd_id - ClaimMD tracking (unique)
• org_id + status - Status filtering
• org_id + created_at - Date sorting

Multi-Tenancy

All operations are automatically filtered by org_id to ensure complete data isolation between organizations. The service:

• Adds org_id to all insert operations
• Includes org_id in all query filters
• Prevents cross-organization data access

Environment Variables

# NATS Configuration
NATS_URL=nats://localhost:4222
NATS_USER=mongodb_service
NATS_PASS=secure_password

# MongoDB Configuration
MONGO_URL=mongodb://localhost:27017
MONGO_DB_NAME=htpi
MONGO_TIMEOUT_MS=5000
MONGO_MAX_POOL_SIZE=100
MONGO_MIN_POOL_SIZE=10

# Service Configuration
LOG_LEVEL=INFO
ENABLE_METRICS=true
METRICS_PORT=9093

Usage Examples

Insert Patient

// NATS message to db.request.insert
{
  "request_id": "req-123",
  "org_id": "org-456",
  "collection": "patients",
  "operation": "insert",
  "document": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "mrn": "MRN-12345"
  }
}

Find Patients

// NATS message to db.request.find
{
  "request_id": "req-124",
  "org_id": "org-456",
  "collection": "patients",
  "operation": "find",
  "filter": {
    "status": "active",
    "deleted_at": null
  },
  "sort": [["created_at", -1]],
  "limit": 20,
  "skip": 0
}

Update Patient

// NATS message to db.request.update
{
  "request_id": "req-125",
  "org_id": "org-456",
  "collection": "patients",
  "operation": "update",
  "filter": {
    "_id": "patient-id"
  },
  "update": {
    "$set": {
      "phone": "555-1234",
      "address": "123 Main St"
    }
  }
}

Deployment

Railway

railway up

Docker

docker build -t htpi-mongodb-service .
docker run -e NATS_URL=nats://host:4222 -e MONGO_URL=mongodb://host:27017 htpi-mongodb-service

Docker Compose

docker-compose up -d

Health Check

The service exposes health status via NATS:

• Topic: health.check or mongodb-service.health
• Returns: Service status, version, uptime, and database connectivity