HH/prompt.md

PX360 PROMPT ENHANCED

AlHammadi Group (Saudi Arabia).

This is a complex enterprise system. You MUST follow the process, implement incrementally, run checks, and produce a clean codebase. Do not skip steps. Do not guess silently. If a requirement is not implementable without external vendor credentials (MOH/CHI/social APIs), implement robust integration stubs with clear TODOs and testable interfaces.

⸻

0) Non-Negotiable Rules (Follow Strictly)
	1.	No monolithic app. Use the modular apps described below.
	2.	No undocumented magic. Every critical business rule must be documented in code comments and in /docs/.
	3.	Config-driven behavior: SLA thresholds, routing rules, journey templates, stage triggers, survey thresholds must be stored in DB models or settings, not hardcoded.
	4.	Event-driven: Patient journey stage completion and survey sending must be triggered via integration events (stored in DB + processed by Celery).
	5.	Everything has an API: Build DRF APIs for the main entities and operations (including journeys and stage events).
	6.	RBAC is mandatory: Role-based access must be implemented early and enforced in views/DRF permissions.
	7.	Auditing is mandatory: Status changes, assignments, SLA escalations, and external events must be logged.
	8.	Deliver in checkpoints: Implement in phases; each phase must compile, migrate, and pass basic tests.
	9.	Use UUIDs for all primary models (except Django internal tables).
	10.	Saudi context: Multi-language support (Arabic/English in surveys and UI where applicable), data residency assumptions, security best practices.

⸻

1) Tech Stack Requirements
	•	Python 3.11+
	•	Django 5.x
	•	DRF
	•	PostgreSQL
	•	Celery + Redis (celery-beat included)
	•	JWT auth (SimpleJWT)
	•	Bootstrap 5 templates (minimal but functional)
	•	django-environ for .env
	•	Docker + docker-compose
	•	Logging: structured logs with separate loggers for integrations
	•	Tests: pytest-django (preferred) OR Django TestCase
	•	Formatting/lint: ruff (preferred) OR black/isort/flake8

⸻

2) Project Name + Folder Layout

Project name: px360

Create this structure:

px360/
  manage.py
  config/
    __init__.py
    settings/
      __init__.py
      base.py
      dev.py
      prod.py
    urls.py
    asgi.py
    wsgi.py
    celery.py
  apps/
    core/
    accounts/
    organizations/
    journeys/
    surveys/
    complaints/
    feedback/
    callcenter/
    social/
    px_action_center/
    analytics/
    physicians/
    projects/
    integrations/
    notifications/
    ai_engine/
  templates/
  static/
  docs/
  requirements/
  docker/
  docker-compose.yml
  Dockerfile
  .env.example
  README.md

Important: Put all business apps under apps/ for clarity.

3) Implementation Phases (Must Follow)

Phase 0 — Bootstrap & Infrastructure

Deliverables:
	•	Django project scaffolding
	•	settings split (base/dev/prod)
	•	environment loading via .env
	•	Dockerfile + docker-compose (web, db, redis, celery, celery-beat)
	•	Celery working and discoverable tasks
	•	Health endpoint: /health/
	•	Basic README with run commands

Acceptance:
	•	docker compose up works
	•	migrations run
	•	health endpoint returns JSON {status:"ok"}

⸻

Phase 1 — Core + Accounts + RBAC + Audit

Deliverables:
	•	core app:
	•	TimeStampedModel, UUIDModel, SoftDeleteModel (if needed)
	•	AuditEvent model (generic audit log)
	•	reusable enums/choices
	•	accounts app:
	•	Custom User model (extends AbstractUser)
	•	Role model or role choices with Group mapping
	•	Permission utilities + DRF permission classes
	•	Create default roles & groups via data migration/management command
	•	Authentication:
	•	JWT endpoints
	•	Audit logging hooks:
	•	record login, role changes, status changes (later) using helper service

Acceptance:
	•	Can create users with roles
	•	RBAC enforced on at least one endpoint
	•	AuditEvent records at least user login and a sample action

⸻

Phase 2 — Organizations (Hospitals/Departments/People)

