Roles & Permissions

Overview

The system uses a multi-role, privilege-based access control system. Users can have multiple roles per organization, and each role maps to a set of privileges.

Roles

Role	Description
`doctor`	Healthcare practitioner — clinical access
`manager`	Administrative manager — operations
`receptionist`	Front desk staff — scheduling, patient intake
`admin`	System administrator — full access
`nurse`	Nursing staff — clinical support
`pharmacist`	Pharmacy staff — medication management
`lab_tech`	Laboratory technician — lab operations
`hr_admin`	HR administrator — workforce management

Privileges

Privilege	Description
`view_patients`	View patient list and details
`manage_patients`	Create and edit patient records
`manage_encounters`	Start/end encounters, clinical documentation
`manage_medications`	Prescribe and manage medications
`manage_appointments`	Schedule and manage appointments
`view_reports`	Access analytics and reports
`manage_organization`	Edit organization settings
`manage_roles`	Grant/revoke roles for other users
`manage_hr`	HR workforce management
`manage_inventory`	Inventory management
`view_inventory`	View inventory data
`dispense_medication`	Dispense medications from pharmacy
`manage_billing`	Billing and invoicing
`manage_documents`	Document management
`manage_communication`	Messaging and communication

Permission Matrix

Patient Permissions

Action	Doctor	Manager	Receptionist	Admin
View patient list	Y	Y	Y	Y
View patient details	Y	Y	Y	Y
Create patient	Y	-	Y	Y
Edit patient	Y	-	Y	Y
Delete patient	-	-	-	Y
View medical history	Y	-	-	Y

Clinical Permissions

Action	Doctor	Nurse	Pharmacist	Admin
Start encounter	Y	-	-	Y
Write clinical notes	Y	Y	-	Y
Prescribe medication	Y	-	-	Y
Dispense medication	-	-	Y	Y
Order lab tests	Y	-	-	Y
View lab results	Y	Y	-	Y

How Roles Resolve

A user holds a set of roles per organization, not a single role — someone can be a doctor and an HR administrator in the same place, and a different thing again in another organization.

Roles are not checked directly at the point of use. Each role maps to a set of privileges, and the application authorizes against the privilege:

roles: ["doctor", "hr_admin"]
     ↓ resolved at login
privileges: ["view_patients", "manage_encounters", "manage_hr", ...]

Both the roles and the resolved privileges are carried in the access token, so a client can render the right UI without asking, and the server never has to re-derive them per request.

The indirection is the point: adding a capability to a role changes one mapping rather than every call site that would otherwise be testing role === "doctor".

Auditing

Every grant and revoke is recorded — who was changed, which role, who made the change, in which organization, and when. Role changes are not silent.

Frontend Usage

import { usePermissions } from '@/hooks/usePermissions';
 
function MyComponent() {
  const { hasPrivilege, isDoctor, isAdmin } = usePermissions();
 
  return (
    <>
      {hasPrivilege('manage_encounters') && <StartEncounterButton />}
      {hasPrivilege('manage_roles') && <SecurityLink />}
    </>
  );
}

Security Page

The /security page (requires manage_roles privilege) allows:

Viewing all staff members and their roles
Granting/revoking roles per user
Viewing audit log of role changes