# Oziris RIS — Codex Handoff Log

Last updated: 17 July 2026 (Asia/Kuala_Lumpur)

This file is the continuity record for resuming development with Codex on another device. Read `AGENTS.md` first, then this file, before making changes.

## Repository and branch

- GitHub: <https://github.com/projectoziris/oziris-radiology.git>
- Active application branch: `master`
- Current application commit when this log was created: `c142d1e`
- Commit: `c142d1e Add theme controls and expandable tables`
- Local project root on the original device: `C:\radiology-ris`
- Application URL: <http://127.0.0.1:8000>

> Important: GitHub currently reports `main` as the default branch, but `main` has a separate, divergent initial history. The working Oziris RIS application is on `master`. Do not force-push or merge `main` until the branch strategy has been reviewed.

Clone and select the correct branch:

```bash
git clone https://github.com/projectoziris/oziris-radiology.git
cd oziris-radiology
git switch master
git status
```

Expected status:

```text
On branch master
Your branch is up to date with 'origin/master'.
```

## Current progress checklist

### Phase 1 — Core RIS

- [x] Laravel 12 application setup
- [x] MariaDB data model and seed data
- [x] Custom email/password authentication
- [x] Patient registration and search by National ID, MRN, and name
- [x] Unique National ID as main identity and standardized citizenship
- [x] Permanent automatic `RADHWKKS#####` MRN generation for new patients
- [x] Appointment, Walk-In, and Exam Request intake workflows
- [x] Cascading modality, region, and procedure selection
- [x] Active Procedures Worklist across scheduled dates
- [x] Pending Schedule for overdue and future examinations
- [x] Appointment dashboard with daily, weekly, and monthly views
- [x] Modality-based 15-minute appointment slots from 8:00 AM to 5:00 PM
- [x] Push-to-Worklist lifecycle and automatic No-Show classification
- [x] Appointment staff attribution and reason-required change history
- [x] Appointment modality inclusion/exclusion settings
- [x] Study status workflow
- [x] Completed, cancelled, and rejected examination views
- [x] Radiologist reporting with Quill
- [x] Draft and finalized report workflow
- [x] Printable finalized reports
- [x] Role-based access control
- [x] Admin CRUD modules
- [x] User profile and avatar management
- [x] AI-assisted report generation integration points
- [x] AdminLTE 4 application shell
- [x] Standard AdminLTE dashboard design
- [x] All authenticated views migrated to the current template
- [x] Font Awesome assets resolved through Vite
- [x] Browser fullscreen control
- [x] Light, Dark, and Auto theme switcher
- [x] Persistent theme selection using `lte-theme` in local storage
- [x] Improved dark-mode design
- [x] Expandable table workspace
- [x] Sticky table headers and action columns
- [x] Responsive table and mobile layout improvements
- [x] Responsive sidebar branding and permission-aware navigation
- [x] Mobile-optimized Appointment and Patient pages
- [x] Appointment integrity constraints, locking, indexes, and audit snapshots
- [x] 28 PHPUnit tests passing with 74 assertions

### Planned enhancements

- [ ] Email notification when reports are finalized
- [ ] PDF report export
- [ ] Study image upload
- [ ] DICOM viewer integration
- [ ] Audit logging for CRUD and workflow changes
- [ ] Appointment reminders by email or SMS
- [ ] Billing integration
- [ ] Malay and English localization
- [ ] HL7/FHIR REST API
- [ ] DICOM modality worklist integration
- [ ] PACS integration
- [ ] Reporting and turnaround-time analytics
- [ ] SSO or LDAP authentication
- [ ] Voice report dictation
- [ ] Custom role-based dashboard widgets

### Production-readiness work

- [~] Expand PHPUnit coverage beyond the current 28 tests
- [~] Convert completed manual browser validation into a reusable automated browser suite
- [~] Continue security review; authentication, RBAC, workflow, report, and appointment integrity have been reviewed
- [~] Continue controller authorization audit; core workflow and administration routes use permission middleware
- [ ] Add database backup and restore procedure
- [ ] Add Windows/XAMPP and production deployment guide
- [ ] Audit query performance and eager loading
- [ ] Define database backup and restore procedures
- [ ] Add deployment documentation
- [ ] Add monitoring and centralized error reporting
- [ ] Perform load testing

