Referral Frontend App Documentation

Getting Started

The Referral Frontend App is a demonstration tool for creating FHIR Australian profiles for healthcare referrals. This guide will help you understand what the app does and how you can use it in your own projects.

Prerequisites

• Node.js 18.0 or newer
• Basic understanding of React and Next.js
• Familiarity with FHIR concepts (recommended)

Quick Start

# Clone the repository
git clone https://github.com/ausbiz/referral-frontend.git

# Navigate to the project directory
cd referral-frontend

# Install dependencies
npm install

# Start the development server
npm run dev

Installation

Installation from GitHub

# Clone the repository
git clone https://github.com/ausbiz/referral-frontend.git

# Navigate to the project directory
cd referral-frontend

# Install dependencies
npm install

Configuration

Create a .env.local file in the root directory with the following variables:

# FHIR Server URL
NEXT_PUBLIC_FHIR_SERVER=https://fhir-demo.ausbiz.com.au/api/fhir

# For local development only (optional)
NEXT_PUBLIC_USE_MOCK_DATA=true

Using with our Demo FHIR Server

You can use our public demo FHIR server for testing:

# Add to your .env.local file
NEXT_PUBLIC_FHIR_SERVER=https://fhir-demo.ausbiz.com.au/api/fhir

# Add client certificate (for mTLS)
FHIR_CLIENT_CERT=path/to/client.cert
FHIR_CLIENT_KEY=path/to/client.key

Usage

Creating a New Referral

1. Navigate to the "New Referral" section
2. Select the appropriate referral template
3. Fill in patient demographic details
4. Add clinical information and referral reason
5. Review and validate the FHIR payload
6. Submit the referral to the FHIR server

Using Server Actions with mTLS

The app demonstrates how to use Next.js Server Actions to securely communicate with a FHIR server using mTLS 2.0:

// app/actions.ts
"use server";

import * as https from 'https';
import fs from 'fs';

export async function submitReferral(payload: FHIRReferral) {
  // Create HTTPS agent with client certificates for mTLS
  const agent = new https.Agent({
    cert: fs.readFileSync(process.env.FHIR_CLIENT_CERT!),
    key: fs.readFileSync(process.env.FHIR_CLIENT_KEY!)
  });

  // API call is made securely from the server
  const response = await fetch(process.env.FHIR_SERVER_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/fhir+json' },
    body: JSON.stringify(payload),
    agent
  });
  
  return response.json();
}

Technical Details

FHIR Implementation

The Referral Frontend App implements the Australian FHIR profiles for referrals, which extend the base FHIR resources with Australian-specific requirements. Key resources implemented include:

• ServiceRequest: The primary resource representing the referral
• Patient: Contains patient demographic information
• Practitioner: Information about the referring and receiving practitioners
• Organization: Details about the referring and receiving organizations
• Condition: Clinical conditions relevant to the referral
• AllergyIntolerance: Patient allergies and adverse reactions
• MedicationStatement: Current medications
• Observation: Relevant clinical observations

Sample FHIR Referral Payload

Below is an example of a complete FHIR referral payload conforming to Australian standards:

