# Oziris RIS Module Reference

Last reviewed: 17 July 2026. The application currently exposes 99 non-vendor routes.

## Statistics & Analytics (optional)

- Controller: `Workflow\StatisticsController`
- Routes: `/statistics`, `/statistics/insights`, `/statistics/examinations`, `/statistics/workload`, `/statistics/clinical`, `/statistics/quality-safety`, `/statistics/moh-standards`, and `/statistics/export.csv`
- Permissions: `view_statistics` and `export_statistics`
- The primary OZI-RIS layer reports operational examination, procedure, modality, turnaround, and recorded staff activity for a governed hospital-timezone date range.
- The Insights layer adds prior-period demand comparison, completion and no-show rates, patient/oncology mix, referral sources, peak operating patterns, report turnaround bands, backlog, and five-field data-quality scoring.
- Staff workload includes attendance, completion, report finalization, scheduling, workflow actions, active days, average activity/day, out-of-hours and weekend contribution, modality mix, and activity share. It is explicitly not a performance score because rosters, leave and governed complexity weights are not captured.
- Clinical/referral analysis covers age bands, recorded sex, citizenship, repeat patients, MDT linkage, reporting profiles, oncology primary site/treatment phase, requesting departments, and requesting clinicians.
- Quality/safety analysis covers critical-result communication, acknowledgement delay, peer-review findings, contrast-documentation completeness, contrast volumes/brands, extravasation, consumable usage, and cancellation/rejection reasons.
- MOH Standards is a separate secondary layer. Indicators show their definition year, eligibility denominator, compliant numerator, target, and calculation caveats; missing data is not counted as compliance.
- The module is controlled by `statistics_analytics` in Module Control and retains data when disabled.

## 1. Authentication

- Controller: `Auth\LoginController`
- Routes: `GET|POST /login`, `POST /logout`
- Login uses email/password, guest middleware, CSRF protection, and rate limiting.
- Successful login redirects to the intended page or `/worklist`.

## 2. Worklist

- Release status: **Stable — Alpha 1**.
- Controller: `Workflow\WorklistController`
- Route: `GET /worklist`
- Permission: `view_worklist`
- Default scope shows all pushed procedures that remain Scheduled, Arrived, or In Progress, regardless of scheduled date.
- `?scope=pending` shows Scheduled examinations outside today, including overdue and upcoming appointments.
- Completed, Cancelled, Rejected, Booked-only, and No-Show records are excluded from the Active Procedures list.
- Provides status counts and actions for status changes, viewing, editing, and reporting.

## 3. Appointments

- Controller: `Workflow\AppointmentController`
- Route: `GET /appointments`
- Permission: `view_worklist`
- Daily board provides 36 bookable 15-minute slots from 8:00 AM through 4:45 PM; 5:00 PM is closing time.
- Daily, weekly, and monthly views summarize appointments by modality; monthly dates show total appointments with modality totals on hover.
- Patient search and registration are available from the dashboard, with new patients passed directly into appointment booking.
- Booking is integrated with study scheduling, prevents active double bookings per modality, and supports multiple procedures.
- The staff member who gives an appointment is recorded. Date/time or modality changes require a reason and retain a permanent history.
- Modality rows are locked during booking to serialize competing requests; MariaDB checks enforce operating hours, slot alignment, and non-empty audit reasons.
- Staff names are retained as audit snapshots. Legacy records are explicitly labelled when the original staff member cannot be reconstructed.
- Appointment CRUD uses history-preserving cancellation. New bookings remain tagged `Booked` until pushed to the Worklist, and unattended Scheduled bookings become `No-Show` after the 5:00 PM cutoff.
- Appointment settings allow administrators to include or exclude each modality from new appointment booking.

## 4. Patient Management

- Controller: `Workflow\PatientController`
- Routes: patient index, create, store, show, edit, update, and delete under `/patients`
- Permissions: `view_patients` for viewing; `manage_patients` for changes
- National Identification Number is the required, unique primary patient identity for registration and editing.
- New MRNs are generated automatically as `RADHWKKS` plus five digits and remain permanent; existing legacy MRNs are preserved.
- Citizenship is required and standardized as Citizen, Non Citizen, or Undecided.
- Directory search covers National ID, patient name, and MRN and is paginated at 25 records.
- Patient details include demographics and complete examination history.
- Deletion is permitted only when the patient has no examination history.

## 5. Study Scheduling and Workflow

