agdar/PHASE7_SIGNALS_SERVICES_TASKS.md

Phase 7: Signals, Services & Tasks Implementation Plan

Overview

Phase 7 focuses on implementing Django signals for automation, service layer for business logic separation, and Celery tasks for background processing in the Tenhal Multidisciplinary Healthcare Platform.

Objectives

1. Django Signals - Automate audit logging, notifications, and workflow triggers
2. Service Layer - Separate business logic from views for better maintainability
3. Celery Tasks - Background processing for reminders, reports, and integrations
4. Scheduled Jobs - Periodic tasks using Celery Beat

Implementation Checklist

Part 1: Celery Setup & Configuration (30 minutes)

• Celery already configured in settings.py
• Create AgdarCentre/celery.py - Celery app initialization
• Update AgdarCentre/__init__.py - Import Celery app
• Create .env entries for Redis configuration
• Test Celery worker connection

Part 2: Django Signals (2-3 hours)

Core App Signals

• Create core/signals.py
  • post_save signal for Patient - Create audit log entry
  • post_save signal for User - Send welcome email
  • pre_delete signal for Patient - Soft delete implementation
  • post_save signal for Consent - Notify relevant staff

Appointments App Signals

• Create appointments/signals.py
  • post_save signal for Appointment - Status change notifications
  • post_save signal for Appointment (CONFIRMED) - Schedule reminder task
  • post_save signal for Appointment (COMPLETED) - Trigger invoice generation
  • post_save signal for Appointment (CANCELLED) - Cancel reminders
  • pre_save signal for Appointment - Validate time slot conflicts

Finance App Signals

• Create finance/signals.py
  • post_save signal for Payment - Update invoice status
  • post_save signal for Invoice (ISSUED) - Send invoice notification
  • post_save signal for Invoice (OVERDUE) - Schedule overdue reminder
  • post_save signal for Payment (COMPLETED) - Send receipt

Referrals App Signals

• Create referrals/signals.py
  • post_save signal for Referral (PENDING) - Notify receiving clinic
  • post_save signal for Referral (ACCEPTED) - Notify sending clinic
  • post_save signal for Referral (REJECTED) - Notify sending clinic
  • post_save signal for Referral (COMPLETED) - Update statistics

Part 3: Service Layer (3-4 hours)

Core Services

• Create core/services.py
  • PatientService class
    • create_patient() - Patient creation with validation
    • update_patient() - Patient update with audit
    • merge_patients() - Merge duplicate patients
    • get_patient_summary() - Complete patient overview
  • FileService class
    • create_file() - File creation with auto-numbering
    • close_file() - File closure workflow
    • reopen_file() - File reopening workflow

Appointments Services

• Create appointments/services.py
  • AppointmentService class
    • book_appointment() - Complete booking workflow
    • confirm_appointment() - Confirmation with validation
    • reschedule_appointment() - Reschedule with conflict check
    • cancel_appointment() - Cancellation with reason
    • check_availability() - Provider availability check
    • get_calendar_slots() - Calendar view generation
  • ScheduleService class
    • create_schedule() - Schedule creation
    • check_conflicts() - Conflict detection
    • get_available_slots() - Available time slots

Finance Services

• Create finance/services.py
  • InvoiceService class
    • generate_invoice() - Auto-generate from appointment
    • issue_invoice() - Issue draft invoice
    • calculate_totals() - Calculate invoice totals
    • apply_discount() - Apply discount logic
    • mark_paid() - Mark invoice as paid
  • PaymentService class
    • process_payment() - Payment processing
    • refund_payment() - Refund processing
    • allocate_payment() - Allocate to invoices
  • PackageService class
    • activate_package() - Activate patient package
    • consume_session() - Consume package session
    • check_balance() - Check remaining sessions

Referrals Services

• Create referrals/services.py
  • ReferralService class
    • create_referral() - Referral creation with validation
    • accept_referral() - Accept workflow
    • reject_referral() - Reject workflow
    • complete_referral() - Complete workflow
    • check_auto_rules() - Check auto-referral rules
    • get_referral_statistics() - Statistics calculation

Part 4: Celery Tasks (3-4 hours)

Notification Tasks

