Chapter 6: Client Management

Client Management is the cornerstone of the NDSS CRM platform, providing comprehensive tools for recording, organising, and managing NDIS participant information. This module handles everything from initial client creation through ongoing care plan management, NDIS funding tracking, goal monitoring, and progress documentation. Built on Next.js and React for the interface with Python and PHP microservices handling business logic, and PostgreSQL for data persistence, the Client Management module is designed to support organisations of any size, from small community providers to large multi-site operations.

6.1 Client List View

The Client List View is the primary entry point for client management. It displays a paginated, searchable, and filterable table of all clients within the organisation. The list supports server-side pagination (20 records per page by default), full-text search, and multi-criteria filtering.

6.1.1 Client List Wireframe

6.1.2 Client List Table Columns

6.1.3 Client List API Endpoint

# Python API: GET /api/clients
@app.route('/api/clients', methods=['GET'])
def list_clients():
    org_id = get_current_org_id()
    page = int(request.args.get('page', 1))
    per_page = int(request.args.get('per_page', 20))
    search = request.args.get('search', '')
    status = request.args.get('status', '')
    funding_type = request.args.get('funding_type', '')
    sort_by = request.args.get('sort_by', 'last_name')
    sort_dir = request.args.get('sort_dir', 'asc')

    query = """
        SELECT c.id, c.client_id, c.first_name, c.last_name,
               c.ndis_number, c.funding_type, c.suburb, c.state,
               c.intake_date, c.status, c.created_at
        FROM clients c
        WHERE c.org_id = %s AND c.deleted_at IS NULL
    """
    params = [org_id]

    if search:
        query += """ AND (
            c.search_vector @@ plainto_tsquery('english', %s)
            OR c.ndis_number ILIKE %s
        )"""
        params.extend([search, f'%{search}%'])

    if status:
        query += " AND c.status = %s"
        params.append(status)

    if funding_type:
        query += " AND c.funding_type = %s"
        params.append(funding_type)

    # Sorting (whitelist allowed columns)
    allowed_sorts = ['last_name', 'ndis_number', 'funding_type', 'suburb', 'intake_date', 'status']
    if sort_by in allowed_sorts:
        query += f" ORDER BY c.{sort_by} {sort_dir}"

    # Pagination
    offset = (page - 1) * per_page
    query += " LIMIT %s OFFSET %s"
    params.extend([per_page, offset])

    clients = db.execute(query, params)
    total = db.execute_scalar("SELECT COUNT(*) FROM clients WHERE org_id = %s AND deleted_at IS NULL", [org_id])

    return jsonify({
        'data': clients,
        'pagination': {
            'page': page,
            'per_page': per_page,
            'total': total,
            'total_pages': math.ceil(total / per_page)
        }
    })

6.2 Creating a New Client

New clients are created through a comprehensive multi-step form that captures all essential information required for NDIS service delivery. The form includes validation rules that ensure data integrity, including NDIS number format validation, mandatory field enforcement, and duplicate detection.

6.2.1 Client Creation Form Wireframe

6.2.2 Form Field Specifications

6.2.3 NDIS Number Validation

// NDIS Number Validation (TypeScript)
export function validateNDISNumber(value: string): ValidationResult {
  // Remove spaces and hyphens
  const cleaned = value.replace(/[\s-]/g, '');

  if (cleaned.length !== 12) {
    return { valid: false, error: 'NDIS number must be exactly 12 digits' };
  }

  if (!/^\d{12}$/.test(cleaned)) {
    return { valid: false, error: 'NDIS number must contain only digits' };
  }

  if (!cleaned.startsWith('43')) {
    return { valid: false, error: 'NDIS number must start with 43' };
  }

  return { valid: true, formatted: cleaned };
}

// Duplicate detection
export async function checkDuplicateNDIS(ndisNumber: string, orgId: string): Promise<boolean> {
  const response = await fetch(`/api/clients/check-ndis?number=${ndisNumber}&org_id=${orgId}`);
  const data = await response.json();
  return data.exists;
}

6.3 Client Profile

The Client Profile page provides a comprehensive view of all information related to a specific client. It is organised into a tabbed interface with the following sections: Overview, Goals, Progress Notes, Funding, Care Plan, and Documents. The profile page is accessible by clicking on a client's name from the Client List or any other reference to the client throughout the platform.

6.3.1 Client Profile Wireframe

6.3.2 Profile Tab Summary

6.4 NDIS Funding Management

The NDIS Funding Management section within the client profile provides detailed tracking of the client's NDIS plan budget, category allocations, and utilisation rates. This is critical for ensuring that service delivery stays within budget and that funding is optimally distributed across support categories.

6.4.1 Funding Overview Wireframe

6.4.2 Funding Alert Thresholds

6.4.3 Funding Calculation Logic

