# Oziris Radiology Information System (RIS)

Oziris RIS is a web-based radiology information system built with Laravel 12, AdminLTE 4, Bootstrap 5, and MariaDB/MySQL. It supports the clinical journey from patient registration and online exam requests through scheduling, acquisition, governed reporting, result delivery, audit, and DICOM interoperability.

## Current capabilities

- **Asset management** — Optional physical and biomedical asset register with PTJ catalogue, custody, annual verification, governed documents, inspection, maintenance, calibration, transfer, loss/damage, disposal approval separation, SPPA/MySPS reconciliation export, printable support records and immutable lifecycle history. Site deployment follows [ASSET_GOVERNANCE_ACCEPTANCE.md](ASSET_GOVERNANCE_ACCEPTANCE.md).

- **Telegram staff notifications** — Optional privacy-minimized exam-request cards for verified attending/specific staff, with acknowledgement-only actions and audited delivery. See [TELEGRAM_NOTIFICATIONS.md](TELEGRAM_NOTIFICATIONS.md).

- **Notification Center** — Optional radiology-operations alerts and technical monitoring with severity, assignment, acknowledgement, resolution, deduplication and Telegram routing. See [NOTIFICATION_CENTER.md](NOTIFICATION_CENTER.md).

- **Patient management** — Registration, immutable MRN generation, identity search, demographic history, duplicate detection, and controlled merge.
- **Clinical exam requests** — Optional authenticated staff portal with patient search/registration, modality → region → procedure selection, priority, mobile-exam justification, radiology review, clarification, rejection, and transactional conversion into a Study.
- **Malaysian request form** — System-generated A4 portrait print view aligned to the field conventions of MOH form PER.SS-RA301 (Pind. 1/2018), subject to local controlled-form policy.
- **Scheduling and appointments** — Configurable slots, appointment boards, conflict protection, No-Show handling, cancellation history, and Worklist push.
- **Worklist and acquisition** — Scheduled, Arrived, In Progress, Completed, Cancelled, and Rejected workflows with staff accountability.
- **Clinical catalogue** — Modalities, regions, procedures, charge codes, lifecycle controls, and a billing-ready Mobile X-Ray catalogue with portable adult, paediatric, and neonatal procedures.
- **Reporting governance** — Draft, preliminary, finalized, signed PDF, report versions, addenda, templates, administrator-selectable rich-text editors, critical-result communication, peer review, and quality analytics.
- **Patient journey tracking** — Optional internal and approved-public appointment/exam/report tracking with hashed access codes, DOB verification, final-report sharing controls, revocation, code reissue, and append-only access events.
- **DICOM interoperability** — Study identifiers, MWL contract/gateway, MPPS handling, storage-commitment status, PACS/DICOMweb query, viewer launch controls, and reconciliation.
- **Clinical collaboration** — MDT case studies, assigned teams, discussion records, decisions, and follow-up plans.
- **Staff messaging** — Optional authenticated direct/group conversations with participant isolation, live updates, unread alerts, announcement deadlines, priorities, acknowledgement, resolution, read state, and permission-filtered patient/exam context.
- **Security and administration** — RBAC, MFA, session controls, lockout, break-glass access, tamper-evident audit logs, attachment quarantine, module control, settings-driven sidebar branding, users, and operational dashboards.
- **Localization and accessibility** — English/Bahasa Melayu preference, responsive AdminLTE interface, themes, keyboard navigation, and accessible status feedback.
- **AI assistance** — Governed Gemini or OpenAI report drafting/summarization with encrypted credentials, identifier minimization, approval controls, and mandatory human verification.

## Optional modules

The optional **Inventory & Consumables** capability provides batch/lot and expiry-controlled stock, transactional examination usage, general department/room/modality issues, wastage and damage recording, configurable low-stock and expiry alerts, suppliers, purchase orders and receiving, location transfers, barcode/QR lookup, batch-recall patient tracing, analytics and CSV/PDF exports, mandatory contrast parameters, extravasation documentation, reversal history, and audit traceability. General issues remain separate from patient clinical records.

Administrators control optional modules from **Administration → Module Control**. Disabling a module hides its navigation and blocks its routes without deleting clinical or audit records.

| Module key | Staff route | Public route | Default |
|---|---|---|---|
| `clinical_exam_requests` | `/exam-requests` | None | Disabled |
| `patient_journey_tracking` | `/tracking` | `/track` | Disabled |
| `user_messaging` | `/messages` | None | Disabled |
| `inventory_consumables` | `/admin/inventory` and examination details | None | Disabled |
| `asset_management` | `/assets` | None | Disabled |
| `statistics_analytics` | `/statistics` | None | Disabled |

The optional **Statistics & Analytics** module provides operational examination volumes, modality and procedure activity, transparent staff contribution and modality mix, reporting turnaround, period-over-period trends, appointment no-shows, age/oncology/MDT mix, referral demand, peak activity patterns, critical-result communication, peer review, contrast/extravasation and consumable safety insights, documentation completeness, governed CSV export, and a separate secondary **MOH Standards** dashboard. MOH calculations retain their definition year, numerator, denominator, target, and data-quality caveats so local operational measures are not presented as national standards.

## Quick start