{
  "resourceType": "ServiceRequest",
  "id": "AURF-028",
  "contained": [
    {
      "resourceType": "PractitionerRole",
      "id": "187490",
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org.au/CodeSystem/v2-0203",
                "code": "UPIN",
                "display": "Referral for specialist consultation"
              }
            ],
            "text": "Medicare Provider Number"
          },
          "system": "http://ns.electronichealth.net.au/id/medicare-provider-number",
          "value": "2524439314"
        }
      ],
      "practitioner": {
        "reference": "#9548550b-7851-4a5d-b637-99f09126e6d4",
        "type": "Practitioner"
      },
      "organization": {
        "reference": "#995227b8-e847-41d0-a1f1-c696a9c0e362",
        "type": "Organization"
      }
    },
    {
      "resourceType": "Practitioner",
      "id": "9548550b-7851-4a5d-b637-99f09126e6d4",
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "system": "http://hl7.org.au/fhir/v2/0203",
                "code": "NPI",
                "display": "National provider identifier"
              }
            ],
            "text": "HPI-I"
          },
          "system": "http://ns.electronichealth.net.au/id/hi/hpii/1.0",
          "value": "3582776755834409"
        }
      ],
      "name": [
        {
          "use": "official",
          "family": "Herzog",
          "given": [
            "Cedrick"
          ]
        },
        {
          "use": "pratice",
          "family": "Herzog",
          "given": [
            "Gold Coast Health Partners"
          ]
        }
      ],
      "telecom": [
        {
          "system": "phone",
          "value": "0276668451",
          "use": "work"
        },
        {
          "system": "email",
          "value": "Cedrick.Herzog40@gmail.com",
          "use": "work"
        }
      ]
    },
    {
      "resourceType": "Organization",
      "id": "995227b8-e847-41d0-a1f1-c696a9c0e362",
      "meta": {
        "profile": [
          "http://hl7.org.au/fhir/StructureDefinition/au-organization"
        ]
      },
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org.au/CodeSystem/v2-0203",
                "code": "NOI",
                "display": "National Organisation Identifier"
              }
            ],
            "text": "HPI-O"
          },
          "system": "http://ns.electronichealth.net.au/id/hi/hpio/1.0",
          "value": "1928561278767784"
        },
        {
          "type": {
            "coding": [
              {
                "system": "http://hl7.org.au/fhir/v2/0203",
                "code": "RI",
                "display": "Resource identifier"
              }
            ],
            "text": "EDI"
          },
          "system": "https://au.securemessagingprovider.net/edi-endpoint",
          "value": "WZ16312"
        }
      ],
      "active": true,
      "name": "Blue Mountains Medical Group",
      "telecom": [
        {
          "system": "phone",
          "value": "0286755936",
          "use": "work"
        },
        {
          "system": "email",
          "value": "Cade85@gmail.com",
          "use": "work"
        }
      ],
      "address": [
        {
          "use": "work",
          "type": "physical",
          "line": [
            "9608 Toney Village"
          ],
          "city": "East Ozellaport",
          "state": "TAS",
          "postalCode": "20390-8653",
          "country": "AUS"
        }
      ]
    },
    {
      "resourceType": "Patient",
      "id": "2ff6fd9d-6c25-4494-a90a-83fec3c26f50",
      "meta": {
        "profile": [
          "http://hl7.org.au/fhir/StructureDefinition/au-patient"
        ]
      },
      "extension": [
        {
          "url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
          "valueCoding": {
            "system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
            "code": "1",
            "display": "Aboriginal but not Torres Strait Islander origin"
          }
        }
      ],
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                "code": "NI",
                "display": "National unique individual identifier"
              }
            ],
            "text": "IHI"
          },
          "system": "http://ns.electronichealth.net.au/id/hi/ihi/1.0",
          "value": "0980671847270144"
        },
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                "code": "MC",
                "display": "Patient's Medicare Number"
              }
            ],
            "text": "Medicare Number"
          },
          "system": "http://ns.electronichealth.net.au/id/medicare-number",
          "value": "9153436357"
        },
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org.au/CodeSystem/v2-0203",
                "code": "DVAU",
                "display": "DVA Number"
              }
            ],
            "text": "DVA Number"
          },
          "system": "http://ns.electronichealth.net.au/id/dva",
          "value": "ZjkZXXAT"
        }
      ],
      "name": [
        {
          "use": "official",
          "family": "Bahringer",
          "given": [
            "Donnie"
          ]
        }
      ],
      "telecom": [
        {
          "system": "phone",
          "value": "0267914539",
          "use": "work",
          "rank": 2
        },
        {
          "system": "phone",
          "value": "0405879809",
          "use": "home",
          "rank": 2
        },
        {
          "system": "phone",
          "value": "0447870962",
          "use": "mobile",
          "rank": 1
        },
        {
          "system": "email",
          "value": "Donnie_Bahringer83@hotmail.com",
          "use": "home",
          "rank": 2
        }
      ],
      "gender": "other",
      "birthDate": "1992-03-25",
      "address": [
        {
          "use": "home",
          "type": "postal",
          "line": [
            "79280 Graham Roads"
          ],
          "city": "New Adacester",
          "state": "VIC",
          "postalCode": "2537",
          "country": "AUS"
        },
        {
          "use": "home",
          "type": "physical",
          "line": [
            "8596 10th Street"
          ],
          "city": "Bodechester",
          "postalCode": "86487-1430",
          "country": "AUS"
        }
      ],
      "contact": [
        {
          "relationship": [
            {
              "coding": [
                {
                  "system": "http://health.unknown.gov.au/snomed?ItemID=10813",
                  "code": "27",
                  "display": "Carer"
                }
              ]
            }
          ],
          "name": {
            "given": [
              "Wyatt"
            ],
            "family": "Simonis"
          },
          "telecom": [
            {
              "system": "phone",
              "value": "0277198016",
              "use": "mobile"
            }
          ]
        }
      ],
      "generalPractitioner": [
        {
          "reference": "#9548550b-7851-4a5d-b637-99f09126e6d4",
          "type": "Practitioner"
        }
      ],
      "managingOrganization": {
        "reference": "#995227b8-e847-41d0-a1f1-c696a9c0e362",
        "type": "Organization"
      },
      "medicareExpiry": "09/2030"
    }
  ],
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org.au/fhir/StructureDefinition/au-medicare-provider",
            "code": "MPR",
            "display": "Medicare Provider Number"
          }
        ],
        "text": "Medicare Provider Number"
      },
      "system": "http://hl7.org.au/fhir/StructureDefinition/au-medicare",
      "value": "0444197645"
    }
  ],
  "basedOn": [
    {
      "display": "Referral for consultation and investigation"
    }
  ],
  "status": "active",
  "intent": "order",
  "priority": "routine",
  "code": {
    "text": "Patient has a broken shoulder."
  },
  "subject": {
    "reference": "#2ff6fd9d-6c25-4494-a90a-83fec3c26f50",
    "type": "Patient"
  },
  "occurrenceTiming": {
    "repeat": {
      "duration": 14,
      "durationUnit": "d"
    }
  },
  "authoredOn": "2023-06-17T00:00:42+00:00",
  "requester": {
    "reference": "#187490",
    "type": "PractitionerRole"
  },
  "performer": [
    {
      "type": "Organization",
      "identifier": {
        "value": "aubootcampref"
      },
      "display": "AusBiz Medical Consulting Group"
    }
  ],
  "recipient": [
    {
      "reference": "Organization/ausbiz-medical-consulting-group"
    }
  ]
}