# PHP Funding Calculation Service
class FundingCalculator
{
    public function calculateUtilisation(string $clientId, string $categoryId): array
    {
        $plan = $this->planRepository->getActivePlan($clientId);

        if (!$plan) {
            throw new PlanNotFoundException("No active NDIS plan found for client {$clientId}");
        }

        $budget = $this->budgetRepository->getCategoryBudget($plan->id, $categoryId);
        $spent = $this->invoiceRepository->getTotalSpentByCategory($plan->id, $categoryId);

        $remaining = $budget->amount - $spent;
        $utilisation = ($budget->amount > 0) ? ($spent / $budget->amount) * 100 : 0;

        // Calculate projected utilisation at plan end
        $daysElapsed = now()->diffInDays($plan->start_date);
        $totalDays = $plan->end_date->diffInDays($plan->start_date);
        $dailyBurnRate = ($daysElapsed > 0) ? $spent / $daysElapsed : 0;
        $projectedTotal = $dailyBurnRate * $totalDays;
        $projectedUtilisation = ($budget->amount > 0)
            ? ($projectedTotal / $budget->amount) * 100
            : 0;

        return [
            'budget' => $budget->amount,
            'spent' => $spent,
            'remaining' => $remaining,
            'utilisation_percent' => round($utilisation, 1),
            'projected_utilisation' => round($projectedUtilisation, 1),
            'daily_burn_rate' => round($dailyBurnRate, 2),
            'alert_level' => $this->getAlertLevel($utilisation),
        ];
    }

    private function getAlertLevel(float $utilisation): string
    {
        return match(true) {
            $utilisation > 100 => 'overspent',
            $utilisation > 95  => 'critical',
            $utilisation > 80  => 'warning',
            $utilisation > 60  => 'notice',
            default            => 'normal',
        };
    }
}

6.5 Goal Tracking

Goal Tracking enables support coordinators and clinicians to define, monitor, and review client goals as part of their NDIS plan. Each goal has a measurable target, progress percentage, category, and review schedule.

6.5.1 Goals List Wireframe

6.5.2 Goal Data Model

-- PostgreSQL: client_goals table
CREATE TABLE client_goals (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  client_id       UUID NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
  org_id          UUID NOT NULL REFERENCES organisations(id),
  title           VARCHAR(500) NOT NULL,
  description     TEXT,
  category        VARCHAR(50) NOT NULL,  -- 'core_supports', 'capacity_building', 'capital'
  progress        INTEGER DEFAULT 0 CHECK (progress >= 0 AND progress <= 100),
  status          VARCHAR(20) DEFAULT 'active',  -- 'active', 'completed', 'on_hold', 'cancelled'
  target_date     DATE,
  review_date     DATE,
  created_by      UUID REFERENCES users(id),
  completed_at    TIMESTAMPTZ,
  notes           TEXT,
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);

6.6 Progress Notes

Progress Notes are chronological records of interactions, observations, and service delivery details for a client. They are typically created during or after a shift and serve as the primary documentation trail for NDIS compliance and auditing purposes.

6.6.1 Note Types

6.6.2 Progress Notes Wireframe

6.7 Care Plan Management

Care Plans define the comprehensive support framework for each client, including support categories, service schedules, risk assessments, and review timelines. Care plans are versioned documents that are reviewed and updated at regular intervals in line with NDIS plan review cycles.

6.7.1 Care Plan Components

6.7.2 Care Plan Versioning

Every modification to a care plan creates a new version. The system maintains a complete version history for audit purposes. Previous versions are read-only but can be viewed for comparison. The versioning is implemented using a combination of PostgreSQL row versioning and a PHP service that manages version diffs.

-- PostgreSQL: care_plan_versions table
CREATE TABLE care_plan_versions (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  care_plan_id    UUID NOT NULL REFERENCES care_plans(id),
  version_number  INTEGER NOT NULL,
  content         JSONB NOT NULL,
  change_summary  TEXT,
  created_by      UUID REFERENCES users(id),
  approved_by     UUID REFERENCES users(id),
  approved_at     TIMESTAMPTZ,
  created_at      TIMESTAMPTZ DEFAULT NOW(),

  UNIQUE(care_plan_id, version_number)
);

6.8 Client Status Management

Client status determines the operational state of a client within NDSS CRM and affects what actions can be performed on their record.

6.8.1 Status Definitions

6.8.2 Status Transition Rules

6.9 Client Search & Filtering

The Client Management module supports comprehensive search and filtering capabilities to help users quickly locate client records. Searching leverages PostgreSQL full-text search with GIN indexes for fast, relevant results.

6.9.1 Search Capabilities

6.9.2 Filter Options

6.9.3 Full-Text Search Index Configuration

-- PostgreSQL: Full-text search configuration for clients
ALTER TABLE clients ADD COLUMN search_vector tsvector;

CREATE FUNCTION update_client_search_vector() RETURNS trigger AS $$
BEGIN
  NEW.search_vector :=
    setweight(to_tsvector('english', COALESCE(NEW.first_name, '')), 'A') ||
    setweight(to_tsvector('english', COALESCE(NEW.last_name, '')), 'A') ||
    setweight(to_tsvector('english', COALESCE(NEW.ndis_number, '')), 'B') ||
    setweight(to_tsvector('english', COALESCE(NEW.suburb, '')), 'C') ||
    setweight(to_tsvector('english', COALESCE(NEW.email, '')), 'D') ||
    setweight(to_tsvector('english', COALESCE(NEW.notes, '')), 'D');
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER client_search_vector_update
  BEFORE INSERT OR UPDATE ON clients
  FOR EACH ROW EXECUTE FUNCTION update_client_search_vector();

CREATE INDEX idx_clients_search ON clients USING GIN(search_vector);