- Controller: `Workflow\StudyController`
- Routes: scheduling, details, editing, status updates, notes, and completed exams under `/studies`
- Permissions: `schedule_exams`, `view_worklist`, `update_status`, `complete_studies`, `cancel_studies`, and `write_radiographer_notes`
- Supports one or more procedures during initial scheduling.
- Intake type separates Appointment, Walk-In, and Exam Request workflows. Only Appointment requires an 8:00 AM–5:00 PM 15-minute slot; Walk-In and Exam Request enter the Worklist immediately.
- Modalities excluded from appointment booking remain available for Walk-In and Exam Request intake.
- Individual Scheduled or Arrived examinations can be edited.
- Valid active flow is Scheduled → Arrived/In Progress → Completed.
- Completed, Cancelled, and Rejected are terminal states.
- Accession numbers use the configured prefix: `PREFIX-YYYYMMDD-RANDOM`.
- Attending staff assignments record `assigned_at`.

## 6. Reporting

- Controller: `Workflow\ReportController`
- Routes: `/studies/{study}/report`, `/studies/{study}/print`, and `/reports`
- Permissions include `write_report`, `finalize_report`, `update_finalized`, `add_addendum`, `view_own_reports`, `view_all_reports`, `print_reports`, and `search_reports`.
- Draft, preliminary, correction, and addendum workflows use an editor-neutral HTML adapter. Administrators select Tiptap (default), CKEditor 5, TinyMCE, or Quill under **Settings → Reporting**.
- Editor changes preserve existing report HTML, structured templates, AI insertion, word counts, Ctrl+S draft saving, focus mode, server-side sanitization, signatures, and version history.
- Finalized reports have a controlled one-hour correction window for authorized users.
- Later changes use timestamped addenda.
- Only finalized reports can be printed or returned by report search.

## 7. AI-Assisted Reporting

- Controller: `Workflow\AiController`
- Routes: report generation and summarization under `/studies/{study}`
- Permissions: `ai_generate`, `ai_summarize`
- Providers: Google Gemini or OpenAI
- API keys are encrypted in the `app_settings` table.

## 8. Completed Examinations

- Controller: `Workflow\StudyController@completed`
- Route: `GET /completed-exams`
- Permission: `view_worklist`
- Defaults to today's terminal examinations.
- Supports all-time Completed, Cancelled, and Rejected filters with 25-record pagination.

## 9. User Profile

- Controller: `ProfileController`
- Routes: `GET /profile`, `PATCH /profile`, `PATCH /profile/password`, `PATCH /profile/locale`
- Users can update avatar, nickname, phone, and their English/Bahasa Melayu interface preference.
- Password changes are submitted separately and require the current password.
- Name, designation, grade, email, and role remain administrator-managed.

## 10. Administration

- Dashboard: `GET /admin`
- CRUD modules: modalities, regions, procedures, departments, and users
- Each module uses its corresponding `manage_*` permission.
- RBAC roles are stored only through the `role_user` pivot; there is no legacy role column.

## 11. Application Settings

- Controller: `Admin\SettingsController`
- Routes: `GET|PUT /admin/settings`
- Permission: `manage_settings`
- Tabs: Appointments, Hospital Information, RIS Configuration, AI Integration, Reporting, and Staff Options
- Includes facility identity/contact details, logo, timezone, date format, accession prefix, report footer, AI provider, and encrypted API key.
- Timezone and date-format settings are applied at runtime and print reports use facility branding.

## 12. AJAX Metadata

- Controller: `Workflow\AjaxController`
- Routes: `/ajax/regions` and `/ajax/procedures`
- Permission: `schedule_exams`
- Supplies region and procedure choices for scheduling forms.

## 13. Interface

- Primary layout: `resources/views/layouts/adminlte.blade.php`
- Navigation: `config/navigation.php`
- Frontend: AdminLTE 4, Bootstrap 5, Font Awesome, Vite, Sass, and vanilla JavaScript
- Supports light, dark, and automatic color modes, fullscreen, responsive tables, sticky headers/actions, expandable table workspaces, responsive sidebar branding, and mobile-optimized Appointment and Patient pages.

## 14. Testing

- PHPUnit uses an in-memory SQLite database.
- Current suite: 43 tests and 125 assertions.
- Coverage includes authentication redirects, RBAC, status transitions, report integrity, accession prefixes, Active Procedures, Pending Schedule, appointment lifecycle/integrity, Worklist pushing, No-Show handling, modality deletion safety, National ID uniqueness, immutable MRNs, patient management, and slot-free Walk-In/Exam Request intake.
# Multidisciplinary Team (MDT) Case Studies

