# PX360 Patient Experience 360° Management System

## Overview

PX360 is a comprehensive enterprise patient experience management system designed for AlHammadi Group (Saudi Arabia). It tracks, measures, and improves patient satisfaction across multiple touchpoints in the healthcare journey—from admission through discharge and follow-up.

The system automatically collects patient feedback through surveys, complaints, call center interactions, and social media. It then routes negative feedback to improvement actions with SLA tracking, performs root cause analysis, and provides executive dashboards with AI-powered insights.

---

## Application Modules

This section documents each module (Django app) in the PX360 system, explaining what it does, its key features, and how it relates to other modules.

---

## 1. accounts — User Management & Authentication

### What It Does

Manages user accounts, authentication, roles, and employee onboarding. Provides the foundation for user identity and access control throughout the system.

### Key Features

- **Email-based JWT Authentication**: Secure login using email and password with JWT tokens
- **Role-Based Access Control (RBAC)**: Users assigned to groups (PX Admin, Hospital Admin, Department Manager, etc.) that determine their permissions
- **Onboarding Wizard**: Multi-step onboarding process with progress tracking for new employees
- **Digital Acknowledgements**: Employees digitally sign and acknowledge policy documents, training materials
- **PDF Generation**: Generates downloadable PDFs of acknowledged documents
- **Staff Activity Logging**: Audit trail tracking login/logout and CRUD operations

### Key Models

- **User**: Custom user with UUID, email, hospital/department assignments, notification preferences
- **Role**: Role definitions for RBAC
- **AcknowledgementContent**: Bilingual educational content (EN/AR)
- **UserAcknowledgement**: Records of user acknowledgements with timestamps and signatures

---

## 2. organizations — Hospital & Department Structure

### What It Does

Defines the organizational hierarchy including healthcare organizations, hospitals, departments, staff members, and patients. Provides the structural context for all other modules.

### Key Features

- **Multi-Hospital Support**: Manage multiple facilities under one organization
- **Bilingual Names**: All entities support English and Arabic names
- **Staff Hierarchy**: Report-to relationships and direct reports tracking
- **Patient Records**: Patient registration with MRN and encrypted national ID
- **Department Categories**: Nursing, Medical, Non-Medical, Support Services classification
- **Location Management**: Physical location tracking with sections and subsections

### Key Models

- **Organization**: Top-level healthcare organization entity
- **Hospital**: Individual hospital/facility with executive leadership
- **Department**: Departments within hospitals
- **Staff**: Staff members with types (Physician, Nurse, Admin), job titles, sections
- **Patient**: Patient records with MRN, national ID, contact information

---

## 3. journeys — Patient Journey Templates & Instances

### What It Does

Tracks patient journeys through hospital pathways. Defines journey templates with stages and monitors actual patient journeys from admission to discharge.

### Key Features

- **Journey Templates**: Predefined pathways (EMS, Inpatient, OPD, Day Case)
- **Stage Definitions**: Each stage has specific event triggers and post-discharge survey configuration
- **Event-Triggered Progression**: Journey stages complete automatically based on integration events from HIS
- **Journey Completion Tracking**: Percentage completion and stage status monitoring
- **Survey Integration**: Automatically sends surveys at specific journey stages

### Key Models

- **PatientJourneyTemplate**: Defines journey stages and flow
- **PatientJourneyStageTemplate**: Individual stage definitions with triggers
- **PatientJourneyInstance**: Actual patient journey record
- **PatientJourneyStageInstance**: Stage completion tracking with timestamps

### Workflow

1. Patient arrives → **PatientJourneyInstance** created from template
2. HIS events trigger → **PatientJourneyStageInstance** marked complete
3. Stage completion → Survey dispatched via notifications
4. Journey ends → Post-discharge survey sent

---

## 4. surveys — Survey System

### What It Does

Creates and manages bilingual surveys (English/Arabic) linked to patient journeys. Collects patient responses and triggers actions based on negative feedback.

### Key Features

