PX360 - Patient Experience 360 Management System

AlHammadi Group (Saudi Arabia)

A comprehensive enterprise patient experience management system built with Django 5.0, designed to track, measure, and improve patient satisfaction across multiple touchpoints in the healthcare journey.

🎯 Project Overview

PX360 is a complex, event-driven system that:

• Tracks patient journeys through EMS, Inpatient, and OPD pathways
• Automatically sends stage-specific surveys based on integration events
• Manages complaints with SLA tracking and escalation
• Creates and tracks PX actions from negative feedback
• Provides real-time analytics and dashboards
• Supports multi-language (Arabic/English) operations

🏗️ Architecture

Tech Stack

• Backend: Python 3.12+ / Django 5.0
• API: Django REST Framework with JWT authentication
• Database: PostgreSQL 15
• Task Queue: Celery + Redis
• Scheduler: Celery Beat
• Documentation: drf-spectacular (OpenAPI/Swagger)
• Deployment: Docker + Docker Compose

Project Structure

px360/
├── config/                 # Project configuration
│   ├── settings/          # Split settings (base/dev/prod)
│   ├── urls.py           # Main URL configuration
│   ├── celery.py         # Celery configuration
│   ├── wsgi.py           # WSGI application
│   └── asgi.py           # ASGI application
├── apps/                  # Business applications
│   ├── core/             # Base models, utilities, health check
│   ├── accounts/         # User authentication & RBAC
│   ├── organizations/    # Hospitals, departments, staff, patients
│   ├── journeys/         # Patient journey templates & instances
│   ├── 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/    # SMS/WhatsApp/Email delivery
│   └── ai_engine/        # Sentiment analysis
├── templates/            # Django templates
├── static/              # Static files
├── docs/                # Documentation
├── docker/              # Docker configuration files
├── requirements/        # Python dependencies
├── manage.py           # Django management script
├── Dockerfile          # Docker image definition
└── docker-compose.yml  # Multi-container setup

🚀 Quick Start

Prerequisites

• Python 3.12+
• Docker & Docker Compose
• PostgreSQL 15 (if running locally)
• Redis 7 (if running locally)

Installation

1. Clone the repository

git clone <repository-url>
cd PX360

2. Create environment file

cp .env.example .env
# Edit .env with your configuration

3. Run with Docker (Recommended)

docker-compose up --build

This will start:

• Web server (Django) on http://localhost:8000
• PostgreSQL database
• Redis
• Celery worker
• Celery beat scheduler

4. Access the application

• API: http://localhost:8000/api/
• Admin: http://localhost:8000/admin/
• API Docs: http://localhost:8000/api/docs/
• Health Check: http://localhost:8000/health/

Local Development (Without Docker)

1. Create virtual environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install dependencies

pip install -e ".[dev]"

3. Set up database

# Make sure PostgreSQL is running
createdb px360

4. Run migrations

python manage.py migrate

5. Create superuser

python manage.py createsuperuser

6. Run development server

python manage.py runserver

7. Run Celery worker (separate terminal)

celery -A config worker -l info

8. Run Celery beat (separate terminal)

celery -A config beat -l info

📋 Implementation Status

✅ Phase 0: Bootstrap & Infrastructure (COMPLETED)

• Project structure with config/ and apps/
• Split settings (base/dev/prod)
• Django 5.0 + DRF setup
• Celery + Redis configuration
• Docker setup (web, db, redis, celery, celery-beat)
• Health check endpoint
• Environment configuration

🔄 Phase 1: Core + Accounts + RBAC + Audit (IN PROGRESS)

• Core base models (UUIDModel, TimeStampedModel, SoftDeleteModel)
• AuditEvent model with generic foreign key
• AuditService for centralized logging
• Custom User model with UUID primary key
• Role model linked to Django Groups
• JWT authentication endpoints
• DRF permission classes
• Management commands for default roles
• User registration and login audit logging

🔄 Phase 2: Organizations (IN PROGRESS)

• Hospital model
• Department model (hierarchical)
• Physician model
• Employee model
• Patient model
• Admin interfaces
• DRF API endpoints
• RBAC enforcement

⏳ Phase 3: Journeys + Event Intake (PENDING)

