# Architecture Overview

## Tech Stack

| Layer        | Technology                          |
|-------------|-------------------------------------|
| Framework    | Laravel 12                         |
| PHP          | 8.2.12                             |
| Database     | MariaDB 10.4.32 (XAMPP)            |
| Frontend     | Bootstrap 5 + AdminLTE 4           |
| Icons        | Font Awesome 6 Free                |
| Editor       | Quill.js (vanilla, no Vue/React)   |
| Build        | Vite + Laravel Vite plugin         |
| CSS Preproc  | Sass (SCSS)                        |
| JS Modules   | ES modules (vanilla JS)            |
| Auth         | Custom LoginController (no Breeze) |
| RBAC         | Custom roles + permissions tables  |
| AI           | Gemini 2.0 Flash / OpenAI GPT-4o-mini |

## Directory Structure (Key)

```
app/
  Http/
    Controllers/
      Auth/LoginController.php
      Admin/{Admin,Dashboard,Modality,Region,Procedure,Department,Settings,User}Controller.php
      Workflow/{Patient,Worklist,Study,Report,Ajax,Ai}Controller.php
      ProfileController.php
    Middleware/PermissionMiddleware.php
  Models/
    User, Patient, Study, Report, Modality, Region, Procedure, Department, AppSetting, Role, Permission
  Services/
    AiService.php
    ReportService.php
bootstrap/app.php              ← middleware alias registration
config/
  app.php (timezone, locale)
  database.php (mysql)
resources/
  views/
    layouts/adminlte.blade.php  ← master layout
    auth/login.blade.php
    admin/{dashboard,modalities,regions,procedures,departments,users,settings}/
    workflow/{patients,worklist,studies,reports}/
    profile/edit.blade.php
    components/                 ← reusable alert, modal, form-input, pagination
  scss/app.scss
  js/app.js
routes/web.php
public/
  build/                        ← Vite output
  storage/ → storage/app/public
  uploads/avatars/
database/
  migrations/
  seeders/
```

## Request Lifecycle

1. Browser hits `http://127.0.0.1:8000/patients`
2. `public/index.php` boots Laravel
3. `bootstrap/app.php` loads middleware (session, csrf, `permission` alias)
4. `routes/web.php` matches `/patients` → `PatientController@index` (auth + permission:manage_patients)
5. `PermissionMiddleware` checks `manage_patients` on user's roles
6. Controller fetches data (paginated patients via `Patient::query()->search(...)`)
7. Returns `view('workflow.patients.index', compact('patients'))`
8. View extends `layouts.adminlte` → renders sidebar, navbar, content with Font Awesome icons
9. Vite injects compiled CSS/JS via `@vite()` directive

## RBAC Design

- **Roles table**: id, name, guard_name, created_at, updated_at
- **Permissions table**: id, name, guard_name, created_at, updated_at
- **Pivot tables**: `permission_role`, `role_user`
- **8 Roles**: Admin, Radiologist, Medical Officer, Radiographer Technologist, Imaging Officer, Nurse, PPK, Head of Department
- **25 Permissions**: `view_dashboard`, `manage_patients`, `schedule_studies`, `perform_studies`, `view_worklist`, `write_reports`, `finalize_reports`, `view_completed_exams`, `view_reports`, `manage_users`, `manage_modalities`, `manage_regions`, `manage_procedures`, `manage_departments`, `manage_settings`, `view_users`, `view_modalities`, `view_regions`, `view_procedures`, `view_departments`, `request_report`, `cancel_study`, `reject_study`, `use_ai`, `manage_all`
- Middleware: `$middleware->alias(['permission' => PermissionMiddleware::class])`

## AI Integration

- `AiController@generate` accepts POST with `report_id`
- `AiService` loads AI provider + API key from `AppSetting`
- Constructs prompt from Modality, Region, Procedure, Patient demographics
- Returns structured report draft as JSON
- Providers: Gemini 2.0 Flash (default, `gemini-2.0-flash`), OpenAI (`gpt-4o-mini`)
- API key encrypted at rest (`AppSetting` model casts `ai_api_key` as `encrypted`)

## Frontend Compilation

```
resources/scss/app.scss  ─┐
resources/js/app.js     ─┤── Vite ──→ public/build/
                         ┘
@vite('resources/js/app.js') in layout
```

- `admin-lte` npm package provides ES modules: `CardWidget`, `PushMenu`, `Treeview`, `Layout`
- Imported in `app.js` and initialized after DOM ready
- Quill initialized in report create/edit views with `#report_body` selector