- **Bilingual Surveys**: Full support for English and Arabic with automatic language detection
- **Multiple Question Types**: Rating (1-5), NPS, Yes/No, Multiple Choice, Text, Likert scale
- **Dynamic Routing**: Conditional question flow based on previous answers
- **Journey-Triggered Surveys**: Surveys sent automatically at specific journey stages
- **Resolution Satisfaction Surveys**: Sent when complaint is resolved
- **Negative Threshold Triggers**: Low scores automatically create PX Actions
- **Token-Based Security**: Secure survey links with expiring tokens

### Key Models

- **SurveyTemplate**: Survey definitions with questions
- **SurveyQuestion**: Individual questions with types and routing rules
- **SurveyInstance**: Individual survey distributed to patients
- **SurveyResponse**: Patient responses stored with timestamps

### Workflow

1. Survey template created with questions
2. Patient journey stage triggers → **SurveyInstance** created
3. Notification sent with secure link
4. Patient completes survey → **SurveyResponse** stored
5. Low score detected → PX Action created automatically

---

## 5. complaints — Complaint Management

### What It Does

Core complaint management system with SLA tracking, escalation, and resolution workflow. The primary module for tracking patient complaints.

### Key Features

- **4-Level Classification Taxonomy**: Domain → Category → Subcategory → Classification (SHCT structure)
- **SLA Tracking**: Configurable SLA per hospital/source/severity/priority with due dates and reminders
- **Workflow Management**: Open → In Progress → Partially Resolved → Resolved → Closed
- **Resolution Satisfaction Surveys**: Surveys sent on complaint closure
- **Resolution Categories**: Full Action, Partial Action, No Action, Cannot Resolve
- **AI Integration**: AI-generated summaries and suggested actions
- **External References**: MOH and CHI reference linking
- **Public Tracking**: Patients can look up complaint status with tracking code
- **Escalation Rules**: Automatic escalation based on configurable rules
- **Attachment Support**: File uploads for evidence documentation

### Key Models

- **ComplaintCategory**: 4-level classification hierarchy
- **Complaint**: Main complaint model with full tracking
- **ComplaintAttachment**: File attachments
- **ComplaintUpdate**: Timeline and audit trail
- **ComplaintSLAConfig**: Configurable SLA rules
- **EscalationRule**: Escalation configuration

### Workflow

1. Complaint submitted via form, call center, or external source
2. Classified using SHCT taxonomy
3. Assigned to department/staff with SLA tracking
4. Staff works on resolution → updates logged
5. Resolution proposed → patient satisfaction survey sent
6. Patient satisfied → Closed; else → Reopened

---

## 6. feedback — Patient Feedback & Suggestions

### What It Does

Manages patient feedback including compliments, suggestions, and general comments. Different from complaints—focused on improvement ideas rather than problems.

### Key Features

- **Feedback Types**: Compliment, Suggestion, General, Inquiry, Satisfaction Check
- **Sentiment Analysis**: Automatic sentiment detection via AI engine
- **Workflow**: Submitted → Reviewed → Acknowledged → Closed
- **Multi-Level Classification**: Hospital, Medical, Non-Medical, Nursing, ER, Support categories
- **Action Plan Tracking**: Link suggestions to improvement actions
- **Response Tracking**: Staff can respond to patient feedback

### Key Models

- **Feedback**: Main feedback model
- **FeedbackAttachment**: File attachments
- **FeedbackResponse**: Staff responses
- **CommentActionPlan**: Improvement plans from feedback

---

## 7. observations — Staff Observation Reporting

### What It Does

Anonymous staff observation reporting system. Allows staff to report safety concerns, process issues, or positive observations without revealing identity.

### Key Features

- **Anonymous Submission**: No login required; reporters remain unidentified
- **Optional Identification**: Reporters can optionally identify themselves
- **Unique Tracking Codes**: Public lookup codes for status checking
- **Full Lifecycle Management**: From submission to resolution
- **AI Analysis**: Automatic sentiment and category analysis
- **SLA Tracking**: Configurable SLA by hospital/severity with reminders
- **File Attachments**: Support for evidence documentation