Deliverables:
* organizations app models:
* Hospital, Department (hierarchical), Physician, Employee, Patient
* Admin pages for these models
* DRF endpoints for CRUD (admin/authorized only)

Acceptance:
* CRUD works, permissions enforced

⸻

Phase 3 — Journeys (EMS/Inpatient/OPD) + Event Intake

Deliverables:
	•	journeys app models (templates + instances):
	•	JourneyType enum: EMS / INPATIENT / OPD
	•	PatientJourneyTemplate
	•	PatientJourneyStageTemplate
	•	PatientJourneyInstance
	•	PatientJourneyStageInstance
	•	Journey configuration UI (admin) + APIs
	•	Integration event table (in integrations app or journeys app):
	•	InboundEvent model to store events from HIS/Lab/Radiology/Pharmacy etc.
	•	Fields: source_system, event_code, payload_json, encounter_id, patient_identifier, received_at, processed_at, status, error
	•	An API endpoint to receive events:
	•	POST /api/integrations/events/ (secured by API key or JWT service account)
	•	Celery task that processes unprocessed inbound events:
	•	resolves journey by encounter_id
	•	completes stage based on trigger_event_code
	•	writes audit logs

Acceptance:
	•	Can define an OPD journey template with stages
	•	Can create a journey instance for an encounter
	•	Posting an inbound event completes the correct stage instance

⸻

Phase 4 — Surveys (Journey Stage Surveys) + Delivery

Deliverables:
	•	surveys app models:
	•	SurveyTemplate, SurveyQuestion
	•	SurveyInstance, SurveyResponse
	•	Survey language support (ar/en text fields)
	•	Survey link generation:
	•	use signed token URL to prevent guessing
	•	Survey submission endpoint:
	•	POST /api/surveys/submit/ or instance-specific endpoints
	•	Journey integration:
	•	When a stage completes, if:
	•	auto_send_survey=True
	•	survey_template exists
	•	Then create SurveyInstance linked to:
	•	journey_instance
	•	journey_stage_instance
	•	encounter_id
	•	notifications app:
	•	unify send interface:
	•	send_sms(), send_whatsapp(), send_email()
	•	for now: implement a “console backend” that logs messages in DB (NotificationLog)
	•	Celery tasks:
	•	send_survey_invitation(instance_id)
	•	retry logic on failure
	•	Stage survey examples:
	•	OPD_MD_CONSULT → survey for MD interaction
	•	LAB → lab experience
	•	RADIOLOGY → radiology
	•	PHARMACY → pharmacy

Acceptance:
	•	Completing a stage triggers a SurveyInstance
	•	NotificationLog records outbound survey invitation
	•	Survey can be filled and responses saved

⸻

Phase 5 — Complaints/Inquiries/Feedback + Complaint Resolution Satisfaction

Deliverables:
	•	complaints app models:
	•	Complaint, ComplaintAttachment, ComplaintUpdate/Timeline
	•	Inquiry
	•	Complaint SLA: due_at computed based on severity config
	•	Complaint workflow: open → in progress → resolved → closed
	•	Complaint Resolution Satisfaction:
	•	When complaint closes, automatically send “resolution satisfaction” survey
	•	Low score triggers PXAction creation (see next phase)
	•	API endpoints and admin

Acceptance:
	•	Creating complaint triggers SLA
	•	Closing complaint triggers satisfaction survey send


Phase 6 — PX Action Center (SLA engine, escalations, evidence, approval)

Deliverables:
	•	px_action_center models:
	•	PXAction, PXActionLog, PXActionAttachment, PXActionSLAConfig, RoutingRule
	•	Automation triggers: create PXAction when:
	•	complaint created (optional config)
	•	negative stage survey score
	•	negative complaint-resolution satisfaction
	•	negative social sentiment
	•	low call center rating
	•	KPI decline (later)
	•	SLA reminders and escalation Celery tasks:
	•	reminder X hours before due
	•	escalate when overdue (assign to next level)
	•	PX review/approval:
	•	closing action requires PX role approval flag

Acceptance:
	•	Action is created automatically by at least 2 triggers
	•	Overdue escalates automatically
	•	PX approval enforced

