agdar/HR_INTEGRATIONS_PROGRESS_REPORT.md

HR & Integrations Frontend Implementation Progress Report

Date: October 22, 2025
Project: AgdarCentre - Tenhal Multidisciplinary Healthcare Platform

---

Executive Summary

This report documents the current state of the HR and Integrations modules, identifying what exists in the Django admin vs. what's missing from the frontend implementation.

---

1. HR Module Analysis

Current Status: ❌ NOT IMPLEMENTED

The HR module does not exist as a Django app. Only orphaned templates are present.

What EXISTS:

• ✅ 10 HTML Templates in templates/hr/:
  • attendance_list.html
  • attendance_form.html
  • attendance_detail.html
  • attendance_kiosk.html
  • schedule_list.html
  • schedule_form.html
  • schedule_detail.html
  • schedule_grid.html
  • holiday_list.html
  • holiday_form.html
  • holiday_detail.html

What's MISSING:

1.1 Django App Structure

• ❌ No hr/ app directory
• ❌ No hr/__init__.py
• ❌ No hr/apps.py
• ❌ No hr/models.py
• ❌ No hr/views.py
• ❌ No hr/urls.py
• ❌ No hr/admin.py
• ❌ No hr/forms.py
• ❌ No hr/migrations/

1.2 Required Models (Based on Template Analysis)

Attendance Model:

class Attendance(models.Model):
    employee = ForeignKey(User)  # or separate Employee model
    date = DateField()
    check_in = TimeField()
    check_out = TimeField(null=True, blank=True)
    hours_worked = DecimalField()  # calculated
    status = CharField(choices=['PRESENT', 'LATE', 'ABSENT', 'HALF_DAY'])
    notes = TextField(blank=True)

Schedule Model:

class Schedule(models.Model):
    employee = ForeignKey(User)
    day_of_week = CharField(choices=['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'])
    start_time = TimeField()
    end_time = TimeField()
    is_active = BooleanField(default=True)

Holiday Model:

class Holiday(models.Model):
    name = CharField(max_length=200)
    date = DateField()
    is_recurring = BooleanField(default=False)  # for annual holidays
    description = TextField(blank=True)

1.3 Required Views

• ❌ AttendanceListView
• ❌ AttendanceCreateView
• ❌ AttendanceDetailView
• ❌ AttendanceUpdateView
• ❌ AttendanceKioskView (special clock in/out interface)
• ❌ ScheduleListView
• ❌ ScheduleCreateView
• ❌ ScheduleDetailView
• ❌ ScheduleUpdateView
• ❌ ScheduleGridView (calendar-style view)
• ❌ HolidayListView
• ❌ HolidayCreateView
• ❌ HolidayDetailView
• ❌ HolidayUpdateView

1.4 Required URL Patterns

# Expected URL namespace: 'hr'
urlpatterns = [
    path('attendance/', AttendanceListView, name='attendance-list'),
    path('attendance/create/', AttendanceCreateView, name='attendance-create'),
    path('attendance/<uuid:pk>/', AttendanceDetailView, name='attendance-detail'),
    path('attendance/<uuid:pk>/update/', AttendanceUpdateView, name='attendance-update'),
    path('attendance/kiosk/', AttendanceKioskView, name='attendance-kiosk'),
    
    path('schedules/', ScheduleListView, name='schedule-list'),
    path('schedules/create/', ScheduleCreateView, name='schedule-create'),
    path('schedules/<uuid:pk>/', ScheduleDetailView, name='schedule-detail'),
    path('schedules/<uuid:pk>/update/', ScheduleUpdateView, name='schedule-update'),
    path('schedules/grid/', ScheduleGridView, name='schedule-grid'),
    
    path('holidays/', HolidayListView, name='holiday-list'),
    path('holidays/create/', HolidayCreateView, name='holiday-create'),
    path('holidays/<uuid:pk>/', HolidayDetailView, name='holiday-detail'),
    path('holidays/<uuid:pk>/update/', HolidayUpdateView, name='holiday-update'),
]

1.5 Main URLs Integration

• ❌ Not included in AgdarCentre/urls.py
• Need to add: path('hr/', include('hr.urls'))

1.6 Forms

• ❌ AttendanceForm
• ❌ ScheduleForm
• ❌ HolidayForm

