# AGENTS.md — Oziris RIS (Laravel 12)

## Project Identity

- **Project**: Oziris Radiology Information System (RIS)
- **Framework**: Laravel 12
- **Frontend**: Bootstrap 5, AdminLTE 4, Font Awesome 6, selectable Tiptap / CKEditor 5 / TinyMCE / Quill report editors
- **Database**: MariaDB / MySQL
- **Build Tool**: Vite + Sass
- **Workspace Root**: Current repository root (do not assume an absolute path)
- **Default Local URL**: http://127.0.0.1:8000

> IMPORTANT:
> Always use the currently mounted workspace root.
> Never assume the repository is located at a fixed Windows path.
> All commands should be executed relative to the current workspace.

---

# Development Commands

## Install dependencies

```bash
composer install
npm install
```

## Development

```bash
php artisan serve
npm run dev
```

## Production build

```bash
npm run build
```

## Database

```bash
php artisan migrate
php artisan db:seed
```

## Clear caches

```bash
php artisan optimize:clear
```

## Tests

```bash
php artisan test
```

## Useful diagnostics

```bash
php artisan route:list
php artisan about
git status
```

---

# Architecture

- Laravel MVC architecture
- Service Layer for complex business logic
- AdminLTE 4 master layout
- Bootstrap 5 UI
- RBAC using Roles & Permissions
- Vite asset pipeline
- Editor-adapter reporting layer with administrator-selected default (Tiptap by default)
- AI provider abstraction through AiService
- Public storage via Laravel storage link

---

# Core Modules

- Authentication
- Dashboard
- Patients
- Studies
- Worklist
- Reports
- Modalities
- Procedures
- Regions
- Departments
- Users
- Settings
- DICOM Integration
- Module Management

---

# Route Structure

Authentication

```
/login
/logout
/profile
```

Workflow

```
/patients
/studies
/worklist
/reports
/completed-exams
/ajax/*
```

Administration

```
/admin
/admin/users
/admin/settings
/admin/modalities
/admin/procedures
/admin/regions
/admin/departments
/admin/dicom
/admin/modules
```

---

# Models

## User

- Roles
- Avatar
- Profile

## Patient

- MRN generation
- Searchable

## Study

- Accession generation
- Workflow status
- Assignment

## Report

- Draft
- Finalized
- Sanitized editor-neutral HTML body

## AppSetting

- Key/value settings
- Encrypted API keys

## Role / Permission

RBAC

---

# Coding Standards

## Controllers

- PascalCase
- Singular
- Controller suffix

Example

```
PatientController
ReportController
ModuleController
```

## Models

- PascalCase
- Singular

## Views

- Dot notation
- kebab-case folders

Example

```
admin.settings.index
admin.modules.index
workflow.worklist.index
```

## Routes

- Resource routes where appropriate
- kebab-case URLs

## Icons

Font Awesome 6 only.

## Styling

Bootstrap utilities first.

Custom SCSS only when necessary.

---

# Workflow

1. Register patient
2. Create study
3. Schedule study
4. Radiographer performs study
5. Complete study
6. Radiologist writes report
7. Finalize report
8. Print finalized report

---

# AI Integration

Supported providers

- Gemini
- OpenAI

API keys are stored encrypted through AppSetting.

---

# Storage

Use Laravel storage link.

```
php artisan storage:link
```

---

# Testing

Primary verification

```
php artisan test
```

Manual verification

- Login
- Patient registration
- Study creation
- Worklist
- Report creation
- Report finalization
- Module management
- DICOM pages

---

# Development Rules

- Keep controllers thin.
- Put business logic into services.
- Never hardcode absolute Windows paths.
- Always use Laravel helpers.
- Preserve existing coding style.
- Keep changes minimal and focused.
- Do not refactor unrelated code.
- Never modify generated migrations unless requested.
- Preserve backward compatibility unless instructed otherwise.

---

# Git Rules

Before making changes

```
git status
```

After changes

```
git diff
```

Never overwrite unrelated user changes.

Never discard existing work unless explicitly instructed.

---

# Codex Instructions

Always operate relative to the mounted workspace.

Never assume:

```
C:\oziris-radiology
```

or any other absolute path.

Always determine the workspace root dynamically.

Before making edits:

1. Verify workspace exists.
2. Verify target files exist.
3. Apply minimal patches.
4. Preserve formatting.
5. Report modified files.

If workspace access fails, report the exact failing path instead of guessing.