Requirements: PHP 8.2+, Composer, Node.js/npm, and MariaDB or MySQL.

```bash
git clone <repo-url> oziris-radiology
cd oziris-radiology
composer install
npm install
cp .env.example .env
# Configure DB_DATABASE, DB_USERNAME, DB_PASSWORD and APP_URL.
php artisan key:generate
php artisan migrate
php artisan db:seed --class=DatabaseSeeder
php artisan storage:link
npm run build
php artisan serve
```

Local URL: `http://127.0.0.1:8000`

Development-only seeded administrator: `admin@radiology.com` / `password`. Change all seeded credentials before any shared or production deployment.

## Development commands

```bash
php artisan test
php artisan route:list
php artisan migrate:status
php artisan optimize:clear
npm run dev
npm run build
```

### Production-representative test profiles

The default suite remains fast and isolated with SQLite. Additional profiles use the disposable MariaDB database `radiology_ris_test`; never point them at a development or clinical database.

```bash
composer test:mariadb
composer test:queue
npm run test:browser
npm run test:browser:desktop
```

Copy `.env.testing.mariadb.example` when local credentials differ from the safe defaults. Browser tests target `http://127.0.0.1:8000` unless `PLAYWRIGHT_BASE_URL` is set. The Playwright suite covers desktop and mobile Chromium smoke tests, authentication boundaries, and serious/critical Axe accessibility findings. Failed traces, screenshots, and video are written under `storage/app/test-results` and are ignored by Git.

GitHub Actions runs the isolated PHP suite, frontend production build, MariaDB contract checks, database-queue persistence checks, and desktop browser/accessibility tests. The current local baseline is 142 passing PHP tests with 615 assertions, 6 passing desktop/mobile browser checks, and no npm vulnerability findings as of 18 July 2026. See `LOCALHOST_TEST_REPORT_2026-07-18.md` for the detailed development assessment and known gaps.

## Architecture

- **Backend:** Laravel 12, PHP 8.2, Eloquent ORM, service layer for governed workflows
- **Database:** MariaDB/MySQL with foreign keys, lifecycle constraints, and operational indexes
- **Frontend:** Blade, Bootstrap 5, AdminLTE 4, Font Awesome 6, Tiptap (default), CKEditor 5, TinyMCE, Quill, Sass, Vite
- **Authentication:** Custom session authentication with RBAC, MFA, lockout, and secure-session middleware
- **AI:** Provider abstraction for Gemini and OpenAI
- **Documents:** DomPDF for signed clinical report PDFs; browser A4 printing for clinical request forms

## Documentation

| File | Purpose |
|---|---|
| `ROADMAP.md` | Completed milestones, active validation, and future work |
| `ARCHITECTURE.md` | Technical architecture and request lifecycle |
| `DOMAIN.md` | Entities, relationships, and status machines |
| `MODULES.md` | Module, route, controller, and view reference |
| `CLINICAL_EXAM_REQUESTS.md` | Staff request and radiology review workflow |
| `PATIENT_JOURNEY_TRACKING.md` | Internal and public journey tracking controls |
| `DICOM_CONFORMANCE_STATEMENT.md` | Development DICOM integration baseline |
| `DOWNTIME_AND_RECOVERY.md` | Downtime, backup, restoration, and reconciliation |
| `P1_SECURITY_OPERATIONS.md` | Security operations and administrative controls |
| `CONTRIBUTING.md` | Development and review workflow |

## Contributing

Contributions that improve patient safety, workflow reliability, accessibility, security, interoperability, documentation, or automated testing are welcome through the project's controlled review process. Start with `CONTRIBUTING.md` and `CODING_STANDARDS.md`, create a focused feature branch, and submit a pull request with a clear clinical or operational rationale.

Before submitting a change:

- Do not include real patient information, credentials, private keys, access tokens, production logs, or proprietary hospital data.
- Add or update tests for changed behavior and run `composer quality` plus the relevant MariaDB, queue, browser, and frontend checks.
- Preserve audit history, authorization boundaries, finalized-report governance, and optional-module isolation.
- Document migrations, configuration changes, operational risks, rollback steps, and any required clinical validation.
- Keep formatting-only changes separate from functional changes whenever practical.

Bug reports and feature proposals should contain reproducible steps, expected and observed behavior, affected roles/modules, and sanitized evidence. Security or patient-safety concerns must be reported privately to the project maintainer or the deploying organization's authorized security contact rather than posted publicly.

## Donations and sponsorship

Financial or in-kind support may be used for development infrastructure, automated testing, accessibility work, security review, documentation, interoperability validation, and approved community development. No public donation account or payment link is configured in this repository at present.

Organizations interested in sponsorship, equipment access, test infrastructure, clinical review, translation, documentation, or engineering contributions should contact the project maintainer through an approved private channel. Sponsorship does not provide access to patient data, security credentials, clinical records, or influence over clinical-safety and governance requirements. Any future donation link should identify the legal recipient, intended use of funds, applicable fees, refund policy, and financial-reporting arrangements before publication.

## Production boundary

Automated tests and local integration checks do not replace clinical governance approval, privacy review, penetration testing, modality/PACS vendor acceptance, disaster-recovery exercises, or validation of the facility's controlled forms and operating procedures.

## License

Proprietary — internal use.