⸻

Phase 7 — Call Center + Social Media + AI Engine (Foundations)

Deliverables:
	•	callcenter models for ratings
	•	social models for mentions
	•	ai_engine foundation:
	•	AISentimentResult model linked generically
	•	A service interface for sentiment scoring (stub)
	•	When new text enters (complaints/comments/social), create AISentimentResult via Celery task (stubbed)
	•	Negative sentiment flags drive PXActions (config)

Acceptance:
	•	Create mention → sentiment task runs → PXAction created if negative

⸻

Phase 8 — Analytics, KPIs, Dashboards, Physician Hub, QI Projects

Deliverables:
	•	analytics: KPI, KPIValue, dashboard endpoints
	•	physicians: monthly rating aggregation from surveys
	•	projects: QI projects and tasks
	•	Basic “PX Command Center” UI:
	•	active complaints count
	•	overdue actions count
	•	latest negative sentiment
	•	stage survey averages by department

Acceptance:
	•	Dashboard endpoint returns aggregated results
	•	Physician monthly rating computed for a test month

⸻

4) Detailed Business Logic Specifications

4.1 Patient Journey Definition (Key Requirement)

The system must allow PX Admin to define journeys for:
	•	EMS
	•	INPATIENT
	•	OPD

A journey is a template of ordered stages. Each stage:
	•	has trigger_event_code that maps to an incoming integration event
	•	optionally has a survey_template
	•	can automatically send survey when the stage completes

OPD Example:
	•	OPD_MD_CONSULT (trigger: OPD_VISIT_COMPLETED) → send MD survey
	•	LAB (trigger: LAB_ORDER_COMPLETED) → send Lab survey
	•	RADIOLOGY (trigger: RADIOLOGY_REPORT_FINALIZED) → send Radiology survey
	•	PHARMACY (trigger: PHARMACY_DISPENSED) → send Pharmacy survey

The journey instance is linked to an encounter_id. The same encounter can trigger multiple stages in sequence, and each stage may send its own survey.

4.2 Stage Completion Rules

When an inbound event arrives:
	1.	Identify journey instance via encounter_id
	2.	Find the first matching stage where:
	•	stage_template.trigger_event_code == event.event_code
	•	stage_instance.status != Completed
	3.	Mark it Completed with timestamps
	4.	Attach optional physician/department from payload
	5.	Audit log the completion
	6.	If stage has auto survey enabled → create survey instance and queue send task

4.3 Survey Delivery Rules
	•	Each survey invitation uses a secure signed link token
	•	Survey templates are bilingual (ar/en)
	•	Delivery channels:
	•	SMS (default)
	•	WhatsApp / Email (optional config)
	•	Sending must be Celery-based and record NotificationLog
	•	Survey responses:
	•	store per question
	•	compute summary score (template-defined scoring rules)
	•	if score below threshold → trigger PXAction

4.4 Threshold & Routing Configuration (Must Be DB-Driven)

Add models/config to control:
	•	per hospital:
	•	survey score threshold for “negative”
	•	SLA durations by priority
	•	routing rules (department manager vs PX team)
	•	per stage:
	•	auto_send_survey
	•	assigned survey template

⸻

5) APIs (Must Implement)

Implement DRF endpoints with filtering, pagination, and permissions:
	•	Auth:
	•	/api/auth/token/, /api/auth/refresh/
	•	Organizations:
	•	hospitals, departments, physicians, employees, patients
	•	Journeys:
	•	journey templates, stage templates
	•	journey instances, stage instances
	•	Integrations:
	•	inbound events create + list
	•	Surveys:
	•	templates/questions
	•	instances
	•	submit responses
	•	Complaints/Inquiries:
	•	CRUD + status transitions
	•	Action Center:
	•	actions list/detail
	•	status changes
	•	attachments/logs
	•	Call center:
	•	interactions CRUD
	•	Social:
	•	mentions CRUD
	•	Analytics:
	•	dashboard summary endpoint

Include OpenAPI/Swagger via drf-spectacular.

6) UI Templates & Admin Console (Comprehensive, Modern, Best-Practice)