Understanding the FHIR Payload Structure

Let's break down the key components of this FHIR referral payload:

1. Root ServiceRequest Resource

The root resource is a ServiceRequest, which represents the referral itself:

• resourceType and id: Identifies this as a ServiceRequest with a unique identifier
• status and intent: Indicates that this is an active referral with an "order" intent
• priority: Specifies the urgency level (routine, urgent, asap, stat)
• code: Contains the reason for referral in text format
• authoredOn: The date and time when the referral was created
• occurrenceTiming: Defines the validity period of the referral (14 days in this example)

2. Contained Resources

The contained array holds related resources that are referenced within the ServiceRequest:

• PractitionerRole: Links a practitioner to their organization with their provider number
• Practitioner: The referring doctor with:
  • HPI-I (Healthcare Provider Identifier-Individual)
  • Contact information
  • Multiple name records (official name and practice name)
• Organization: The referring practice with:
  • HPI-O (Healthcare Provider Identifier-Organization)
  • EDI secure messaging endpoint for electronic communication
  • Address and contact information
  • Australian profile conformance (au-organization)
• Patient: The subject of the referral with:
  • Australian-specific extensions like indigenous-status
  • Multiple identifiers (IHI, Medicare, DVA)
  • Contact information with priority ranking
  • Emergency contact (carer)
  • References to their GP and managing organization

3. Australian-Specific Elements

This payload demonstrates several Australian healthcare system elements:

