Document the specialty module design standard for Care.

Capture the unified workflow, UI, queue, and billing blueprint, and add a Cursor rule so specialty work follows the shared shell instead of one-off apps.

Co-authored-by: Cursor <cursoragent@cursor.com>

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.