You must build a modern, control-panel style web UI (Bootstrap 5 + best-practice Django templates) that provides:
	•	Comprehensive CRUD coverage for all core modules
	•	Dashboards and control panels as first-class features (not an afterthought)
	•	Fast filtering, saved views, and usable tables
	•	Action-oriented workflows: assign, escalate, close, approve, export
	•	Consistent UI layout with reusable components and partials

6.1 UI Framework and Layout Rules

Use Bootstrap 5 and implement a consistent layout system:

Base layout structure
	•	templates/layouts/base.html
	•	top navbar (global search, notifications, user menu)
	•	left sidebar navigation (module links + quick counts)
	•	main content area
	•	footer
	•	templates/layouts/partials/
	•	sidebar.html (RBAC-based nav)
	•	topbar.html
	•	breadcrumbs.html
	•	flash_messages.html
	•	filters_panel.html (collapsible)
	•	pagination.html
	•	table_toolbar.html (export, bulk actions)
	•	stat_cards.html (dashboard metric cards)
	•	charts_panel.html
	•	modal_form.html (optional)

Front-end best practices
	•	Use Bootstrap components: cards, offcanvas/accordion, badges, progress bars, nav tabs, modals, tooltips.
	•	Use DataTables (or a lightweight alternative) for advanced tables:
	•	search, sorting, server-side pagination where needed
	•	column toggles
	•	export actions
	•	Use Select2 for all large foreign-key selects (patients, departments, physicians, staff).
	•	Use HTMX (recommended) for partial updates:
	•	filters update list without full refresh
	•	status changes inline (e.g., close action)
	•	quick assign from list view
	•	Use Chart.js or ApexCharts for dashboards:
	•	trends, distributions, leaderboards, time series
	•	Ensure RTL-ready templates (Arabic support):
	•	Provide an RTL base CSS toggle and dir="rtl" handling.
	•	Accessibility:
	•	proper labels, aria, keyboard-friendly forms

6.2 UI Apps Coverage (Full CRUD + Control Panels)

You must implement full UI pages for:

A) PX Command Center Dashboard (Group-Level Real-Time Control Panel)
Create a primary dashboard: dashboard/command-center/

It must include:

Top KPI strip (cards)
	•	Active complaints
	•	Overdue complaints (SLA breach)
	•	Open PX actions
	•	Overdue PX actions
	•	Negative stage surveys (last 24h / 7d)
	•	Negative social mentions
	•	Call center low ratings
	•	Complaint resolution dissatisfaction rate

Charts (interactive)
	•	Complaints trend by day/week/month
	•	SLA compliance trend (complaints + actions)
	•	Survey satisfaction averages by stage (OPD MD / LAB / Radiology / Pharmacy)
	•	Sentiment distribution (positive/neutral/negative)
	•	Department leaderboard (best/worst)
	•	Physician leaderboard (best/worst)

Live feed widgets
	•	Latest high severity complaints
	•	Latest escalated actions
	•	Latest negative comments/mentions with quick “Create Action” button
	•	Stage events log stream (latest integration events processed)

Filters (persisted)
	•	Date range
	•	Hospital
	•	Department
	•	Journey type (EMS/Inpatient/OPD)
	•	Source (HIS/MOH/CHI/PXConnect/Social/Internal)

Actions
	•	Quick create complaint
	•	Quick create action
	•	Export dashboard snapshot (PDF/Excel)

RBAC rules:
	•	PX Admin can see all
	•	Hospital admin sees their hospital only
	•	Department manager sees their department only

⸻

B) Complaints Console (Complete CRUD + Workflow + SLA)
Provide a full complaints module UI:

Pages
	1.	Complaints List

	•	table with advanced filters:
	•	status, severity, priority, SLA status (due soon / overdue)
	•	source
	•	hospital, department
	•	physician (optional)
	•	date range
	•	bulk actions:
	•	assign to department/staff
	•	change status
	•	export selected
	•	quick actions from row:
	•	“View”
	•	“Assign”
	•	“Escalate”
	•	“Add Note”
	•	“Close”
	•	SLA badges and progress indicator

	2.	Complaint Create / Edit form

	•	structured form sections:
	•	patient info (select patient or enter MRN)
	•	encounter linking (encounter_id)
	•	classification (category/subcategory)
	•	description + attachments
	•	assignment + priority
	•	Use Select2 for patient/department/physician

	3.	Complaint Detail View (Case Management)

	•	case header (status, SLA countdown, assigned owner)
	•	timeline feed (updates, status changes, attachments, notes)
	•	tabs:
	•	Details
	•	Timeline
	•	Attachments
	•	Related Journey Stages & Surveys
	•	Actions (linked PX actions)
	•	Buttons:
	•	assign, escalate, change status
	•	“Trigger Resolution Satisfaction Survey” (admin only)
	•	“Create Action” (if not already)
	•	SLA indicator + audit log summary

	4.	Complaint Resolution Satisfaction Dashboard

	•	score distribution
	•	by department/hospital
	•	dissatisfied list with drill-down

Exports
	•	export list or selected complaints to CSV/Excel/PDF

⸻

C) PX Action Center Console (Operational Hub)
This must be a control room UI, not just CRUD.

Pages
	1.	Action Center Board (List + Advanced Filters)

	•	filters: status, SLA, priority, type/source, department, assignee
	•	views: “My Actions”, “Overdue”, “Escalated”, “New from Surveys”, “From Complaints”, “From Social”
	•	bulk actions:
	•	assign
	•	update status
	•	escalate
	•	row quick actions:
	•	open
	•	change status
	•	attach evidence
	•	request approval

	2.	Action Detail View (Workflow + Evidence + Approval)

	•	action header: SLA progress bar, owner, linked source object
	•	tabs:
	•	Details
	•	Evidence & Attachments
	•	Discussion / Logs
	•	SLA History
	•	Approval
	•	approval flow:
	•	department closes → PX reviews/approves
	•	prevent closure without required evidence if configured
	•	show related complaints/surveys/mentions

	3.	SLA Control Panel (Admin)

	•	manage SLA configs by:
	•	priority/severity
	•	department/hospital
	•	manage escalation rules (who gets escalated next)

⸻

D) Patient Journey Console (Templates + Instances + Monitoring)
This must be comprehensive because it’s core to your survey logic.

Journey Template Builder UI
	•	Journey templates list (EMS/Inpatient/OPD)
	•	Create/edit template
	•	Stage builder:
	•	reorder stages (drag-drop if possible, else order field)
	•	set trigger_event_code
	•	set auto_send_survey
	•	bind survey template
	•	require physician or not
	•	Test panel:
	•	simulate event code on a test encounter to validate mapping

Journey Instances Monitoring
	•	Instances list with filters:
	•	journey type
	•	hospital/department
	•	stage status
	•	encounter_id
	•	patient MRN
	•	Instance detail:
	•	progress stepper (stages in sequence)
	•	each stage card shows:
	•	status (pending/in progress/completed)
	•	completion time
	•	linked dept/physician
	•	survey instance status + link
	•	“Send survey now” (admin) / “Resend invitation”
	•	event history timeline:
	•	inbound events used to complete stages
	•	analytics snapshot:
	•	average score per stage
	•	negative flags

⸻

E) Surveys Console (Templates + Instances + Analytics)
This is not just forms — it’s a survey control center.

Survey Templates
	•	list templates
	•	create/edit template
	•	question builder:
	•	add question
	•	reorder
	•	bilingual text
	•	type
	•	required
	•	branch logic UI (simple JSON editor acceptable, but validate JSON)

Survey Instances
	•	list/filter instances (status, journey type, stage)
	•	detail view:
	•	invitation status
	•	responses
	•	computed score
	•	sentiment results
	•	“Create Action” if negative

Survey Analytics Dashboard
	•	satisfaction by:
	•	hospital
	•	department
	•	physician
	•	journey type
	•	stage
	•	trends over time
	•	negative survey heatmap by department/stage

⸻

F) Survey Public Form (Token Link — Modern UX)
This page is used by patients; it must be mobile-first and clean.

