NexGeneration Portal
User Manual

The NexGeneration Support Staff Portal is a full-stack web application that manages the entire operational lifecycle of a healthcare support staffing agency — from recruiting and onboarding candidates through to scheduling shifts, tracking compliance, and generating financial reports.

Technology Stack

The portal has three authenticated roles and one public-facing route:

Feature Access Matrix

The Staff module holds all registered support workers. Each staff record tracks personal details, compliance status, documents, training, pay overrides, and shift history.

Staff Roles (Care Positions)

Workers are assigned one of the following roles, which determines which shifts they can claim:

• Support Worker
• Senior Support Worker
• Healthcare Assistant
• Registered Nurse
• Team Leader
• Domiciliary Carer

Staff Status

Pay Overrides

Administrators can set individual pay rate overrides for a worker via the worker_pay_overrides table, specifying an effective date range. When a new shift is created for that worker, the system automatically applies the current override rate in place of the default role rate from Settings.

Unavailability Blocks

Workers can declare periods of unavailability. During these periods, matching open shifts will not be shown to the worker in their shift list.

Pulling Application Documents to Staff Record

If a worker was previously processed through the Recruitment module, an admin can click Pull Docs on the staff profile. The system will match the staff record to their application (by email or name) and copy across any approved application documents, automatically marking them as Approved in the staff document section.

Clients are the care establishments (residential homes, supported living settings, etc.) that book staff through NexGeneration. Each client has a profile, one or more locations, and their own portal login.

Client Profile Fields

• Name — Organisation name
• Contact details — Email, phone, address, town
• Charge rate defaults — Overridden per shift if required

Locations

Each client may have multiple named locations (e.g. individual wards, houses, or units) with a name and postcode. Locations are linked to shifts. Clients can manage their own locations through the portal; admins can manage all locations.

Shift Statuses

Creating a Shift

Admins and clients can create shifts. Required fields are date, start time, end time, role required, and client. Optional fields include location, specific worker assignment, notes, and rate overrides.

Claiming a Shift (Workers)

Workers see open shifts that match their care role and fall outside any declared unavailability. To claim a shift:

1. The worker must be Active status with a Compliant or Expiring Soon compliance status. Non-compliant and Inactive workers cannot see or claim open shifts.
2. The worker clicks Claim on an open shift. The system uses a database-level atomic lock to prevent double-claiming.
3. The shift status changes to Confirmed and the worker is notified by email.

Cancelling a Shift

Auto-Completion

The system runs a background check every 15 minutes. Any Confirmed shift whose date and end time has passed is automatically moved to Completed and a draft timesheet is created. An email summary is sent to the admin notification address.

Timesheet Statuses

Automatic Timesheet Generation

Timesheets are created automatically in two ways:

• On shift completion: A Draft timesheet is created immediately when a shift auto-completes.
• Weekly sweep: Every Monday at 10:00 AM, the system checks for any Completed shifts from the previous week that do not yet have a timesheet and generates them.

Timesheet Structure

Each timesheet covers a Monday-to-Sunday week. It includes start/end times, break durations, sleep times, and totals for each day of the week, plus a weekly total hours field.

Submitting & Approving

1. Worker reviews the pre-populated timesheet entries and submits.
2. Admin or client reviews and either Approves or Rejects the timesheet.
3. Approved timesheets feed into the Financial Reports module for revenue and cost calculations.

Every staff member has a live compliance status computed from their account status, DBS expiry, document review statuses, and training record expiries.

What Triggers Non-Compliant

• DBS expiry date is in the past
• Any staff document has expired (expiry date < today)
• Any training record has expired
• A document has status Replacement Requested
• A document has status Rejected

Accepted File Types

Maximum file size: 15 MB. Both MIME type and file extension are validated server-side.

Document Review Statuses

Document Access Security

Document files are not publicly accessible. The server enforces the following access rules:

• Admins can access any document file.
• Workers can only access documents that belong to their own staff record.
• Path traversal attacks are prevented by resolving and comparing absolute file paths before serving.

DBS Tracking

The DBS expiry date is stored directly on the staff record (dbs_expiry). When this date passes, the worker immediately becomes Non-Compliant regardless of document review status.

Staff training is tracked in the staff_training table. Each record links a training module to a staff member, with an optional expiry date.

Training Modules

Training modules are configured by admins (e.g. Manual Handling, Safeguarding, Fire Safety, First Aid, Medication, Infection Control). Each module can be marked as completed and assigned an expiry date.

Training & Compliance

• Any training with an expiry date in the past makes the worker Non-Compliant.
• Any training expiring within 30 days sets status to Expiring Soon.

Training data is included in the staff list API and displayed as a key-value map of module name → completed boolean.

The Applications module manages inbound candidate enquiries from initial submission through to interview and onboarding as a staff member.

Application Fields

• Personal details: name, email, phone, date of birth
• Role applied for
• Right to work / visa status
• Public upload token and expiry (for document submission)

Application Requirements Checklist

Each application has a requirements record with a JSON checklist that tracks whether the following items have been supplied and approved:

When an admin approves a document, the checklist is automatically updated for the matching requirement key.

Ready for Staff Flag

Once an admin is satisfied that all requirements are met, they can toggle Ready for Staff on the requirements record. This signals that the application is complete and the candidate can be onboarded as a staff member.

Interviews are scored records linked to an application. Only admins can create or view interviews.

Interview Scoring

Six dimensions are rated on a numeric scale. The system calculates an average score automatically:

Interview Outcome

Eligibility Pre-Checks