### Key Models

- **ObservationCategory** / **ObservationSubCategory**: Classification structure
- **ObservationSLAConfig**: SLA configuration
- **Observation**: Main observation model
- **ObservationAttachment**: Evidence files
- **ObservationStatusLog**: Status change audit trail

---

## 8. callcenter — Call Center Interaction Tracking

### What It Does

Tracks call center interactions with patients. Records call details, satisfaction ratings, and resolution status for agent performance tracking.

### Key Features

- **Call Type Classification**: Inquiry, Complaint, Appointment, Follow-up, Feedback
- **Satisfaction Rating**: 1-5 scale rating after call
- **Low Rating Triggers**: Negative ratings create PX Actions automatically
- **Agent Performance Tracking**: Track agent handling times and resolution rates
- **Call Duration Metrics**: Wait time and talk time recording
- **Call Record Import**: CSV import for call recording metadata

### Key Models

- **CallCenterInteraction**: Call records with ratings and duration
- **CallRecord**: Imported call metadata

### Workflow

1. Call received → **CallCenterInteraction** created
2. Type classified → handled by agent
3. Resolution provided → satisfaction rating collected
4. Rating ≤ 2 → PX Action created automatically
5. Data used for agent performance reports

---

## 9. px_action_center — Improvement Action Tracking

### What It Does

Manages improvement actions (PX Actions) triggered by negative feedback. Tracks actions from creation to closure with SLA monitoring.

### Key Features

- **Auto-Creation Triggers**: Negative surveys, complaints, social media, call center ratings, KPI thresholds
- **Workflow**: Open → In Progress → Pending Approval → Approved → Closed
- **SLA Tracking**: Due dates, reminders, escalation for overdue items
- **Approval Workflow**: Multi-level approval before closure
- **Evidence Attachment**: Documents supporting closure
- **Routing Rules**: Automatic assignment based on configurable rules

### Key Models

- **PXAction**: Main action model with SLA tracking
- **PXActionLog**: Timeline and updates
- **PXActionAttachment**: Evidence files
- **PXActionSLAConfig**: Configurable SLA rules
- **RoutingRule**: Assignment rules

### Workflow

1. Negative feedback detected (survey/complaint/social/call)
2. PX Action automatically created
3. Assigned via routing rules
4. Staff works on action → updates logged
5. Evidence attached → submitted for approval
6. Approved → Closed

---

## 10. rca — Root Cause Analysis

### What It Does

Manages root cause analysis (RCA) for complaints, inquiries, observations, and feedback. Provides structured investigation and corrective action tracking.

### Key Features

- **Generic Linking**: Links to any feedback type via GenericForeignKey (complaints, inquiries, observations, feedback)
- **Root Cause Categories**: Process, People, Equipment, Communication, Policy, Environment, Technology
- **Corrective Action Tracking**: Actions with effectiveness scoring
- **Risk Scoring**: Likelihood × Impact scoring
- **Evidence Management**: Document attachments
- **Audit Trail**: Full status change history

### Key Models

- **RootCauseAnalysis**: Main RCA linked to feedback item
- **RCARootCause**: Individual root causes with categories
- **RCACorrectiveAction**: Corrective actions with effectiveness tracking
- **RCAAttachment**: Evidence documents

---

## 11. appreciation — Staff Recognition & Gamification

### What It Does

Allows patients, families, and staff to send appreciation messages to healthcare staff. Includes gamification with badges and monthly leaderboards.

### Key Features

- **Bilingual Messages**: Full EN/AR support
- **Visibility Levels**: Private, Department, Hospital, Public
- **Anonymous Option**: Send anonymously if desired
- **AI Analysis**: Sentiment and theme analysis
- **Badge Gamification**: Earn badges for achievements
- **Monthly Leaderboards**: Rankings and statistics
- **Workflow**: Draft → Activated → AI Analyzed → Sent → Acknowledged

### Key Models

- **AppreciationCategory**: Categories for appreciation
- **Appreciation**: Appreciation messages
- **AppreciationBadge**: Gamification badges
- **UserBadge**: Earned badges
- **AppreciationStats**: Monthly statistics

