Chapter 7: Staff Management

The Staff Management module in NDSS CRM provides a complete human resources and workforce management solution tailored for NDIS and disability care providers. It covers the full employee lifecycle from onboarding through to separation, including qualification tracking, availability management, role assignment, and performance monitoring. The module is built using Next.js and React with TypeScript for the front end, Python services for business logic and reporting, PHP for legacy HR integrations, and PostgreSQL as the primary data store.

7.1 Staff Directory

The Staff Directory is the central hub for managing all employees within the organisation. It provides a searchable, filterable list of all staff members with key information displayed in a table format. The directory supports server-side pagination, full-text search, and multi-criteria filtering.

7.1.1 Staff Directory Wireframe

7.1.2 Staff Directory Table Columns

7.2 Adding New Staff

The staff onboarding form captures all essential information required to create a new employee record. The form is divided into logical sections and includes validation rules to ensure data completeness and accuracy. Upon successful creation, the new staff member receives an automated welcome email with login credentials and onboarding instructions.

7.2.1 Staff Onboarding Form Wireframe

7.2.2 Form Field Specifications

7.2.3 Onboarding Workflow

When a new staff member is created, the following automated workflow is triggered:

1. Record Creation - Staff record is persisted to PostgreSQL with status onboarding.
2. User Account - A Supabase / Oracle Auth user account is created with a temporary password.
3. Welcome Email - A Python email service sends a welcome email with login credentials, password reset link, and onboarding checklist.
4. Onboarding Checklist - The system generates a task checklist including: upload certifications, complete profile, set availability, review policies.
5. Role Assignment - The user is assigned the appropriate system role with corresponding permissions.
6. Notification - The HR manager and direct supervisor receive a notification that a new staff member has been onboarded.

# Python Onboarding Service
class StaffOnboardingService:
    def onboard_new_staff(self, staff_data: dict) -> dict:
        # 1. Create staff record
        staff = self.staff_repository.create(staff_data)

        # 2. Create auth user account via Supabase / Oracle
        auth_user = self.supabase.auth.admin.create_user({
            'email': staff_data['email'],
            'password': generate_temp_password(),
            'user_metadata': {
                'staff_id': str(staff.id),
                'role': staff_data['role'],
                'org_id': str(staff_data['org_id']),
            }
        })

        # 3. Send welcome email
        self.email_service.send_welcome_email(
            to=staff_data['email'],
            name=f"{staff_data['first_name']} {staff_data['last_name']}",
            temp_password=auth_user.temp_password,
            reset_link=f"{BASE_URL}/auth/reset-password?token={auth_user.reset_token}"
        )

        # 4. Generate onboarding checklist
        self.checklist_service.create_onboarding_checklist(staff.id)

        # 5. Assign role permissions
        self.permission_service.assign_role(auth_user.id, staff_data['role'])

        # 6. Notify stakeholders
        self.notification_service.notify_new_staff(staff)

        return {'staff_id': str(staff.id), 'user_id': auth_user.id}

7.3 Staff Profile

The Staff Profile page provides a comprehensive view of all information related to an individual staff member. It uses a tabbed interface with five sections: Overview, Qualifications, Shifts, Availability, and Documents.

7.3.1 Staff Profile Wireframe

7.3.2 Profile Tab Descriptions

7.4 Qualification & Certification Tracking

Qualification and certification tracking is a critical compliance function in NDIS service delivery. NDSS CRM maintains a comprehensive registry of all required certifications for each staff member, with automated expiry monitoring and alert generation. The system ensures that no staff member can be rostered for shifts if they have expired mandatory certifications.

7.4.1 Qualification Tracking Wireframe

7.4.2 Mandatory Certifications for NDIS Workers

7.4.3 Expiry Alert Schedule

# Python Certification Expiry Checker (Scheduled Job)
from datetime import datetime, timedelta

class CertificationExpiryChecker:
    ALERT_SCHEDULE = [
        (90, 'advance_notice', ['staff']),
        (60, 'reminder', ['staff', 'hr_manager']),
        (30, 'warning', ['staff', 'hr_manager', 'supervisor']),
        (14, 'urgent_warning', ['staff', 'hr_manager', 'supervisor', 'ops_manager']),
        (7, 'critical_warning', ['staff', 'hr_manager', 'supervisor', 'ops_manager', 'admin']),
        (0, 'expired', ['staff', 'hr_manager', 'supervisor', 'ops_manager', 'admin']),
    ]

    def check_expiring_certifications(self):
        today = datetime.now().date()

        for days_threshold, alert_type, recipients in self.ALERT_SCHEDULE:
            target_date = today + timedelta(days=days_threshold)

            expiring = self.db.execute("""
                SELECT sq.*, s.first_name, s.last_name, s.email, s.org_id
                FROM staff_qualifications sq
                JOIN staff s ON sq.staff_id = s.id
                WHERE sq.expiry_date = %s
                  AND sq.status = 'active'
                  AND NOT EXISTS (
                    SELECT 1 FROM alert_log al
                    WHERE al.entity_id = sq.id
                      AND al.alert_type = %s
                  )
            """, (target_date, alert_type))

            for cert in expiring:
                self.send_expiry_alert(cert, alert_type, recipients)

                # Block rostering if expired
                if days_threshold == 0:
                    self.block_rostering(cert['staff_id'], cert['id'])

7.5 Employment Management