## Recently completed UI work

The UI is based on AdminLTE 4, Bootstrap 5, Font Awesome 7, and Vite.

Key implementation files:

- `resources/views/layouts/adminlte.blade.php` — primary authenticated shell
- `resources/views/partials/topbar-tools.blade.php` — theme and fullscreen controls
- `resources/views/partials/navbar.blade.php` — legacy/reusable navbar partial
- `resources/views/partials/sidebar.blade.php` — reusable navigation partial
- `config/navigation.php` — permission-aware sidebar configuration
- `resources/views/admin/dashboard.blade.php` — main AdminLTE dashboard
- `resources/js/app.js` — AdminLTE modules, Quill, and expandable tables
- `resources/scss/app.scss` — light theme, dedicated dark theme, and table design

Theme behavior:

- Light mode retains the standard AdminLTE appearance.
- Dark mode uses custom navy surfaces, improved borders, refined cards, dark form controls, and higher-clarity tables.
- Auto mode follows the operating-system color preference.
- Theme choice is persisted using the `lte-theme` local-storage key.
- A small script in the page head applies the saved theme before CSS loads to avoid a theme flash.

Table behavior:

- Every `.table-responsive` inside `.app-content` is enhanced automatically.
- An expand button is added to the containing card.
- Expanded tables use a fixed workspace and can be restored with the button or `Escape`.
- Headers remain sticky while scrolling.
- A final column named `Actions` becomes sticky on the right.

## Application workflow

1. Register or search for a patient in `/patients`.
2. Schedule an examination in `/studies/create`.
3. Process the examination from `/worklist`.
4. Move the study through Scheduled, Arrived, In Progress, and Completed as appropriate.
5. Request and write a report for completed examinations.
6. Save a draft or finalize the report.
7. Review finished studies in `/completed-exams`.
8. Print finalized reports from the study report page.

## Main routes

- `/login` — sign in
- `/worklist` — daily worklist
- `/patients` — patient directory
- `/patients/create` — patient registration
- `/studies/create` — schedule examination
- `/completed-exams` — finished examinations
- `/reports` — finalized report search
- `/profile` — current-user profile
- `/admin` — administrative dashboard
- `/admin/modalities` — modality management
- `/admin/regions` — region management
- `/admin/procedures` — procedure management
- `/admin/departments` — department management
- `/admin/users` — user management
- `/admin/settings` — application and AI settings

At the time of this log, `php artisan route:list --except-vendor` returned 61 application routes.

## Development environment

Original verified versions:

- Laravel `12.8.1`
- Node.js `26.5.0`
- npm `11.17.0`
- MariaDB `10.4.32` through XAMPP
- Database name: `radiology_ris`

Install on another device:

```bash
composer install
npm install
```

Create local configuration:

```bash
cp .env.example .env
php artisan key:generate
```

Configure the local `.env` database values, then run:

```bash
php artisan migrate
php artisan db:seed --class=DatabaseSeeder
php artisan storage:link
npm run build
php artisan serve
```

Never commit `.env`, API keys, database passwords, production credentials, or patient data.

## Development login

The live seeded login verified during UI testing was:

- Email: `admin@radiology.com`
- Password: `password`

The login form currently expects an email address. Some older documentation mentions `dr.oziris`; verify and update the README or seed data before relying on that value.

## Validation performed

The following checks passed after the AdminLTE and dark-theme work:

- [x] `php artisan view:clear`
- [x] `php artisan view:cache`
- [x] `php artisan route:list --except-vendor`
- [x] `npm run build`
- [x] `git diff --check`
- [x] Live authenticated browser checks
- [x] Dashboard returned HTTP 200
- [x] Worklist returned HTTP 200
- [x] Patient list and registration returned HTTP 200
- [x] Study scheduling returned HTTP 200
- [x] Completed exams returned HTTP 200
- [x] Report search returned HTTP 200
- [x] Profile returned HTTP 200
- [x] Admin CRUD pages returned HTTP 200
- [x] Dark theme persisted after reload
- [x] Auto theme resolved correctly
- [x] Fullscreen entered successfully
- [x] Table expansion and Escape restoration worked
- [x] No HTTP resource or browser console errors during the final UI checks