Doctor-facing module for complex longitudinal cases. A case links one patient to one or more imaging studies, a lead clinician, a multidisciplinary team, a meeting date, the clinical question, discussion summary, consensus decision, follow-up plan, and an immutable event timeline. Closed cases are read-only.

# Reporting governance

Reports can be drafted and finalized only after the examination is completed and a report has been requested. Finalization is restricted to users holding the Radiologist role. Modalities selected under **Settings → Reporting** additionally require the current user to be the study's assigned primary radiologist.

Medical Officers can issue a clearly labelled preliminary report after examination completion. The system records its author and timestamp. A preliminary report remains non-final and can subsequently be reviewed, edited, and finalized only by a Radiologist.

# Doctor Dashboard

The authenticated landing dashboard is optimized for Radiologists, Medical Officers, and the Head of Department. It presents today's exam activity, arrivals, in-progress procedures, outstanding draft and preliminary reports, assigned active examinations, personal reporting totals, upcoming MDT cases, and recent final reports. Queues and action labels adapt to the signed-in doctor's role.

# Staff designation and grade configuration

Administration users select professional designations and grades from controlled dropdown lists. Administrators maintain both lists under **Settings → Staff Options**, one value per line. Existing legacy values remain visible during editing even if an option is later removed from the central list.

# Administration Dashboard

The Administration Dashboard consolidates daily examination and appointment activity, report backlog, MDT workload, administrative exceptions, RIS configuration readiness, recent examinations, status distribution, modality configuration and workload, user/role coverage, and direct links to all master-data modules. Attention items are shown before informational charts so urgent access and workflow gaps are immediately visible.

# System health and audit logging

Administrators can monitor PHP, Laravel, database version and response time, operating system, web server, application environment, debug state, memory, disk, database size, cache, queue and available server-load information. The system audit log records authentication and state-changing requests with actor, event, route, HTTP method, affected model identifier, result, timestamp, IP address and user-agent. It intentionally excludes passwords, API keys, patient form payloads, clinical notes and report content.

The administrator landing experience uses a command-center hierarchy: readiness and exceptions first, task-based navigation second, and detailed operational, resource and governance tables afterward. The responsive header collapses into a two-column status grid on small screens.
# Phase 2 Reporting Quality

Structured templates may be scoped globally, by modality, or by procedure and are versioned when edited. Every preliminary, draft, finalized correction and addendum creates an immutable report-version snapshot with a content hash. Finalization creates a Radiologist electronic signature and SHA-256 signature hash.

Critical results use a controlled workflow of **Raised → Communicated → Acknowledged**, retaining the responsible staff and timestamps. The Reporting Quality dashboard summarizes pending work, preliminary reports, 24-hour finalizations, open critical results, median turnaround time and 30-day Radiologist workload. Finalized reports can be peer reviewed as Agree, Minor discrepancy or Major discrepancy.
# Operational Enhancements

Potential duplicate patients are grouped by matching name and birth date for authorized review. A confirmed merge moves studies and MDT cases to the surviving permanent MRN, preserves a source snapshot and reason, and is captured by the system audit log.

Study attachments use private application storage with controlled download routes, file-type and 10 MB size restrictions, uploader attribution and SHA-256 file hashes. Electronically signed final reports can be downloaded as branded A4 PDFs containing the signature timestamp and verification hash.

Appointment opening time, closing time and slot duration are configurable under Appointment Settings. Procedure master data supports unique billing charge codes and standard RM amounts. English and Bahasa Melayu are selectable per user, with localized navigation, common workflow terminology, accessibility labels, authentication and validation messages; English remains the fallback for untranslated or newly introduced text.
# Clinical Catalogue Administration

Modalities, anatomical regions and procedures use an active/inactive lifecycle so historically used master data can be retired without deletion. Directories support search and operational filters, expose usage counts and billing completeness, and disable destructive actions when clinical references exist. Modality workflow settings consolidate appointment eligibility and strict Radiologist finalization. Region names are unique within a modality, and the region catalogue uses collapsible modality groups.
# Notifications, Consent, Billing and Locale

Patient contact preferences separately record email and SMS consent. Final-report, critical-result and appointment-reminder events enter a provider-neutral delivery outbox only when the channel is enabled and consent/contact requirements are satisfied. Administrators can filter delivery status and return failed messages to the queue. Actual delivery, attempt processing and provider response handling require a deployment-specific SMTP/SMS adapter and background worker.

Studies support Not Billed, Pending, Paid, Waived, Exempted and Cancelled billing states with amount, responsible user, timestamp and mandatory reasons for exceptional outcomes. This is a clinical charge/status foundation and does not yet provide invoices, receipts, payment collection, reconciliation or accounting-system integration.
