529 lines
16 KiB
Markdown
529 lines
16 KiB
Markdown
# 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
|