---

## 12. notifications — Multi-Channel Notification System

### What It Does

Sends notifications via SMS, WhatsApp, Email, and in-app channels. Tracks delivery status and supports reusable templates.

### Key Features

- **Multiple Channels**: SMS, WhatsApp, Email, Push notifications
- **Template-Based Messaging**: Reusable bilingual templates with variable substitution
- **Delivery Status Tracking**: Pending → Sending → Sent → Delivered → Failed → Bounced
- **Retry Logic**: Automatic retry for failed deliveries
- **Variable Substitution**: Patient name, survey link, etc.

### Key Models

- **NotificationLog**: Delivery attempt tracking
- **NotificationTemplate**: Reusable templates
- **UserNotification**: In-app notifications

---

## 13. integrations — External System Integration

### What It Does

Handles inbound events from external systems including HIS (Hospital Information System), Lab, Radiology, Pharmacy, MOH, and CHI. Drives journey progression and survey triggers.

### Key Features

- **Patient Journey Event Triggers**: HIS events complete journey stages
- **Survey Delivery Automation**: Events trigger survey distribution
- **Patient Type Mapping**: Maps patient types to survey templates
- **Event Code Mapping**: External codes mapped to internal triggers
- **Event Types**: Admission, Discharge, Lab Results, etc.

### Key Models

- **InboundEvent**: Integration events from external systems
- **IntegrationConfig**: External system connection config
- **SurveyTemplateMapping**: Patient type to survey mapping
- **HISPatientVisit**: Patient visit data from HIS
- **HISVisitEvent**: Individual visit timeline events
- **EventMapping**: External to internal code mapping

---

## 14. ai_engine — AI Sentiment Analysis

### What It Does

Provides AI-powered sentiment analysis and NLP capabilities. Analyzes text from complaints, surveys, social media, and call center notes.

### Key Features

- **Sentiment Classification**: Positive, Neutral, Negative
- **Sentiment Score**: -1 to 1 scale
- **Confidence Level**: 0 to 1 certainty score
- **Keyword Extraction**: Key terms identified
- **Entity Extraction**: Named entities (locations, staff, departments)
- **Emotion Detection**: Specific emotions identified
- **Bilingual Support**: English and Arabic analysis

### Key Models

- **SentimentResult**: Generic results linked to any content

---

## 15. social — Social Media Management

### What It Does

Unified social media account management. Monitors and analyzes reviews/comments from social platforms.

### Key Features

- **Multi-Platform Support**: LinkedIn, Google Business, Meta (Facebook/Instagram), TikTok, X (Twitter), YouTube
- **Token Management**: API tokens with expiration tracking
- **Delta Sync**: Incremental updates only
- **AI Bilingual Analysis**: Sentiment, summaries, keywords, topics, entities, emotions
- **Webhook Support**: Real-time notification of new comments
- **Reply Management**: Track responses to comments

### Key Models

- **SocialAccount**: Platform account credentials
- **SocialContent**: Posts and videos
- **SocialComment**: Comments/reviews with metrics
- **SocialReply**: Staff responses

---

## 16. analytics — KPI & Metrics Tracking

### What It Does

Defines and tracks KPIs and metrics across the system. Provides measurement framework for patient experience.

### Key Features

- **KPI Definitions**: Categories including patient satisfaction, complaint management, SLA compliance
- **Threshold Configuration**: Target, Warning, Critical levels
- **Period-Based Measurements**: Hourly, Daily, Weekly, Monthly, Quarterly, Yearly
- **Hospital/Department Tracking**: Granular organization-level metrics

### Key Models

- **KPI**: KPI definition with categories and thresholds
- **KPIValue**: Actual measurements at points in time

---

## 17. executive_summary — AI-Powered Executive Reports

### What It Does

Provides AI-generated executive dashboards, reports, and predictive insights. Generates narrative summaries from data.

### Key Features