Requirements:
	•	token-based access (signed token)
	•	bilingual toggle (Arabic/English)
	•	progress indicator
	•	validation and friendly error messages
	•	thank-you page
	•	optional NPS style components
	•	should work beautifully on mobile

⸻

G) Social Media Monitoring Console
	•	mentions feed with filters (platform, sentiment, hospital)
	•	sentiment trend chart
	•	“Create Action” button per negative mention
	•	mention detail page with AI sentiment breakdown

⸻

H) Call Center Ratings Console
	•	interactions list + filters (agent, dept, score range)
	•	dashboard:
	•	avg waiting time
	•	avg satisfaction
	•	lowest performing agents/depts
	•	“Create Action” on low rating

⸻

I) Analytics / KPI Admin Console
	•	KPI definitions CRUD
	•	KPI values list
	•	KPI dashboard:
	•	threshold breaches
	•	trend lines
	•	department rankings
	•	ability to trigger actions from KPI breaches

⸻

J) Admin “System Configuration” Console
Provide a UI for:
	•	routing rules (where actions go)
	•	thresholds (negative survey threshold, dissatisfaction threshold)
	•	notification gateways configuration (toggle SMS/WhatsApp/email modes)
	•	integration endpoint configs (placeholders)

⸻

6.3 UI Architecture Requirements (Don’t Skip)
	•	Use Django Class-Based Views + ModelForm best practices.
	•	Use Form validation + server-side errors displayed in UI.
	•	Use reusable template patterns:
	•	*_list.html, *_detail.html, *_form.html, partials/*
	•	Use consistent breadcrumb navigation.
	•	Use consistent UI status badges:
	•	Open/Closed/Overdue/Completed
	•	Add “Empty state” designs when no data exists.
	•	Add “Saved filters”:
	•	store user filter presets (DB model SavedViewFilter)
	•	Add Export:
	•	CSV/Excel for lists
	•	PDF for detail summary

6.4 Performance Requirements for UI
	•	Use server-side pagination everywhere for large lists.
	•	Use indexes in DB for filtering fields (status, dates, hospital, department).
	•	Use select_related/prefetch_related in views.

6.5 Acceptance Criteria for UI (Must Pass)

By the end:
	•	Every core model has full CRUD pages (create/list/detail/edit/delete where safe).
	•	Dashboards show real aggregated metrics (not placeholder values).
	•	Action Center supports assignment, evidence upload, closure approval.
	•	Journey builder can define stages and link surveys.
	•	Journey instance view shows stage progression and survey status.
	•	Public survey form works via token and saves responses.
	•	UI is consistent, modern, and usable as a control panel.


7) Security & Compliance
	•	RBAC: enforce in DRF permission classes
	•	Audit logs for critical events
	•	Data encryption: document at-rest & in-transit expectations
	•	Data residency: mention KSA hosting requirement in docs
	•	Rate-limit integration endpoint if possible (simple middleware or DRF throttle)

⸻

8) Deliverables Checklist (Must Produce)

When finished, ensure the repository includes:
	•	Full Django project with apps
	•	Migrations for all apps
	•	Admin configuration
	•	DRF APIs + permissions
	•	Celery tasks for events, survey sending, SLA reminders
	•	Docker setup
	•	.env.example
	•	README.md
	•	/docs/ including:
	•	Architecture overview
	•	Journey & survey engine explanation
	•	Integration event contracts (example payload JSON)
	•	SLA and routing config explanation
	•	Minimal tests verifying:
	•	event completes stage
	•	stage triggers survey
	•	negative survey triggers action
	•	overdue action escalates (can be tested with time override)

⸻

9) Final Output Requirements

At the end, provide:
	1.	A list of created apps and their responsibilities
	2.	Key endpoints list
	3.	How to run locally (docker compose)
	4.	Example API calls:
	•	create journey template
	•	create encounter journey instance
	•	post event to complete stage
	•	verify survey send log

⸻

10) Start Now

Proceed phase-by-phase.
After each phase:
	•	run migrations
	•	run basic tests
	•	confirm acceptance criteria met
	•	then continue.

Do not jump ahead.
Do not leave broken code.
Do not omit the journey-stage survey requirement.