# 06 — Overview & Architecture Decisions: Medical Center Expansion (Phase 6+)

## Relationship to the rest of this folder

`00-overview.md` through `05-roadmap.md` planned the original booking module (Phase 0–5: guards,
CRUD, booking/payment, doctor portal, chat/reviews/reports/offers, mobile+video). As of this
writing, the codebase matches that plan through the end of **Phase 4** (bookings, a free-text
medical record, doctor portal, chat/reviews/reports/offers all shipped); **Phase 5 (Sanctum API +
Agora video) has not been built yet** — `routes/api.php` and `laravel/sanctum` still don't exist.

This document starts a **new, additive track — Phase 6 onward** — that does not touch or
renumber `00`–`05`. It turns the module from a generic booking system into a specialized private
medical center covering: obesity treatment & bariatric surgery, internal medicine, endocrinology,
diabetes & its complications, and therapeutic nutrition — while also performing surgical
operations. If Phase 5 (mobile/video) is built later, it slots in independently; nothing here
depends on it.

## What we're building

Depth, not breadth: the existing entities (`ClinicProfile`, `Specialty`, `Doctor`, `Booking`,
`PatientProfile`) stay as-is. What's missing and gets added is **structured clinical data** (the
current `clinic_medical_records` is three free-text columns — diagnosis/prescription/report —
with no way to trend a patient's weight, HbA1c, or blood pressure over time, and no way to run a
"which diabetic patients are out of control" report), plus the specialty-specific workflows that
depend on that structure (bariatric assessment, diabetes complication screening, nutrition plans),
plus the operational pieces a real medical center needs and currently has zero support for:
e-prescriptions, lab orders, surgery scheduling, printable documents, and — critically — a real
link into the ERP's Finance module so clinic revenue shows up on the trial balance instead of
living only in a disconnected `clinic_payments` table.

## Four scope decisions confirmed with the user (govern every phase below)

| Area | Decision | Why it shapes the design |
|---|---|---|
| **Billing** | Full integration with Finance (journal entries, Receipt Voucher, trial balance) — not a simplified standalone ledger | New `clinic_invoices` must post through the same `JournalEntryService`/`JournalPostingService` pipeline every other module uses, not a bespoke one. See `07-database-schema-expansion.md` §Phase 11 and `flows/12-billing-and-posting-flow.md`. |
| **Surgery** | Scheduling + pre/post-op **documentation** only — no bed/ward/admission management | `clinic_surgery_cases` has no room/bed FK; a post-op note is just an `Encounter` with `encounter_type = post_op`, not an inpatient stay record. If admissions are ever needed, that's a separate future phase, not folded in here. |
| **Pharmacy** | Structured e-prescription + print — **no** stock deduction | `clinic_medications` is a lightweight drug list for autocomplete/reporting, not an inventory item. No FK to `Inventory\*`; dispensing a prescription never touches stock. |
| **Insurance** | Cash/card only for now — no payer/claims model | `clinic_invoices.customer_id` always resolves to the patient (via an auto-provisioned `Sales\Customer`), never to an insurance company. No claims table, no coverage percentage field. Flagged as a clean future extension point, not built now. |

## Reuse map — decide once, apply everywhere (Phase 6+ additions)

| Concept | Reuse existing code? | Concrete decision |
|---|---|---|
| Clinical documentation | **Extend, don't replace** | `clinic_medical_records` (diagnosis/prescription/report text + one attachment) stays in the schema for backward compatibility but is superseded by `clinic_encounters` + `clinic_vitals` + `clinic_diagnoses` as the primary structured record going forward. See `07-database-schema-expansion.md` §Phase 6. |
| "Nutritionist" as a provider type | **Yes — reuse `Doctor`** | No new authenticatable model. A nutritionist is a `Doctor` row whose `specialty_id` points at a "Therapeutic Nutrition" `Specialty`. The `doctor` guard, portal, schedule, and booking machinery are unchanged. |
| Medical master data (conditions, drug allergies) | **Yes — reuse `clinic_medical_history_options`** | The existing `type`/`code`/`name(json)` master-data table (condition/medication/attachment_category types) is the established pattern for any new small controlled vocabulary this expansion needs (e.g. surgery procedure types) — extend its `type` enum rather than inventing a parallel options table per feature. |
| Patient identity for billing | **New bridge, not reuse** | `Sales\Customer` has no `user_id` and nothing today links a clinic patient (`users` + `clinic_patient_profiles`) to one. A new `ClinicPatientCustomerProvisioningService` creates/links a `Customer` row on first invoice — see `07-database-schema-expansion.md` §Phase 11 and `models/ClinicInvoice.md`. |
| Journal posting | **Yes — mirror `SalesPostingService`** | `app/Services/Sales/Finance/SalesPostingService.php::postInvoice()` is the template: resolve accounts by priority (line-level → category default → Setting → throw), build balanced lines, post via `JournalEntryService` + `JournalPostingService`. A new `ClinicPostingService` follows the identical shape. |
| AR settlement | **Yes, plus one fix** — `ReceiptVoucher` | `ReceiptVoucherService`/`ReceiptVoucherPostingService` (draft → approved → posted) are reused as-is for collecting patient payments. The one gap: `ReceiptVoucher` today links to an invoice only via a free-text `invoice_reference` field (true even for Sales), so `paid_amount`/`payment_status` never auto-updates on the source document. This expansion adds a proper nullable `clinic_invoice_id` FK and updates the posting service to set it — a general fix, reusable by Sales later too, not a clinic-only hack. |
| Printable documents | **New** | No print/PDF template exists anywhere in the app today (confirmed by full-codebase search) — Phase 12 is a genuinely new capability, not a reuse-and-extend. |
| Reporting | **Yes — extend `ClinicReportService`** | `app/Services/Clinic/Reports/ClinicReportService.php` + `Admin\Clinic\Reports\ClinicReportController` already exist; Phase 13 adds new query methods/report types to the same service rather than creating a parallel reporting stack. |

## New composer dependencies

None required for Phase 6–11. Phase 12 (print center) may need a PDF library if the existing app
has none — **check first**: search `composer.json` for `dompdf`/`mpdf`/`snappy` before adding a
new dependency; if browser-based print (`window.print()` + print CSS) is acceptable for the first
cut, no new dependency is needed at all.

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

- A new patient identity/auth system (reuse `User` + `clinic_patient_profiles`, as already decided in `00-overview.md`).
- A new provider/staff account type for nutritionists (reuse `Doctor` + `specialty_id`).
- A pharmacy inventory or stock-deduction pipeline (explicitly out of scope per the user's decision).
- A bed/ward/admission system (explicitly out of scope per the user's decision).
- An insurance/claims/payer model (explicitly out of scope per the user's decision).
- A new journal/posting engine — reuse Finance's existing `JournalEntryService`/`JournalPostingService`/`ReceiptVoucher` pipeline exactly as Sales does.