# 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
```json
{
  "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/`
```json
{
  "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