# 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 share a **specialty shell** on the Care Queue Engine. Per-module clinical forms deepen in Phase 3.

| Capability | Status |
| --- | --- |
| Module catalog + activate/deactivate | Exists (`config/care_specialty_modules.php`, `SpecialtyModuleService`) |
| Department + queue provisioning | Exists (native Care Queue Engine) |
| Shared specialty shell (Overview / Visits / History / Billing / Workspace) | Exists (`SpecialtyShellService`, `care/specialty/shell.blade.php`) |
| Stage maps + service catalogs | Exists (`config/care_specialty_shell.php` — Emergency, Blood Bank, Dentistry first-class; others inherit defaults) |
| Standard patient header + timeline | Exists (reused on specialty workspace + patient chart) |
| Visit-backed specialty visits | Exists (open visits + history lists) |
| Service catalog → Billing Engine | Exists (seed on activate; add line from workspace Billing tab) |
| Specialty KPIs | Exists (overview strip) |
| Deep clinical forms / order sets / documents | Phase 3 started — Emergency, Blood Bank, Dentistry structured records + docs upload; others inherit generic notes |
| Specialty clinical alerts | Exists (derived from triage / blood request / inventory payloads) |

**Program plan:** `docs/care-queue-engine-and-specialty-plan.md` (Phase 2 shell complete; Phase 3 rolls remaining modules onto clinical depth).

| 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.

---

## Care Queue Engine (product decision)

Ladill Care uses an **in-app Care Queue Engine**, fully decoupled from Ladill Queue.

- Specialty queues, call-next, and service points are Care-native.
- Ladill Queue remains a general-purpose QMS; healthcare / Care packaging is removed from Queue.
- Unified program plan: [`docs/care-queue-engine-and-specialty-plan.md`](care-queue-engine-and-specialty-plan.md).
