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