Employment status management controls the operational state of a staff member within NDSS CRM. Status changes affect rostering eligibility, system access, and payroll processing.

7.5.1 Employment Status Definitions

7.5.2 Employment History Tracking

Every status change is recorded in the employment_history table, creating a complete audit trail of the staff member's employment lifecycle.

-- PostgreSQL: employment_history table
CREATE TABLE employment_history (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  staff_id        UUID NOT NULL REFERENCES staff(id),
  previous_status VARCHAR(20),
  new_status      VARCHAR(20) NOT NULL,
  reason          TEXT,
  effective_date  DATE NOT NULL,
  changed_by      UUID REFERENCES users(id),
  notes           TEXT,
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

7.6 Availability Management

Availability Management allows staff members to define their regular working hours and preferred shifts. This information is used by the rostering engine to match staff to shifts efficiently and avoid scheduling conflicts.

7.6.1 Weekly Availability Wireframe

7.6.2 Leave Management

Staff members can submit leave requests through the platform. Leave types include:

7.7 Staff Roles & Permissions

NDSS CRM uses a Role-Based Access Control (RBAC) system to manage staff permissions. Each staff member is assigned one or more roles, and each role grants a specific set of permissions that determine what the user can see and do within the platform.

7.7.1 Role Hierarchy

7.7.2 Permission Groups

// Permission Group Definitions (TypeScript)
export const PERMISSION_GROUPS = {
  clients: {
    'clients.view': 'View client list and profiles',
    'clients.create': 'Create new client records',
    'clients.edit': 'Edit existing client records',
    'clients.delete': 'Delete/archive client records',
    'clients.funding': 'View and manage client funding',
    'clients.goals': 'Manage client goals',
    'clients.notes': 'Create and view progress notes',
    'clients.care_plan': 'Manage care plans',
  },
  staff: {
    'staff.view': 'View staff directory and profiles',
    'staff.create': 'Create new staff records',
    'staff.edit': 'Edit existing staff records',
    'staff.delete': 'Delete/archive staff records',
    'staff.qualifications': 'Manage staff qualifications',
    'staff.availability': 'View/edit staff availability',
  },
  rostering: {
    'shifts.view': 'View shift schedules',
    'shifts.create': 'Create new shifts',
    'shifts.edit': 'Edit existing shifts',
    'shifts.delete': 'Cancel/delete shifts',
    'shifts.allocate': 'Assign staff to shifts',
    'timesheets.view': 'View timesheets',
    'timesheets.approve': 'Approve timesheets',
  },
  finance: {
    'invoices.view': 'View invoices',
    'invoices.create': 'Create invoices',
    'invoices.approve': 'Approve invoices',
    'claims.view': 'View NDIS claims',
    'claims.submit': 'Submit NDIS claims',
    'reports.financial': 'Access financial reports',
  },
  compliance: {
    'incidents.view': 'View incidents',
    'incidents.create': 'Report incidents',
    'incidents.manage': 'Manage and resolve incidents',
    'audits.view': 'View audit records',
    'audits.manage': 'Manage audits',
  },
  admin: {
    'admin.settings': 'Access admin settings',
    'admin.users': 'Manage user accounts',
    'admin.roles': 'Manage roles and permissions',
    'admin.preview_role': 'Preview other roles',
    'admin.audit_log': 'View system audit log',
  },
} as const;

7.8 Staff Performance

The Staff Performance module provides metrics and analytics on individual staff performance, including shift completion rates, client feedback scores, compliance adherence, and timeliness. These metrics are aggregated by a Python analytics service and displayed within the staff profile.

7.8.1 Performance Metrics

7.8.2 Performance Dashboard Wireframe

# Python Performance Analytics Service
class StaffPerformanceService:
    def calculate_performance_metrics(self, staff_id: str, period_start: date, period_end: date) -> dict:
        # Shift completion rate
        total_shifts = self.db.execute_scalar(
            "SELECT COUNT(*) FROM shifts WHERE staff_id = %s AND date BETWEEN %s AND %s",
            (staff_id, period_start, period_end)
        )
        completed_shifts = self.db.execute_scalar(
            "SELECT COUNT(*) FROM shifts WHERE staff_id = %s AND date BETWEEN %s AND %s AND status = 'completed'",
            (staff_id, period_start, period_end)
        )
        completion_rate = (completed_shifts / total_shifts * 100) if total_shifts > 0 else 0

        # Punctuality rate
        on_time_count = self.db.execute_scalar("""
            SELECT COUNT(*) FROM timesheets t
            JOIN shifts s ON t.shift_id = s.id
            WHERE t.staff_id = %s AND s.date BETWEEN %s AND %s
              AND t.clock_in <= s.start_time + INTERVAL '5 minutes'
        """, (staff_id, period_start, period_end))
        total_clocked = self.db.execute_scalar(
            "SELECT COUNT(*) FROM timesheets WHERE staff_id = %s AND created_at BETWEEN %s AND %s",
            (staff_id, period_start, period_end)
        )
        punctuality_rate = (on_time_count / total_clocked * 100) if total_clocked > 0 else 0

        return {
            'shift_completion_rate': round(completion_rate, 1),
            'punctuality_rate': round(punctuality_rate, 1),
            'total_shifts': total_shifts,
            'completed_shifts': completed_shifts,
            'period': {'start': period_start.isoformat(), 'end': period_end.isoformat()},
        }