26 KiB
26 KiB
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
- Patient arrives → PatientJourneyInstance created from template
- HIS events trigger → PatientJourneyStageInstance marked complete
- Stage completion → Survey dispatched via notifications
- 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
- Survey template created with questions
- Patient journey stage triggers → SurveyInstance created
- Notification sent with secure link
- Patient completes survey → SurveyResponse stored
- 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
- Complaint submitted via form, call center, or external source
- Classified using SHCT taxonomy
- Assigned to department/staff with SLA tracking
- Staff works on resolution → updates logged
- Resolution proposed → patient satisfaction survey sent
- 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
- Call received → CallCenterInteraction created
- Type classified → handled by agent
- Resolution provided → satisfaction rating collected
- Rating ≤ 2 → PX Action created automatically
- 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
- Negative feedback detected (survey/complaint/social/call)
- PX Action automatically created
- Assigned via routing rules
- Staff works on action → updates logged
- Evidence attached → submitted for approval
- 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
- Complaint submitted
- Classified (SHCT taxonomy)
- Assigned to department
- SLA tracking starts
- Staff investigates
- Resolution provided
- Satisfaction survey sent
- Patient responds:
- Satisfied → Closed
- Unsatisfied → Reopened / Escalated
Patient Journey Flow
- Patient admitted (HIS event)
- Journey instance created
- Stage 1 begins (event trigger)
- Stage 1 complete survey sent
- Next stage begins
- ... continues through journey
- Discharge event
- Post-discharge survey sent
- Journey closed
PX Action Flow
- Negative feedback detected
- Action created automatically
- Routed to responsible staff
- Staff works on action
- Evidence attached
- Submitted for approval
- Approved → Closed
- Or rejected → Returned to staff
Summary
PX360 is a comprehensive patient experience management system that:
- Tracks Patient Journeys from admission through follow-up
- Collects Feedback via surveys, complaints, call center, social media
- Analyzes Sentiment using AI for all feedback types
- Triggers Actions automatically from negative feedback
- Manages SLAs with reminders and escalation
- Reports Insights via executive dashboards and AI reports
- Improves Continuously through RCA and action tracking
The system connects every patient touchpoint into a unified loop: feedback → analysis → action → improvement → measurement.