• Create core/tasks.py
  • send_email_task() - Async email sending
  • send_sms_task() - Async SMS sending
  • send_whatsapp_task() - Async WhatsApp sending
  • create_notification_task() - Create in-app notification

Appointment Tasks

• Create appointments/tasks.py
  • send_appointment_reminder() - Send reminder (24h, 2h before)
  • send_appointment_confirmation() - Send confirmation
  • check_no_shows() - Check and mark no-shows
  • generate_daily_schedule() - Generate daily schedule report
  • sync_calendar() - Sync with external calendar (future)

Finance Tasks

• Create finance/tasks.py
  • generate_invoice_from_appointment() - Auto-generate invoice
  • send_invoice_notification() - Send invoice to patient
  • check_overdue_invoices() - Check and notify overdue
  • send_payment_receipt() - Send payment receipt
  • generate_financial_report() - Generate periodic reports
  • process_batch_payments() - Process batch payments

Referral Tasks

• Create referrals/tasks.py
  • send_referral_notification() - Notify receiving clinic
  • check_pending_referrals() - Check pending referrals
  • send_referral_reminder() - Remind about pending referrals
  • update_referral_statistics() - Update statistics

Integration Tasks

• Create integrations/tasks.py
  • submit_nphies_eligibility() - NPHIES eligibility check
  • submit_nphies_prior_auth() - NPHIES prior authorization
  • submit_nphies_claim() - NPHIES claim submission
  • submit_zatca_invoice() - ZATCA e-invoice submission
  • sync_lab_results() - Sync lab results
  • sync_radiology_results() - Sync radiology results

Part 5: Celery Beat Scheduled Tasks (1-2 hours)

Periodic Tasks Configuration

• Create appointments/beat_schedule.py

  • Daily at 8:00 AM - Send appointment reminders for today
  • Every 2 hours - Check for no-shows
  • Daily at 6:00 PM - Generate next day schedule

• Create finance/beat_schedule.py

  • Daily at 9:00 AM - Check overdue invoices
  • Weekly on Monday - Generate weekly financial report
  • Monthly on 1st - Generate monthly financial report

• Create referrals/beat_schedule.py

  • Daily at 10:00 AM - Check pending referrals
  • Weekly on Friday - Send referral statistics

• Create integrations/beat_schedule.py

  • Every 30 minutes - Sync lab results
  • Every 30 minutes - Sync radiology results
  • Daily at 11:00 PM - Submit pending ZATCA invoices

Part 6: Testing & Validation (2-3 hours)

Signal Tests

• Create tests/test_signals.py
  • Test patient creation triggers audit log
  • Test appointment confirmation triggers reminder
  • Test payment triggers invoice update
  • Test referral creation triggers notification

Service Tests

• Create tests/test_services.py
  • Test appointment booking service
  • Test invoice generation service
  • Test payment processing service
  • Test referral workflow service

Task Tests

• Create tests/test_tasks.py
  • Test email sending task
  • Test reminder task
  • Test invoice generation task
  • Test integration tasks

Integration Tests

• Test complete workflows
  • Book appointment → Generate invoice → Send reminder
  • Create referral → Notify → Accept → Complete
  • Issue invoice → Process payment → Send receipt

Part 7: Documentation (1 hour)

• Create SIGNALS_REFERENCE.md - Signal documentation
• Create SERVICES_REFERENCE.md - Service layer documentation
• Create TASKS_REFERENCE.md - Celery tasks documentation
• Update README.md - Add Celery setup instructions
• Create CELERY_DEPLOYMENT.md - Production deployment guide

File Structure

AgdarCentre/
├── celery.py                    # Celery app initialization
├── __init__.py                  # Import Celery app
│
core/
├── signals.py                   # Core app signals
├── services.py                  # Core business services
├── tasks.py                     # Core Celery tasks
│
appointments/
├── signals.py                   # Appointment signals
├── services.py                  # Appointment services
├── tasks.py                     # Appointment tasks
├── beat_schedule.py             # Scheduled tasks
│
finance/
├── signals.py                   # Finance signals
├── services.py                  # Finance services
├── tasks.py                     # Finance tasks
├── beat_schedule.py             # Scheduled tasks
│
referrals/
├── signals.py                   # Referral signals
├── services.py                  # Referral services
├── tasks.py                     # Referral tasks
├── beat_schedule.py             # Scheduled tasks
│
integrations/
├── signals.py                   # Integration signals
├── services.py                  # Integration services
├── tasks.py                     # Integration tasks
├── beat_schedule.py             # Scheduled tasks
│
tests/
├── test_signals.py              # Signal tests
├── test_services.py             # Service tests
├── test_tasks.py                # Task tests