1.7 Admin Configuration

• ❌ Admin classes for all three models

---

2. Integrations Module Analysis

Current Status: ⚠️ BACKEND COMPLETE, FRONTEND MISSING

The integrations app exists with full backend implementation but zero frontend integration.

What EXISTS:

2.1 Complete Backend ✅

• ✅ Django app structure (integrations/)

• ✅ 6 Models fully implemented:

  1. ExternalOrder - Lab & radiology orders
  2. NphiesMessage - Insurance e-claims FHIR messages
  3. NphiesEncounterLink - Links appointments to NPHIES
  4. PayerContract - Insurance payer configurations
  5. EInvoice - ZATCA e-invoicing
  6. ZatcaCredential - ZATCA credentials management

• ✅ Admin Interface - Fully configured for all 6 models with:

  • List displays
  • Filters
  • Search fields
  • Fieldsets
  • Read-only fields

• ✅ Supporting Files:

  • messaging_service.py - SMS/WhatsApp integration
  • sms_providers.py - SMS provider implementations
  • tasks.py - Celery tasks for async operations

What's MISSING:

2.2 Frontend Components ❌

Views (integrations/views.py): Currently only contains: from django.shortcuts import render with no actual views.

Required views:

• ❌ ExternalOrderListView
• ❌ ExternalOrderCreateView
• ❌ ExternalOrderDetailView
• ❌ ExternalOrderUpdateView
• ❌ NphiesMessageListView
• ❌ NphiesMessageDetailView
• ❌ PayerContractListView
• ❌ PayerContractCreateView
• ❌ PayerContractUpdateView
• ❌ EInvoiceListView
• ❌ EInvoiceDetailView
• ❌ ZatcaCredentialListView
• ❌ ZatcaCredentialCreateView

Templates:

• ❌ integrations/templates/ directory exists but is empty

Required templates:

• ❌ integrations/external_order_list.html
• ❌ integrations/external_order_form.html
• ❌ integrations/external_order_detail.html
• ❌ integrations/nphies_message_list.html
• ❌ integrations/nphies_message_detail.html
• ❌ integrations/payer_contract_list.html
• ❌ integrations/payer_contract_form.html
• ❌ integrations/einvoice_list.html
• ❌ integrations/einvoice_detail.html
• ❌ integrations/zatca_credential_list.html
• ❌ integrations/zatca_credential_form.html

Forms:

• ❌ No integrations/forms.py file

Required forms:

• ❌ ExternalOrderForm
• ❌ PayerContractForm
• ❌ ZatcaCredentialForm

URLs:

• ❌ No integrations/urls.py file
• ❌ Not included in AgdarCentre/urls.py

Required URL patterns:

# Expected URL namespace: 'integrations'
urlpatterns = [
    # External Orders
    path('orders/', ExternalOrderListView, name='order-list'),
    path('orders/create/', ExternalOrderCreateView, name='order-create'),
    path('orders/<uuid:pk>/', ExternalOrderDetailView, name='order-detail'),
    
    # NPHIES
    path('nphies/messages/', NphiesMessageListView, name='nphies-message-list'),
    path('nphies/messages/<uuid:pk>/', NphiesMessageDetailView, name='nphies-message-detail'),
    path('nphies/payers/', PayerContractListView, name='payer-list'),
    path('nphies/payers/create/', PayerContractCreateView, name='payer-create'),
    
    # ZATCA
    path('zatca/invoices/', EInvoiceListView, name='einvoice-list'),
    path('zatca/invoices/<uuid:pk>/', EInvoiceDetailView, name='einvoice-detail'),
    path('zatca/credentials/', ZatcaCredentialListView, name='credential-list'),
    path('zatca/credentials/create/', ZatcaCredentialCreateView, name='credential-create'),
]

Navigation:

• ❌ No menu items in main navigation
• ❌ No dashboard widgets/cards

---

3. Implementation Priority Recommendations

Phase 1: Integrations (EASIER - Backend exists)

Estimated Effort: 2-3 days

1. Create integrations/forms.py with ModelForms
2. Create integrations/views.py with generic CRUD views
3. Create templates following existing app patterns
4. Create integrations/urls.py and wire to main URLs
5. Add navigation menu items
6. Add dashboard cards for quick access