- **Bilingual Narrative Summaries**: Auto-generated reports in EN/AR
- **Trend Analysis**: Variance tracking over time
- **Predictive Risk Warnings**: Early warning for emerging issues
- **Automated Report Generation**: Weekly/Monthly/Quarterly reports
- **Recommendation Engine**: AI-suggested actions

### Key Models

- **ExecutiveMetric**: Daily KPI snapshots
- **ExecutiveReport**: AI-generated narrative summaries
- **PredictiveInsight**: Detected patterns and anomalies
- **AIRecommendation**: Suggested actions

---

## 18. dashboard — PAD Department Weekly Dashboard

### What It Does

Tracks PAD (Patient Experience Department) weekly performance. Manages employee evaluation metrics and report completion.

### Key Features

- **Evaluation Notes**: Staff evaluation by category/sub-category
- **Complaint Request Tracking**: Tracks complaint request filling status
- **Report Completion**: Weekly compliance tracking
- **Escalation Timing**: Escalated complaint timing analysis
- **Inquiry Details**: Detailed inquiry tracking

### Key Models

- **EvaluationNote**: Evaluation notes
- **ComplaintRequest**: Request filling status
- **ReportCompletion**: Weekly report status
- **EscalatedComplaintLog**: Escalation timing

---

## 19. reports — Custom Report Builder

### What It Does

Custom report creation, scheduling, and generation. Allows non-technical users to build reports from various data sources.

### Key Features

- **Multiple Data Sources**: Complaints, Inquiries, Observations, PX Actions, Surveys, Physicians
- **Filter Configuration**: Flexible filtering options
- **Column Selection**: Choose displayed fields
- **Grouping & Sorting**: Organize data
- **Chart Configuration**: Visual charts
- **Scheduling**: Once, Daily, Weekly, Monthly, Quarterly
- **Export Formats**: HTML, PDF, Excel, CSV

### Key Models

- **SavedReport**: Report configurations
- **ReportSchedule**: Scheduled generation
- **GeneratedReport**: Generated instances
- **ReportTemplate**: Pre-built templates

---

## 20. standards — Compliance Standards Tracking

### What It Does

Tracks compliance with healthcare standards (CBAHI, MOH, CHI, JCI). Manages evidence and assessment status.

### Key Features

- **Multi-Source Support**: CBAHI, MOH, CHI, JCI, etc.
- **Compliance Status**: Not Assessed, Met, Partially Met, Not Met, Not Applicable
- **Assessment Codes**: TM, PM, NM with levels
- **Evidence Management**: Document uploads
- **Score Tracking**: Overall compliance scores

### Key Models

- **StandardSource**: Standards bodies
- **StandardCategory**: Categories within sources
- **Standard**: Actual requirements
- **StandardCompliance**: Compliance status per hospital
- **StandardAttachment**: Evidence documents

---

## 21. references — Document & Folder Management

### What It Does

Manages references, documents, and folders. Provides document repository for policies, procedures, and templates.

### Key Features

- **Folder Hierarchy**: Nested folder structure
- **Document Management**: Upload, version, organize documents
- **Search**: Full-text search capability
- **Access Control**: Permission-based access

### Key Models

- **Folder**: Folder structure
- **Reference**: Document records

---

## 22. px_sources — Feedback Source Management

### What It Does

Manages the origins of patient feedback. Tracks which sources provide feedback and who manages them.

### Key Features

- **Source Type Classification**: Internal, External, Partner, Government
- **Source User Management**: Users assigned to sources with permissions
- **Usage Statistics**: Track source usage across system
- **Communication Requests**: Workflow for source user communications

### Key Models

- **PXSource**: Feedback sources
- **SourceUser**: Users linked to sources
- **SourceUsage**: Usage statistics
- **CommunicationRequest**: Communication workflow

---

## 23. core — Base Models & Shared Functionality

### What It Does

Provides base models and shared utilities inherited throughout the system.

### Key Features

- **TimeStampedModel**: Created/Updated timestamps
- **UUIDModel**: UUID primary key
- **SoftDeleteModel**: Soft delete with restore
- **TenantModel**: Hospital-tenant isolation
- **Audit Logging**: Generic audit events
- **Common Enums**: Priority, Severity choices

