diff --git a/.cursor/rules/specialty-modules.mdc b/.cursor/rules/specialty-modules.mdc new file mode 100644 index 0000000..d8abd3c --- /dev/null +++ b/.cursor/rules/specialty-modules.mdc @@ -0,0 +1,31 @@ +--- +description: Ladill Care specialty module architecture and UX standard +globs: config/care_specialty_modules.php,app/Services/Care/SpecialtyModule*.php,app/Http/Controllers/Care/Specialty*.php,resources/views/care/specialty/**,resources/views/care/settings/modules.blade.php +alwaysApply: false +--- + +# Specialty modules — Care design standard + +Full standard: `docs/specialty-module-design-standard.md`. + +## Non-negotiables + +- Specialty modules are **native Care extensions**, not standalone apps. +- Design **workflow first** (stages, queues, payment checkpoints, completion), then screens. +- Reuse Care engines: Workflow, Queue, Billing, Appointments, Documents, Permissions, Reports. +- Use **identical primary actions** (Call Next, Start Consultation, Order Test, Prescribe, Generate Invoice, Discharge, …). +- Prefer extending **`Visit`** as the clinical episode unit before inventing a separate Episode model. +- Contribute to one **patient timeline** — do not create parallel charts. +- Prefer **structured clinical data** over free-text-only fields (AI-ready). + +## Current reality + +Today specialties are a thin layer: catalog activate → departments/queue stubs → generic `specialty/show` waiting list. Do **not** build deep per-specialty UIs until the shared specialty shell exists (KPI dashboard, patient header, left nav Overview/Visits/History/Module Tabs, billing catalog hooks). + +## When adding or deepening a module + +1. Add/update catalog entry in `config/care_specialty_modules.php` (and department type if needed). +2. Define specialty workflow stages + queue map in docs or config — not only a nav label. +3. Wire through the **shared specialty shell**, not a one-off Blade page. +4. Seed billable services into Billing — never hardcode invoice lines in the specialty UI. +5. Gate with role allowlists + practitioner department assignment (existing `SpecialtyModuleService` patterns); Emergency/Blood Bank stay `default_on_paid_plans`. diff --git a/docs/specialty-module-design-standard.md b/docs/specialty-module-design-standard.md new file mode 100644 index 0000000..4b140ba --- /dev/null +++ b/docs/specialty-module-design-standard.md @@ -0,0 +1,222 @@ +# Ladill Care Specialty Module Design & Development Standard + +## Objective + +Develop all specialty modules using a unified architecture, consistent UI/UX, shared workflows, reusable components, and common design principles while allowing each specialty to introduce its own clinical workflows and records. + +Every specialty module should feel like a natural extension of Ladill Care rather than a separate application. + +--- + +## Core Design Principles + +### 1. Workflow-Driven + +Every module begins with the patient journey. + +Do not design screens first. Design the workflow first. + +**Example — Dentistry** + +``` +Appointment → Registration → Payment → Waiting Room → Dental Chair +→ Treatment → Prescription → Payment → Exit +``` + +Every module must define: + +- Entry points +- Service stages +- Payment checkpoints +- Queues +- Completion criteria + +### 2. Episode-Based + +Every patient visit creates a clinical episode. + +``` +Patient → Visit → Episode → Consultation → Treatment → Billing → Completion +``` + +All specialty records belong to an episode. + +> **Implementation note (current Care):** Prefer extending the existing `Visit` as the episode unit first. Introduce a separate `Episode` entity only when multi-visit care plans require it. + +### 3. Timeline-Based + +Every specialty contributes to one unified patient timeline. + +Example: + +``` +09:15 Registration +09:23 Payment +09:35 Doctor Consultation +09:48 X-Ray Ordered +10:15 X-Ray Completed +10:32 Pharmacy +10:50 Exit +``` + +Every module extends the timeline — it does not create a parallel chart. + +--- + +## UI Standards + +Every module should share the same layout: + +``` +------------------------------------------------ +Patient Header +------------------------------------------------ +Patient Summary | Alerts | Insurance | Outstanding Bills | Queue Status +------------------------------------------------ +Left Navigation | Main Workspace | Action Panel +Overview | | +Visits | | +History | | +Module Tabs | | +------------------------------------------------ +``` + +The user should never feel lost switching between specialties. + +### Standard Patient Header + +Every module displays: + +- Patient photo, name, age, gender, patient ID +- Visit number +- Current queue, current doctor +- Insurance, allergies, outstanding balance +- Emergency flags + +### Module Dashboard + +Every specialty module begins with a dashboard of operational metrics. + +**Dentistry example:** Today's patients, waiting, in treatment, completed, revenue today, average treatment time, chairs occupied. + +**Radiology example:** Scans waiting, in progress, reports pending, completed, equipment utilization. + +### Common Screen Sections + +Every specialty should contain: + +| Section | Purpose | +| --- | --- | +| Overview | General patient / ops summary | +| Clinical Notes | Specialty-specific notes | +| Orders | Tests, medications, procedures | +| Billing | Invoices, payments, outstanding, insurance | +| Documents | Images, reports, consent forms | +| History | Previous visits | + +### Standard Action Buttons + +Use identical primary actions across modules: + +Register · Call Next Patient · Start Consultation · Pause · Complete · Refer · Order Test · Prescribe · Generate Invoice · Receive Payment · Print · Discharge + +No module should invent new terminology where a common action already exists. + +--- + +## Queue Guidelines + +Every specialty owns its own queues with specialty-specific stages. + +Examples: + +| Specialty | Stages | +| --- | --- | +| Dentistry | Waiting → Chair Assignment → Procedure → Recovery | +| Radiology | Waiting → Imaging Room → Reporting → Completed | +| Physiotherapy | Waiting → Session → Follow-up | +| Eye Clinic | Vision Test → Refraction → Doctor → Optical Shop | + +Queues should always display: waiting time, priority, assigned staff, expected duration, status. + +--- + +## Billing Guidelines + +Every module integrates with centralized Billing. + +Each service automatically generates billable items. Never hardcode billing. Services generate invoices dynamically (consultation fees, procedures, investigations, consumables, medications, insurance). + +--- + +## Scheduling + +Every specialty supports: appointments, walk-ins, follow-ups, recurring visits, and group sessions where applicable. + +--- + +## Permissions + +Each module defines role-relevant actions for: Receptionist, Nurse, Doctor, Consultant, Cashier, Technician, Administrator. + +Each role only sees relevant actions. + +--- + +## Alerts, Documents, Analytics, AI Ready + +- **Alerts:** specialty-defined clinical/ops alerts (e.g. high-risk pregnancy, critical radiology report). +- **Documents:** image uploads, scanned reports, consent forms, PDF generation, electronic signatures. +- **Analytics:** patient volume, revenue, waiting time, treatment duration, staff utilization, cancellation rate, follow-up compliance. +- **AI ready:** expose structured clinical data (not free-text only) for decision support, coding, summaries, risk scoring, transcription. + +--- + +## Specialty Module Build Prompt + +Use this prompt when implementing a specific specialty: + +> Develop the **[MODULE NAME]** Specialty Module as a native extension of Ladill Care. +> +> Follow the Ladill Care Design System, Workflow Engine, Queue Engine, Billing Engine, Appointment Engine, Notification Engine, Document Engine, Reporting Engine, and Permission Framework. +> +> The module must not behave like a standalone application. It must extend the patient journey already established within Ladill Care. +> +> Include: (1) Dashboard KPIs, (2) full arrival→discharge workflow, (3) specialty queues, (4) clinical workspace with standard layout, (5) billing integration, (6) scheduling, (7) documents, (8) reporting, (9) integration with registration / pharmacy / lab / radiology / accounting / CRM / notifications / audit / API, (10) UX standards — reuse components, shared design system, responsive, keyboard-first for high-volume facilities. + +--- + +## Current implementation status (as of 2026-07) + +Specialty modules today are a **thin Pro enablement layer**, not the full clinical product shell described above. + +| Capability | Status | +| --- | --- | +| Module catalog + activate/deactivate | Exists (`config/care_specialty_modules.php`, `SpecialtyModuleService`) | +| Department + queue stub provisioning | Exists | +| Specialty Call next + waiting list | Exists (thin show page) | +| Workflow-driven episodes | Missing (use `Visit` as unit) | +| Unified patient timeline component | Partial (patient chart lists only) | +| Standard patient header / specialty shell | Missing | +| Specialty dashboard KPIs | Missing | +| Left nav Overview / Visits / History / Module Tabs | Missing | +| Clinical workspace | Missing (falls through to appointments/consultations) | +| Specialty service catalog → billing | Missing | +| Specialty-scoped reports / alerts / analytics | Missing | + +**Key files today** + +- `config/care_specialty_modules.php` +- `app/Services/Care/SpecialtyModuleService.php` +- `app/Http/Controllers/Care/SpecialtyModuleController.php` +- `resources/views/care/specialty/show.blade.php` + +### Foundational build order (before deep per-specialty work) + +1. **Specialty shell + nested routes** — shared layout with KPI strip and left nav; one family of controllers/views for all modules. +2. **Visit as the episode unit** — specialty Overview/Visits backed by `Visit` + workflow stages. +3. **Shared patient header + timeline component** — reuse on specialty History and patient chart. +4. **Specialty service catalog → billing/workflow charges** — seed charge codes on activate. +5. **Queue + clinical workspace entry points** — stage-aware queue → open consultation/assessment with specialty context. + +Do not implement dentistry, maternity, cardiology, etc. as separate apps until that shared shell and Visit/queue/billing bridges exist.