HH/docs/ARCHITECTURE.md

PX360 System Architecture

Overview

PX360 is an enterprise-grade patient experience management system built for AlHammadi Group (Saudi Arabia). It implements a sophisticated event-driven architecture to track patient journeys, collect feedback, manage complaints, and drive continuous improvement.

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                     External Systems                         │
│  (HIS, Lab, Radiology, Pharmacy, MOH, CHI)                  │
└────────────────────┬────────────────────────────────────────┘
                     │ Integration Events
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                  PX360 API Gateway                           │
│              POST /api/integrations/events/                  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                   Event Queue (Redis)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│              Celery Workers (Event Processing)               │
│  • Process events                                            │
│  • Complete journey stages                                   │
│  • Trigger surveys                                           │
│  • Create actions                                            │
│  • Check SLAs                                                │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                PostgreSQL Database                           │
│  • Journeys & Stages                                         │
│  • Surveys & Responses                                       │
│  • Complaints & Actions                                      │
│  • Organizations & Users                                     │
│  • Audit Logs                                                │
└─────────────────────────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                  Notification Services                       │
│              (SMS, WhatsApp, Email)                          │
└─────────────────────────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                      Patients                                │
│              (Receive & Complete Surveys)                    │
└─────────────────────────────────────────────────────────────┘

Technology Stack

Backend

• Framework: Django 5.0
• API: Django REST Framework
• Authentication: JWT (SimpleJWT)
• Database: PostgreSQL 15
• Task Queue: Celery 5.3
• Message Broker: Redis 7
• Scheduler: Celery Beat

Frontend (Planned)

• Framework: Bootstrap 5
• Interactivity: HTMX
• Charts: Chart.js / ApexCharts
• Tables: DataTables
• Selects: Select2

DevOps

• Containerization: Docker + Docker Compose
• WSGI Server: Gunicorn
• Static Files: WhiteNoise
• Environment: django-environ

Development

• Testing: pytest-django
• Linting: ruff
• Documentation: drf-spectacular (OpenAPI)

Application Architecture

Modular App Structure

apps/
├── core/              # Base models, utilities, audit logging
├── accounts/          # User authentication, RBAC
├── organizations/     # Hospitals, departments, staff, patients
├── journeys/          # Patient journey tracking
├── surveys/           # Survey templates & responses
├── complaints/        # Complaint management
├── feedback/          # General feedback
├── callcenter/        # Call center interactions
├── social/            # Social media monitoring
├── px_action_center/  # Action tracking with SLA
├── analytics/         # KPIs and dashboards
├── physicians/        # Physician ratings
├── projects/          # QI projects
├── integrations/      # External system integrations
├── notifications/     # Multi-channel notifications
└── ai_engine/         # Sentiment analysis

Design Patterns

1. Base Models Pattern

All business models inherit from:

• UUIDModel - UUID primary keys
• TimeStampedModel - Auto timestamps
• SoftDeleteModel - Soft delete capability

2. Service Layer Pattern

Business logic encapsulated in service classes:

• AuditService - Centralized audit logging
• NotificationService - Multi-channel notifications (Phase 4)
• SLAService - SLA calculation and escalation (Phase 6)

3. Event-Driven Pattern

• Integration events trigger stage completions
• Stage completions trigger survey creation
• Negative surveys trigger action creation
• Overdue actions trigger escalations

4. Repository Pattern

• ViewSets act as repositories
• Querysets optimized with select_related/prefetch_related
• Role-based filtering in get_queryset()

Data Model

Core Entities

Organizations

Hospital (1) ──→ (N) Department
Hospital (1) ──→ (N) Physician
Hospital (1) ──→ (N) Employee
Hospital (1) ──→ (N) Patient
Department (1) ──→ (N) User (manager)

Journeys

Hospital (1) ──→ (N) JourneyTemplate
JourneyTemplate (1) ──→ (N) StageTemplate
StageTemplate (1) ──→ (1) SurveyTemplate

Patient (1) ──→ (N) JourneyInstance
JourneyTemplate (1) ──→ (N) JourneyInstance
JourneyInstance (1) ──→ (N) StageInstance
StageTemplate (1) ──→ (N) StageInstance
InboundEvent (1) ──→ (N) StageInstance (completed_by_event)

