HTPI Patients Service

Patient management microservice for the HTPI healthcare platform. Handles all patient-related operations including demographics, contact information, and medical records.

Features

• Complete patient demographics management
• Medical Record Number (MRN) generation and validation
• Patient search and filtering
• Duplicate patient detection and merging
• Multi-tenant support with organization isolation
• Soft delete with audit trail
• Real-time event publishing

Architecture

The service communicates exclusively through NATS messaging:

• Receives patient operation requests
• Sends database requests to MongoDB service
• Publishes patient events for other services

NATS Topics

Request Topics

• patient.create - Create new patient
• patient.get - Get patient by ID or MRN
• patient.update - Update patient information
• patient.delete - Soft delete patient
• patient.list - List patients with pagination
• patient.search - Search patients
• patient.merge - Merge duplicate patients
• patient.stats - Get patient statistics

Event Topics Published

• patient.created - New patient created
• patient.updated - Patient information updated
• patient.deleted - Patient deleted
• patient.merged - Patients merged

Patient Model

Core Fields

• Identifiers: ID, MRN, SSN (encrypted)
• Demographics: Name, DOB, gender, marital status
• Contact: Email, phones, address
• Clinical: Blood type, allergies, medications, conditions
• Administrative: Status, provider, care team

Validation

• Email format validation
• Phone number formatting (E.164)
• State code validation (2 characters)
• Postal code validation (XXXXX or XXXXX-XXXX)
• SSN formatting (XXX-XX-XXXX)

API Examples

Create Patient

{
  "request_id": "req-123",
  "org_id": "org-456",
  "patient": {
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1980-01-15",
    "gender": "M",
    "email": "john.doe@example.com",
    "phone": "555-123-4567",
    "address": {
      "street1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701"
    }
  }
}

Search Patients

{
  "request_id": "req-124",
  "org_id": "org-456",
  "query": "john",
  "search_fields": ["first_name", "last_name", "email"],
  "page": 1,
  "page_size": 20
}

Get Patient Statistics

{
  "request_id": "req-125",
  "org_id": "org-456",
  "group_by": "status",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}

Environment Variables

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

# Service Configuration
LOG_LEVEL=INFO
ENVIRONMENT=production
PATIENT_ID_PREFIX=PAT

# Performance
MAX_CONCURRENT_REQUESTS=100
REQUEST_TIMEOUT=30

Deployment

Railway

railway up

Docker

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

Docker Compose

docker-compose up -d

Health Check

The service exposes health status via NATS:

• Topic: health.check or patients-service.health
• Returns: Service status, version, uptime

Multi-Tenancy

All operations are scoped by org_id:

• Patients are isolated by organization
• MRN uniqueness is per organization
• Email uniqueness is per organization

Data Privacy

• SSN should be encrypted before storage
• Soft deletes preserve audit trail
• PHI handling complies with HIPAA requirements