• JourneyType enum (EMS/Inpatient/OPD)
• PatientJourneyTemplate & StageTemplate models
• PatientJourneyInstance & StageInstance models
• InboundEvent model for integration events
• Event processing Celery task
• API endpoint to receive events
• Stage completion logic

⏳ Phase 4: Surveys + Delivery (PENDING)

• SurveyTemplate & SurveyQuestion models
• SurveyInstance & SurveyResponse models
• Bilingual survey support (AR/EN)
• Signed token URL generation
• Survey submission endpoint
• Automatic survey creation on stage completion
• Notification delivery (SMS/WhatsApp/Email stubs)

⏳ Phase 5: Complaints + Resolution Satisfaction (PENDING)

• Complaint model with SLA tracking
• Complaint workflow (open → resolved → closed)
• ComplaintAttachment & ComplaintUpdate models
• Inquiry model
• Resolution satisfaction survey trigger
• API endpoints

⏳ Phase 6: PX Action Center (PENDING)

• PXAction model with SLA configuration
• Automatic action creation triggers
• SLA reminder Celery tasks
• Escalation logic
• Approval workflow
• Evidence attachment

⏳ Phase 7: Call Center + Social + AI Engine (PENDING)

• Call center interaction models
• Social media mention models
• AI sentiment analysis (stubbed)
• Sentiment-driven action creation

⏳ Phase 8: Analytics + Dashboards (PENDING)

• KPI models and aggregation
• Physician monthly ratings
• QI project models
• PX Command Center dashboard
• Department/physician leaderboards

⏳ Comprehensive UI (PENDING)

• Bootstrap 5 base templates
• PX Command Center dashboard
• Complaints console
• PX Action Center board
• Journey template builder
• Survey control center
• Public survey forms

🔑 Key Features

Event-Driven Architecture

• Integration events from HIS/Lab/Radiology/Pharmacy trigger journey stage completions
• Stage completions automatically send stage-specific surveys
• Negative feedback automatically creates PX actions

SLA Management

• Configurable SLA thresholds by priority/severity
• Automatic reminders before due date
• Automatic escalation when overdue
• Audit trail of all SLA events

Multi-Language Support

• Arabic and English throughout the system
• Bilingual survey templates
• RTL-ready UI components

RBAC (Role-Based Access Control)

• PX Admin: Full system access
• Hospital Admin: Hospital-level access
• Department Manager: Department-level access
• PX Coordinator: Action management
• Physician/Nurse/Staff: Limited access
• Viewer: Read-only access

📚 API Documentation

Once the server is running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/api/docs/
• ReDoc: http://localhost:8000/api/redoc/
• OpenAPI Schema: http://localhost:8000/api/schema/

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=apps --cov-report=html

# Run specific app tests
pytest apps/core/tests/

🔧 Management Commands

# Create default roles and groups
python manage.py create_default_roles

# Create sample data for testing
python manage.py create_sample_data

# Process pending integration events
python manage.py process_events

# Calculate KPIs
python manage.py calculate_kpis

📊 Celery Tasks

Periodic Tasks (Celery Beat)

• process-integration-events: Every 1 minute
• check-overdue-complaints: Every 15 minutes
• check-overdue-actions: Every 15 minutes
• send-sla-reminders: Every hour
• calculate-daily-kpis: Daily at 1 AM
• calculate-physician-ratings: Monthly on 1st at 2 AM

🔒 Security

• JWT authentication for API access
• RBAC enforced at view and API level
• Audit logging for all critical operations
• HTTPS enforced in production
• CSRF protection enabled
• SQL injection protection via ORM
• XSS protection via template escaping

🌍 Deployment

Production Checklist

• Set DEBUG=False in .env
• Configure SECRET_KEY with strong random value
• Set ALLOWED_HOSTS to your domain
• Configure production database
• Set up Redis for production
• Configure email backend (SMTP)
• Set up SMS/WhatsApp providers
• Configure static file serving (WhiteNoise/CDN)
• Set up SSL certificates
• Configure backup strategy
• Set up monitoring and logging
• Configure firewall rules

Environment Variables

See .env.example for all available configuration options.

📝 License

Proprietary - AlHammadi Group

👥 Team

• Client: AlHammadi Group, Saudi Arabia
• Project: PX360 Patient Experience Management System

📞 Support

For issues and questions, please contact the development team.

---

Note: This is a work in progress. The system is being built incrementally following the 8-phase implementation plan outlined in the requirements document.