Current build output contains upstream Sass deprecation warnings from Bootstrap/AdminLTE imports. The build still completes successfully. Treat these as dependency-maintenance work, not a current runtime failure.

## Known cautions

- There is no configured automated application test suite yet; most validation is manual and browser-based.
- Do not use `git push --force` on `main` or `master`.
- Review the divergent `main` branch before changing GitHub's default branch.
- Preserve valid study status transitions; do not allow Completed studies to return to Scheduled.
- Finalized reports should remain immutable unless a formal addendum workflow is implemented.
- Confirm permissions when adding new navigation entries and controller routes.
- The AI API key belongs in encrypted application settings or environment configuration, never in Git.
- Verify `public/build/manifest.json` after every production frontend build.

## Recommended next session

1. Read `AGENTS.md`, `ARCHITECTURE.md`, `DOMAIN.md`, `MODULES.md`, `ROADMAP.md`, and this file.
2. Confirm `git switch master` and a clean working tree.
3. Run `composer install` and `npm install` if dependencies are missing.
4. Configure `.env` and verify the MariaDB connection.
5. Run migrations and seeders in a disposable development database.
6. Run the build and Blade compilation checks.
7. Open `/admin`, `/worklist`, and `/patients/create` in both light and dark modes.
8. Prioritize PHPUnit feature tests for authentication, permissions, study transitions, and report finalization.
9. Decide whether `master` should become GitHub's default branch or whether its history should be safely migrated to `main`.

## Git workflow for continuing

Before work:

```bash
git switch master
git pull --ff-only origin master
git status
```

After completing and validating a change:

```bash
git add <specific-files>
git commit -m "Describe the completed change"
git push origin master
```

Avoid staging unrelated files. Always inspect `git status` and `git diff --check` before committing.

## Phase 1 completion update — 17 July 2026

Phase 1 core workflow is now complete.

- Daily Worklist and Pending Schedule are separate views under `/worklist`.
- Pending Schedule includes overdue and upcoming Scheduled examinations.
- Patient management now supports automatic immutable MRNs, pagination, details, editing, examination history, and safe deletion.
- Patient records with examination history cannot be deleted.
- Workflow, appointment, integrity, and patient regression coverage now totals 28 tests with 74 assertions.
- The application currently exposes 68 non-vendor routes.
- `ROADMAP.md` and `MODULES.md` were refreshed to describe the current implementation.
# 17 July 2026 — Phase 1 Appointment Module

- Added a daily appointment board at `/appointments` using the existing study schedule as the single source of truth.
- Added 36 appointment starts per day at 15-minute intervals from 8:00 AM through 4:45 PM, with 5:00 PM as closing time.
- Replaced free-form examination date/time entry with validated appointment date and time-slot controls.
- Prevented active appointment double-booking while retaining multi-procedure bookings for one patient.
- Added appointment navigation, roadmap/module documentation, and automated workflow coverage.
- Expanded appointments into a dedicated modality-based dashboard with daily, weekly, and monthly calendar views.
- Added dashboard patient search and an appointment-aware patient registration flow.
- Recorded the staff member giving each appointment and added permanent, reason-required rescheduling/modality-change history.
- Hardened appointment integrity with modality-level booking locks, database slot/reason checks, scheduling indexes, durable staff-name snapshots, grouped appointment totals, and corrected permission visibility.
- Normalized the legacy 3:49 PM booking to 3:45 PM and retained the original time in system-generated appointment history.
- Added appointment CRUD lifecycle actions, Worklist push/tagging, automatic No-Show classification after 5:00 PM, cancellation history, and per-modality appointment availability settings.
- Made National Identification Number the main unique patient identity, standardized citizenship values, and changed new immutable MRNs to the `RADHWKKS#####` format while preserving legacy MRNs.
- Separated Appointment, Walk-In, and Exam Request intake: only appointments require slots, while walk-ins and exam requests enter the Worklist immediately using actual intake time.