Surveys (Phase 4)

Hospital (1) ──→ (N) SurveyTemplate
SurveyTemplate (1) ──→ (N) SurveyQuestion
Patient (1) ──→ (N) SurveyInstance
SurveyTemplate (1) ──→ (N) SurveyInstance
SurveyInstance (1) ──→ (N) SurveyResponse

Complaints (Phase 5)

Patient (1) ──→ (N) Complaint
Hospital (1) ──→ (N) Complaint
Department (1) ──→ (N) Complaint
Complaint (1) ──→ (N) ComplaintUpdate
Complaint (1) ──→ (N) ComplaintAttachment

Actions (Phase 6)

Hospital (1) ──→ (N) PXAction
Department (1) ──→ (N) PXAction
User (1) ──→ (N) PXAction (assigned_to)
PXAction (1) ──→ (N) PXActionLog
PXAction (1) ──→ (N) PXActionAttachment

Security Architecture

Authentication & Authorization

Authentication Layers

1. JWT Tokens - For web/mobile clients
2. API Keys - For external system integrations (TODO)
3. Session Auth - For Django admin

Authorization (RBAC)

Role Hierarchy:

Level 100: PX Admin          → Full system access
Level 80:  Hospital Admin    → Hospital-level access
Level 60:  Department Manager → Department-level access
Level 50:  PX Coordinator    → Action/complaint management
Level 40:  Physician         → View feedback & ratings
Level 30:  Nurse             → View department feedback
Level 20:  Staff             → Basic access
Level 10:  Viewer            → Read-only access

Permission Classes:

• IsPXAdmin - Full access
• IsHospitalAdmin - Hospital-level access
• IsDepartmentManager - Department-level access
• CanAccessHospitalData - Object-level hospital access
• CanAccessDepartmentData - Object-level department access
• IsOwnerOrPXAdmin - Own data or admin access

Data Security

At Rest

• PostgreSQL encryption (TDE recommended)
• Encrypted backups
• Secure credential storage

In Transit

• HTTPS/TLS 1.3
• JWT token encryption
• API payload encryption (sensitive data)

Audit Trail

• All critical operations logged
• User actions tracked
• IP address and user agent recorded
• Immutable audit logs

Integration Architecture

Inbound Integrations

Supported Systems

1. HIS - Hospital Information System
2. Lab - Laboratory Information System
3. Radiology - PACS/RIS
4. Pharmacy - Pharmacy Management System
5. MOH - Ministry of Health (TODO: stub)
6. CHI - Council of Health Insurance (TODO: stub)

Integration Pattern

External System
    ↓ (HTTP POST)
API Endpoint (/api/integrations/events/)
    ↓ (Store)
InboundEvent (DB)
    ↓ (Queue)
Celery Task (process_inbound_event)
    ↓ (Process)
Journey Stage Completion
    ↓ (Trigger)
Survey Creation & Delivery

Event Contract

{
  "source_system": "his|lab|radiology|pharmacy",
  "event_code": "EVENT_CODE",
  "encounter_id": "UNIQUE_ID",
  "patient_identifier": "MRN",
  "payload_json": {
    "physician_license": "PHY001",
    "department_code": "DEPT_CODE",
    "timestamp": "ISO8601",
    "custom_fields": {}
  }
}

Outbound Integrations (Phase 4)

Notification Channels

1. SMS - Twilio/local provider
2. WhatsApp - WhatsApp Business API
3. Email - SMTP/SendGrid

Future Integrations

• MOH reporting
• CHI claims integration
• Social media APIs (Twitter, Facebook, Instagram)

Scalability Architecture

Horizontal Scaling

Web Tier

• Multiple Gunicorn workers
• Load balancer (Nginx/HAProxy)
• Stateless design (JWT tokens)

Worker Tier

• Multiple Celery workers
• Task routing by queue
• Auto-scaling based on queue length

Database Tier

• PostgreSQL replication (master-slave)
• Read replicas for reporting
• Connection pooling (PgBouncer)

Caching Strategy (Future)

Redis Caching

• User sessions
• API responses (short TTL)
• Dashboard metrics (5-minute cache)
• Lookup data (hospitals, departments)