Before the interview score is recorded, the form captures pre-checks: DBS eligibility, Right to Work, references, NMC PIN (if applicable), childcare disqualification declaration, and free-text eligibility notes.

Candidates can securely upload compliance documents without needing a portal account, using a time-limited token URL.

Generating an Upload Link (Admin)

1. Navigate to the candidate's application in the portal.
2. Click Get Upload Link (or Send Upload Link to email it directly to the candidate).
3. The system generates a 48-character random token and stores it with a 30-day expiry.
4. The unique URL follows the pattern: /candidate-upload/<token>

Candidate Experience

The candidate visits the secure URL and is presented with a simple upload form. They select the document type and attach their file. Accepted formats are PDF, JPG, PNG, DOC and DOCX (max 15 MB). Uploaded documents appear in the admin's application documents list with a status of Pending review.

Document Types Available to Candidates

• Photo ID / Passport
• Right to Work / Visa / Share Code
• Enhanced DBS Certificate
• Training Certificate
• Reference Document
• Other / General

All portal accounts are managed exclusively by administrators. There is no self-registration.

Creating a User Account

1. In the Admin panel, navigate to Users and click Add User.
2. Enter name, email, password and role.
3. For Worker accounts, link to an existing Staff record (staff_id).
4. For Client accounts, link to an existing Client record (client_id).
5. Save — the user will receive a welcome email with their login details.

Password Management

• Admins can reset any user's password from the Users screen.
• When a password is reset by an admin, the affected user receives a notification email.
• Workers and clients cannot change their own passwords — they must contact an admin or use the Forgot Password flow.
• Passwords must be a minimum of 8 characters.

Deactivating a User

Deleting a user performs a soft-delete: the account is marked deleted_at = NOW() and status set to inactive. The user can no longer log in but their data and audit history are preserved. An admin cannot delete their own account.

The Settings module stores two JSON objects: settings_data for general portal configuration and rates_data for default pay rates by worker role.

Default Pay Rates (rates_data)

The worker_rates section of rates_data defines the default hourly pay rate for each care role. These rates are used when creating or reopening shifts where no individual override is in place:

• support_worker
• senior_support_worker
• healthcare_assistant
• registered_nurse
• team_leader
• domiciliary_carer

The Financials report is available to admins only. It aggregates shift data for a given calendar month and returns daily breakdowns.

Financial Report Fields

Pass a month query parameter in YYYY-MM format. Defaults to the current month if omitted.

All significant create, update, and delete operations write an entry to the audit_log table. Entries are visible to admins only and include:

• user_id — Who performed the action
• action — What was done (e.g. CREATE_SHIFT, RESET_PASSWORD, DELETE_USER)
• table_name — Which table was affected
• record_id — ID of the affected record
• details — JSON payload of relevant context
• ip_address — Originating IP address

The audit log is append-only and cannot be modified through the portal.

The portal runs two background tasks on a 15-minute timer while the Node.js process is running:

The future-compliance-scan.js script is a standalone command-line tool that scans all confirmed future shifts for workers who are (or will be) non-compliant on the shift date. It can optionally reopen (unassign) those shifts.

Usage

# Preview mode — shows what would be affected (no changes made)
node future-compliance-scan.js preview 365

# Commit mode — reopens shifts assigned to non-compliant workers
node future-compliance-scan.js commit 365

# Scan just the next 30 days
node future-compliance-scan.js preview 30

Parameters

What It Does

• Fetches all Confirmed shifts from today up to the horizon date.
• For each shift, calculates the worker's compliance status as of that specific shift date (projecting expiries into the future).
• In commit mode, any shift assigned to a Non-Compliant or Inactive worker is reopened: worker_id cleared, status set to Open.

The db_backup.sh shell script handles automated PostgreSQL backups using pg_dump and uploads them to Google Drive via rclone.

Backup Process

1. Reads database credentials from /var/www/ngs-portal/.env.
2. Runs pg_dump in custom format (-F c) to /var/backups/ngs-portal/ngs_backup_YYYY-MM-DD.dump.
3. Uploads the backup to Google Drive remote: gdrive:NexGen_Backups.
4. Deletes local backup files older than 7 days.
5. Deletes remote backup files older than 30 days.

Prerequisites

• pg_dump must be installed and on the system path.
• rclone must be installed and configured with a gdrive remote pointing to the correct Google Drive folder.

Scheduling the Backup

Schedule the script with cron for daily automated backups. Example — run at 2:00 AM daily:

0 2 * * * /var/www/ngs-portal/db_backup.sh >> /var/log/ngs-backup.log 2>&1

The portal is managed as a PM2 process using the ecosystem.config.js configuration file. PM2 provides process supervision, automatic restarts, and log management.

Starting the Application

# Start the application
pm2 start ecosystem.config.js

# Save the process list (survives reboots)
pm2 save

# Generate and enable startup script
pm2 startup

PM2 Configuration Summary

Environment Variables (.env)

The application reads configuration from a .env file (loaded via dotenv). Key variables:

Health Check Endpoint

A health check endpoint is available without authentication:

GET /api/health

# Returns:
{ "status": "ok", "db": "connected", "version": "2.0", "time": "..." }

Use this endpoint with your load balancer, uptime monitor, or infrastructure automation to verify the application and database are running.

Common PM2 Commands

pm2 status          # View all processes
pm2 logs ngs-portal # Tail live logs
pm2 restart ngs-portal
pm2 stop ngs-portal
pm2 reload ngs-portal # Zero-downtime reload