---

## How the Modules Work Together

### Data Flow Overview

```
┌─────────────────┐
│   Integrations   │ ← HIS, Lab, Radiology events
│   (journeys)    │
└────────┬────────┘
         │ triggers
         ▼
┌─────────────────┐
│    Journeys      │ ← Patient pathway tracking
│   (surveys)     │
└────────┬────────┘
         │ stage completion
         ▼
┌─────────────────┐
│    Surveys      │ ← Patient feedback collection
│  (notifications)│
└────────┬────────┘
         │ response
         ▼
┌─────────────────┐
│  Complaints,    │
│  Feedback,      │ ← Feedback received
│  Observations,  │
│  Call Center    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Engine    │ ← Sentiment analysis
│   (all types)  │
└────────┬────────┘
         │ sentiment
         ▼
┌─────────────────┐
│  PX Action      │ ← Negative feedback triggers
│   Center       │    actions
└────────┬────────┘
         │ root cause
         ▼
┌─────────────────┐
│     RCA         │ ← Root cause analysis
│   (feedback)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Executive     │ ← AI-powered insights
│   Summary       │    and reports
└─────────────────┘
```

### Key Integration Points

| From | To | Trigger |
|------|-----|---------|
| Integrations | Journeys | HIS events complete stages |
| Journeys | Surveys | Stage completion sends surveys |
| Surveys | PX Action Center | Low score threshold |
| Complaints | Surveys | Resolution satisfaction survey |
| Complaints | PX Action Center | Low resolution satisfaction |
| Call Center | PX Action Center | Low rating (≤2) |
| Social | PX Action Center | Negative sentiment |
| All Feedback | AI Engine | Sentiment analysis |
| PX Action Center | RCA | Root cause investigation |
| RCA / Feedback | Executive Summary | AI report generation |
| All Modules | Notifications | Multi-channel delivery |

### Multi-Hospital Architecture

- Each record tied to a **Hospital** via tenant isolation
- **Accounts** users assigned to hospitals and departments
- **Analytics** calculated per hospital
- **SLA** configurable per hospital
- **Executive Summary** shows cross-hospital and single-hospital views

---

## User Roles & Permissions

| Role | Description |
|------|-------------|
| **PX Admin** | System-wide administration |
| **Hospital Admin** | Full hospital management |
| **Department Manager** | Department-level management |
| **Staff** | Execute assigned tasks |
| **Viewer** | Read-only access |
| **Patient** | Submit feedback, view surveys |

---

## System Workflows

### Complaint Resolution Flow

1. Complaint submitted
2. Classified (SHCT taxonomy)
3. Assigned to department
4. SLA tracking starts
5. Staff investigates
6. Resolution provided
7. Satisfaction survey sent
8. Patient responds:
   - Satisfied → Closed
   - Unsatisfied → Reopened / Escalated

### Patient Journey Flow

1. Patient admitted (HIS event)
2. Journey instance created
3. Stage 1 begins (event trigger)
4. Stage 1 complete survey sent
5. Next stage begins
6. ... continues through journey
7. Discharge event
8. Post-discharge survey sent
9. Journey closed

### PX Action Flow

1. Negative feedback detected
2. Action created automatically
3. Routed to responsible staff
4. Staff works on action
5. Evidence attached
6. Submitted for approval
7. Approved → Closed
8. Or rejected → Returned to staff

---

## Summary

PX360 is a comprehensive patient experience management system that:

1. **Tracks Patient Journeys** from admission through follow-up
2. **Collects Feedback** via surveys, complaints, call center, social media
3. **Analyzes Sentiment** using AI for all feedback types
4. **Triggers Actions** automatically from negative feedback
5. **Manages SLAs** with reminders and escalation
6. **Reports Insights** via executive dashboards and AI reports
7. **Improves Continuously** through RCA and action tracking

The system connects every patient touchpoint into a unified loop: **feedback → analysis → action → improvement → measurement**.