ladill-care/docs/specialty-module-design-standard.md

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.