• Australian identifiers:
  • Medicare Provider Numbers
  • Individual Healthcare Identifiers (IHI)
  • Healthcare Provider Identifiers (HPI-I, HPI-O)
  • DVA (Department of Veterans' Affairs) numbers
• Australian extensions:
  • Indigenous status coding using Australian terminology
  • Australian address format
• Profile conformance:
  • References to Australian FHIR profiles (http://hl7.org.au/fhir/StructureDefinition/...)
  • Use of Australian terminology systems

4. References Between Resources

Notice how resources are linked using internal references with the # symbol:

• The Patient resource references the Practitioner as the general practitioner
• The PractitionerRole links a practitioner to their organization
• The ServiceRequest's subject refers to the Patient resource
• The requester refers to the PractitionerRole

This interconnected structure creates a complete clinical context for the referral.

Australian Extensions

The application supports Australian extensions to FHIR resources, including:

• au-address: Australian address format extensions
• indigenous-status: Indigenous status coding
• medicare-number: Medicare number with IRN
• dva-number: Department of Veterans' Affairs number
• ihi-number: Individual Healthcare Identifier
• healthcarecard: Healthcare card details

Validation Process

The application validates FHIR resources at multiple levels:

1. Structure validation: Ensures the JSON structure conforms to FHIR specifications
2. Content validation: Validates that required data elements are present and correctly formatted
3. Business rules: Applies Australian-specific business rules to the referral
4. Cross-resource validation: Ensures consistency across related resources

Advanced Configuration

Custom Templates

You can create custom referral templates by adding JSON files to the templates directory:

# Directory structure
referral-frontend/
├── templates/
│   ├── general-practice.json
│   ├── specialist.json
│   └── allied-health.json

Template structure:

{
  "name": "General Practice Referral",
  "description": "Standard referral to a General Practitioner",
  "version": "1.0",
  "serviceType": {
    "coding": [{
      "system": "https://healthterminologies.gov.au/fhir/CodeSystem/service-type",
      "code": "1",
      "display": "General Practice"
    }]
  },
  "requiredFields": ["patient", "practitioner", "reasonForReferral"],
  "optionalFields": ["allergies", "medications", "pastHistory"],
  "defaultValues": {
    "priority": "routine"
  }
}

Custom FHIR Endpoints

For enterprise deployments, configure custom FHIR endpoints in your environment file:

# Production FHIR server
NEXT_PUBLIC_FHIR_SERVER=https://your-fhir-server.com/fhir
FHIR_AUTH_METHOD=client-credentials
FHIR_CLIENT_ID=your-client-id
FHIR_CLIENT_SECRET=your-client-secret
FHIR_TOKEN_URL=https://your-auth-server.com/token

Security Considerations

Authentication and Authorization

The Referral Frontend App supports several authentication methods:

• Client Credentials: OAuth 2.0 client credentials flow for server-to-server communication
• mTLS: Mutual TLS with client certificates for secure communication
• SMART on FHIR: Integration with SMART authorization for EHR contexts

Data Protection

All patient data handled by the application should be treated as Protected Health Information (PHI):

• Data is transmitted over secure channels (HTTPS/TLS 1.3+)
• Server actions keep sensitive data server-side
• No PHI is stored in browser storage
• Debug logging automatically redacts sensitive fields

Troubleshooting

Common Issues

CORS Errors

If encountering CORS errors when connecting to your FHIR server:

1. Ensure your FHIR server allows requests from your application's origin
2. Use server actions for cross-origin requests to avoid browser CORS restrictions
3. Check network tab for specific CORS error details

Certificate Errors

For mTLS certificate issues:

1. Verify certificate and key file paths
2. Ensure certificates are in PEM format
3. Check certificate expiration dates
4. Validate certificate trust chain against your FHIR server's CA

Validation Errors

If FHIR validation fails:

1. Check the validation response for specific error details
2. Verify resource against the Australian FHIR Implementation Guide
3. Use the FHIR validator tool: npx fhir-validator validate -profile au-referral your-payload.json

Community and Support

Contributing

We welcome contributions to improve the Referral Frontend App:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request with a clear description of the changes

Getting Help

For questions and support:

• GitHub Issues: https://github.com/ausbiz/referral-frontend/issues
• Developer Forum: https://discuss.ausbiz.com.au/referral-frontend
• Email Support: fhir-support@ausbiz.com.au