# 00 — Overview & Architecture Decisions

## What we're building

A multi-clinic booking module inside the existing ERP: patients search doctors by specialty and
branch, book a clinic visit or online video consultation, pay online, get diagnosed/prescribed,
chat with their doctor, and rate the doctor and clinic. Five roles: Super Admin, Clinic Admin,
Receptionist (optional), Doctor, Patient. Full business rules are in the earlier project-details
PDF/artifact — this document only covers **how it plugs into this specific codebase**.

## Reuse map — decide once, apply everywhere

| Concept from the brief | Reuse existing ERP code? | Concrete decision |
|---|---|---|
| "Clinic" / "Branch" / "المركز" | **Yes** — `App\Models\Core\Branch` (`app/Models/Core/Branch.php`, table `branches`) already models a generic company branch (code, name, address, contact, manager, `is_active`) | Add a new 1:1 `ClinicProfile` model/table extending `Branch` with clinic-only fields (logo, working hours, commission, avg rating). Do **not** create a parallel `Clinic` table. A branch "is a clinic" simply by having a `clinic_profiles` row. |
| Super Admin | **Yes** — existing `App\Models\Admin` (guard `admin`), existing Spatie roles/permissions | No new account type. Existing Super Admin role gets new `clinic.*` permissions. |
| Clinic Admin / Receptionist | **Yes** — same `Admin` model/guard, same Spatie system | Two new Spatie roles (`Clinic Admin`, `Receptionist`) under guard `admin`. **New**: `admins.branch_id` (nullable FK) so these accounts can be scoped to one branch — this column and the scoping logic don't exist yet anywhere in the ERP; see `03-permissions-and-roles.md`. |
| Doctor | **New guard** | `admins` guard is for ERP staff, not appropriate for a doctor's own portal login. Mirror the existing `employee` guard/portal pattern (`config/auth.php`, `routes/portal.php`) with a new `doctor` guard/provider. New `App\Models\Clinic\Doctor extends Authenticatable`, table `clinic_doctors`, portal auth columns (`password`, `remember_token`) directly on the table — exactly how `hr_employees` was extended for self-service login. |
| Patient | **Reuse `web` guard** | The site already has customer accounts (`App\Models\User`, used by `Site\AuthController`/`UserController`/orders). A patient is a site customer with an extra medical profile. New `App\Models\Clinic\PatientProfile` (1:1 with `User`) holds the medical-history fields; no new auth system. |
| Booking payment | **Partially reuse** | `App\Services\Payment\PaymentGatewayManager` + gateway adapters (Stripe/Paymob/PayPal, config via `App\Models\Payment\PaymentGateway`) are generic and reusable as-is. `App\Models\Payment\PaymentTransaction` is **not** reusable without a refactor (hard FK to `sales_orders`). Decision: new `clinic_payments` table, call the manager/adapters directly — see `models/Payment.md`. |
| Notifications (booking confirmed, reminder, new chat message, new review) | **Yes** — `App\Services\System\NotificationService` already writes to Laravel's native `notifications` table via `DatabaseNotification::create()` | Follow the same call pattern for every Clinic-module event; do not introduce Notification classes or a second custom notifications table. |
| Audit / activity log (e.g. who edited a prescription) | **Yes** — `App\Models\System\ActivityLog` already exists | Log prescription edits and other sensitive changes there instead of a bespoke `clinic_medical_record_revisions` table, unless a structured diff view is later needed. |
| Real-time chat | **New dependency** — Laravel Reverb | Confirmed with the user. `BROADCAST_CONNECTION` is currently `log`; nothing broadcast-capable is installed. |
| Video consultations | **New dependency** — Agora | Confirmed with the user. No existing precedent in this codebase. |
| Mobile app backend | **New** — Laravel Sanctum | `routes/api.php` does not exist yet, `laravel/sanctum` is not in `composer.json`. Both need adding (Phase 5, see `05-roadmap.md`). |

## Guard summary (after this module ships)

| Guard | Provider / model | Who | Existed before this module? |
|---|---|---|---|
| `web` | `users` / `App\Models\User` | Site customers **and now Patients** | Yes — reused, extended via `PatientProfile` |
| `admin` | `admins` / `App\Models\Admin` | ERP staff, **now including Clinic Admin & Receptionist roles** | Yes — reused, `branch_id` column added |
| `employee` | `employees` / `App\Models\HR\Employee\Employee` | HR self-service portal | Yes — untouched, just the pattern we copy |
| `doctor` *(new)* | `clinic_doctors` / `App\Models\Clinic\Doctor` | Doctors' own portal | **New**, mirrors `employee` exactly |

## New composer dependencies to add

| Package | Purpose | When |
|---|---|---|
| `laravel/sanctum` | Token auth for the mobile app's `routes/api.php` | Phase 5 |
| `laravel/reverb` | Real-time chat broadcasting | Phase 4 |
| `agora/*` (server SDK, e.g. `agora/token-builder` or REST calls — no official first-party Laravel package, so this is typically a thin service class around Agora's REST/token API rather than a composer package) | Video consultation token/session generation | Phase 5 |

## New route files

| File | Guard | Mirrors |
|---|---|---|
| `routes/doctor.php` *(new)* | `doctor` | `routes/portal.php` exactly (prefix `doctor`, `guest:doctor` for login, `['auth:doctor','doctor.active']` for the rest) |
| `routes/api.php` *(new)* | `sanctum` | Standard Laravel API routes file — doesn't exist in this project yet, must also be registered in `bootstrap/app.php`'s `withRouting()` |

`routes/admin.php` (Clinic Admin/Super Admin screens) and `routes/web.php` (patient-facing
booking pages, added to the existing localized `Route::group` alongside the current `Site\*`
routes) are **extended**, not created.

## What this module does *not* need to build

- A new auth/login system for patients (reuse Site's existing one).
- A new admin RBAC system (reuse Spatie `laravel-permission`, already installed).
- A new notifications table/pipeline (reuse `NotificationService`).
- A new payment-gateway configuration screen (reuse `PaymentGatewayController`/`PaymentGateway`).