Key Design Patterns

1. Signal Pattern

from django.db.models.signals import post_save
from django.dispatch import receiver

@receiver(post_save, sender=Appointment)
def appointment_confirmed(sender, instance, created, **kwargs):
    if not created and instance.status == 'CONFIRMED':
        # Schedule reminder task
        send_appointment_reminder.apply_async(
            args=[instance.id],
            eta=instance.start_time - timedelta(hours=24)
        )

2. Service Layer Pattern

class AppointmentService:
    @staticmethod
    def book_appointment(patient, provider, start_time, **kwargs):
        # Validate availability
        if not AppointmentService.check_availability(provider, start_time):
            raise ValidationError("Time slot not available")
        
        # Create appointment
        appointment = Appointment.objects.create(
            patient=patient,
            provider=provider,
            start_time=start_time,
            **kwargs
        )
        
        # Trigger post-creation tasks
        send_appointment_confirmation.delay(appointment.id)
        
        return appointment

3. Celery Task Pattern

from celery import shared_task

@shared_task(bind=True, max_retries=3)
def send_appointment_reminder(self, appointment_id):
    try:
        appointment = Appointment.objects.get(id=appointment_id)
        # Send reminder logic
        send_sms(appointment.patient.phone, f"Reminder: {appointment}")
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)

Dependencies Already Installed

✅ celery>=5.3.4 ✅ redis>=5.0.1 ✅ django-celery-beat>=2.5.0 ✅ django-celery-results>=2.5.1

Environment Variables Needed

Add to .env:

# Celery Configuration
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# Email Configuration (for notifications)
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL=noreply@agdarcentre.sa

# SMS Configuration (Twilio)
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_WHATSAPP_NUMBER=whatsapp:+1234567890

Running Celery

Development

# Terminal 1: Start Redis
redis-server

# Terminal 2: Start Celery Worker
celery -A AgdarCentre worker -l info

# Terminal 3: Start Celery Beat (for scheduled tasks)
celery -A AgdarCentre beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler

# Terminal 4: Start Django
python manage.py runserver

Production

# Use supervisor or systemd to manage processes
# See CELERY_DEPLOYMENT.md for details

Expected Benefits

1. Automation

   • Automatic appointment reminders
   • Auto-generated invoices
   • Automated notifications
   • Scheduled reports

2. Performance

   • Background processing of heavy tasks
   • Non-blocking email/SMS sending
   • Async integration calls
   • Improved response times

3. Maintainability

   • Separated business logic in services
   • Reusable service methods
   • Testable components
   • Clear code organization

4. Reliability

   • Task retry mechanisms
   • Error handling and logging
   • Transaction management
   • Audit trail automation

Timeline Estimate

• Part 1: Celery Setup - 30 minutes
• Part 2: Signals - 2-3 hours
• Part 3: Services - 3-4 hours
• Part 4: Tasks - 3-4 hours
• Part 5: Beat Schedule - 1-2 hours
• Part 6: Testing - 2-3 hours
• Part 7: Documentation - 1 hour

Total: 13-18 hours (2-3 days)

Success Criteria

• All signals properly connected and tested
• Service layer methods working correctly
• Celery tasks executing successfully
• Scheduled tasks running on time
• Email/SMS notifications working
• Integration tasks functioning
• Comprehensive test coverage
• Complete documentation

Next Phase Preview

Phase 8: Admin, RBAC & Auditing

• Custom Django admin interfaces
• Enhanced role-based permissions
• Detailed audit trails
• Compliance reporting
• User activity monitoring

---

Status: Ready to implement Priority: High (enables automation and background processing) Dependencies: Phase 6 (APIs) completed ✅