Complexity: Low - Models and admin already exist, just need frontend

---

Phase 2: HR Module (HARDER - Start from scratch)

Estimated Effort: 3-4 days

1. Create Django app: python manage.py startapp hr
2. Design and implement 3 models (Attendance, Schedule, Holiday)
3. Create and run migrations
4. Configure admin interface
5. Create forms
6. Create views (generic CRUD + special views for kiosk and grid)
7. Create hr/urls.py and wire to main URLs
8. Wire existing templates to new views
9. Add navigation menu items
10. Add dashboard cards

Complexity: Medium - Full app creation but simple models

---

4. Model Field Details (Based on Template Analysis)

HR Models - Detailed Field Requirements

Attendance Model

class Attendance(UUIDPrimaryKeyMixin, TimeStampedMixin, TenantOwnedMixin):
    employee = ForeignKey('core.User', on_delete=CASCADE, related_name='attendances')
    date = DateField()
    check_in = TimeField(null=True, blank=True)
    check_out = TimeField(null=True, blank=True)
    hours_worked = DecimalField(max_digits=4, decimal_places=2, null=True, blank=True)
    status = CharField(max_length=20, choices=Status.choices)
    notes = TextField(blank=True)
    
    class Status(TextChoices):
        PRESENT = 'PRESENT', _('Present')
        LATE = 'LATE', _('Late')
        ABSENT = 'ABSENT', _('Absent')
        HALF_DAY = 'HALF_DAY', _('Half Day')
        LEAVE = 'LEAVE', _('On Leave')

Schedule Model

class Schedule(UUIDPrimaryKeyMixin, TimeStampedMixin, TenantOwnedMixin):
    employee = ForeignKey('core.User', on_delete=CASCADE, related_name='schedules')
    day_of_week = CharField(max_length=3, choices=DayOfWeek.choices)
    start_time = TimeField()
    end_time = TimeField()
    is_active = BooleanField(default=True)
    
    class DayOfWeek(TextChoices):
        MONDAY = 'MON', _('Monday')
        TUESDAY = 'TUE', _('Tuesday')
        WEDNESDAY = 'WED', _('Wednesday')
        THURSDAY = 'THU', _('Thursday')
        FRIDAY = 'FRI', _('Friday')
        SATURDAY = 'SAT', _('Saturday')
        SUNDAY = 'SUN', _('Sunday')

Holiday Model

class Holiday(UUIDPrimaryKeyMixin, TimeStampedMixin, TenantOwnedMixin):
    name = CharField(max_length=200)
    date = DateField()
    is_recurring = BooleanField(default=False)
    description = TextField(blank=True)

---

5. Summary Statistics

HR Module

• Models to Create: 3
• Views to Create: 14
• Forms to Create: 3
• Templates Available: 10 (already exist!)
• Admin Classes to Create: 3
• URL Patterns to Create: ~14
• Overall Completion: 0% (only templates exist)

Integrations Module

• Models Existing: 6 ✅
• Admin Classes Existing: 6 ✅
• Views to Create: 12
• Forms to Create: 3
• Templates to Create: 11
• URL Patterns to Create: ~12
• Overall Completion: 40% (backend complete, frontend missing)

---

6. Next Steps

Immediate Actions Required:

1. Decision Point: Which module to implement first?

   • Recommendation: Start with Integrations (easier, backend exists)

2. For Integrations:

   • Create forms.py
   • Create views.py with CRUD views
   • Create templates
   • Create urls.py
   • Update main urls.py
   • Add navigation

3. For HR:

   • Create Django app
   • Implement models
   • Run migrations
   • Create admin
   • Create forms
   • Create views
   • Create urls.py
   • Update main urls.py
   • Add navigation

---

7. Technical Notes

Design Patterns to Follow:

• Use existing app patterns (appointments, finance, etc.)
• Follow Django generic views (ListView, CreateView, DetailView, UpdateView)
• Use crispy-forms for form rendering
• Maintain bilingual support (English/Arabic)
• Include tenant filtering
• Add proper permissions/access control
• Follow existing URL naming conventions

Dependencies:

• All required packages already installed
• No additional dependencies needed
• Templates follow Bootstrap 5 patterns
• Font Awesome icons already available

---

Report Generated: October 22, 2025
Status: Ready for Implementation