Database Optimization

• Indexes on all filter fields
• Materialized views for analytics
• Partitioning for large tables (audit logs, events)

Monitoring & Observability

Logging

Log Levels

• DEBUG - Development only
• INFO - Normal operations
• WARNING - Potential issues
• ERROR - Errors requiring attention
• CRITICAL - System failures

Log Files

• logs/px360.log - Application logs
• logs/integrations.log - Integration events
• Celery logs - Worker output
• Nginx logs - Access logs

Metrics (Future)

Application Metrics

• Request rate
• Response time
• Error rate
• Active users

Business Metrics

• Events processed/hour
• Surveys sent/day
• Average response time
• SLA compliance rate

Health Checks

Endpoint: /health/

{
  "status": "ok",
  "services": {
    "database": "ok",
    "celery_beat": "ok"
  }
}

Deployment Architecture

Development

Docker Compose:
- web (Django + Gunicorn)
- db (PostgreSQL)
- redis (Redis)
- celery (Worker)
- celery-beat (Scheduler)

Production (Recommended)

┌─────────────────┐
│  Load Balancer  │
│   (Nginx/ALB)   │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼───┐
│ Web1 │  │ Web2 │  (Django + Gunicorn)
└───┬──┘  └──┬───┘
    │        │
    └────┬───┘
         │
┌────────▼────────┐
│   PostgreSQL    │
│   (Primary +    │
│   Replicas)     │
└─────────────────┘

┌─────────────────┐
│     Redis       │
│  (Cluster Mode) │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼───┐
│Celery│  │Celery│  (Workers)
│  W1  │  │  W2  │
└──────┘  └──────┘

┌─────────────────┐
│  Celery Beat    │
│  (Scheduler)    │
└─────────────────┘

Infrastructure Requirements

Minimum (Development)

• CPU: 2 cores
• RAM: 4 GB
• Storage: 20 GB

Recommended (Production)

• Web: 4 cores, 8 GB RAM (2+ instances)
• Workers: 2 cores, 4 GB RAM (3+ instances)
• Database: 4 cores, 16 GB RAM, 100 GB SSD
• Redis: 2 cores, 4 GB RAM
• Total: ~40 GB RAM, 200 GB storage

Data Residency & Compliance

Saudi Arabia Requirements

Data Residency

• All data stored in KSA data centers
• No data transfer outside KSA
• Backup storage in KSA

Compliance

• MOH regulations compliance
• CHI requirements
• HIPAA-equivalent privacy standards
• GDPR-like data protection

Security Measures

Network Security

• VPC isolation
• Private subnets for database
• Security groups/firewall rules
• DDoS protection

Application Security

• HTTPS/TLS 1.3 only
• CSRF protection
• XSS protection
• SQL injection prevention (ORM)
• Rate limiting
• Input validation

Data Security

• Encryption at rest (database)
• Encryption in transit (TLS)
• Encrypted backups
• Secure credential management (secrets manager)

Performance Targets

Response Times

• API endpoints: < 200ms (p95)
• Dashboard load: < 1s
• Event processing: < 5s (p95)
• Survey delivery: < 30s

Throughput

• Events: 10,000/hour
• Concurrent users: 500
• API requests: 100,000/day
• Surveys sent: 5,000/day

Availability

• Uptime: 99.9% (8.76 hours downtime/year)
• RTO: 1 hour
• RPO: 15 minutes

Disaster Recovery

Backup Strategy

• Database: Daily full + hourly incremental
• Files: Daily backup
• Retention: 30 days
• Off-site backup: Yes

Recovery Procedures

1. Database restore from backup
2. Application deployment from Git
3. Configuration from secrets manager
4. Verification and testing

Future Enhancements

Phase 9: Advanced Features

• Real-time dashboards (WebSockets)
• Mobile app (React Native)
• Advanced analytics (ML predictions)
• Automated action routing (AI)
• Voice of customer analysis (NLP)

Phase 10: Integration Expansion

• MOH real-time reporting
• CHI claims integration
• Social media sentiment analysis
• Patient portal integration
• Telemedicine integration

---

Document Version: 1.0
Last Updated: December 14, 2025
Status: Living Document