ladill-care/docs/care-queue-engine-and-specialty-plan.md

Care Queue Engine + Specialty Modules — Unified Plan

Status: Phase 3 in progress (clinical depth on shell)
Date: 2026-07-18
Repos: ladill-care (primary), ladill-queue (healthcare removal)
Related: docs/specialty-module-design-standard.md

---

Phase 1 notes (implementation)

• Config: CARE_QUEUE_DRIVER=native (default) | remote (legacy Ladill Queue HTTP)
• Tables: care_service_queues, care_service_points, care_queue_tickets
• Service: App\Services\Care\CareQueueEngine

Phase 2 notes (implementation)

• Shared shell: Overview / Visits / History / Billing / Workspace + action panel + stage map nav
• SpecialtyShellService + config/care_specialty_shell.php (Emergency, Blood Bank, Dentistry stage maps & catalogs; defaults for others)
• Patient header + timeline partials reused on specialty workspace and patient chart
• Activate seeds billable services; workspace Billing tab posts into Billing Engine

Phase 3 notes (implementation)

• care_specialty_clinical_records — Visit-scoped structured JSON + derived alerts
• Emergency triage/notes, Blood Bank request/inventory, Dentistry odontogram/notes on existing workspace tabs
• Documents tab uploads to patient attachments (specialty_{module})
• KPI strip includes open clinical records; no new queue backends
• Remaining modules inherit generic clinical_notes until rolled onto the same form pattern

---

1. Decision

Decision	Choice
Care waiting lines / call-next / service points	Built into Ladill Care as a first-party Care Queue Engine
Ladill Queue dependency for Care	Removed — Care never requires Queue API keys or Pro “Queue integration”
Healthcare in Ladill Queue	Removed — Queue becomes general-purpose multi-industry QMS only
Specialty modules	Built on top of Care Queue Engine + Visit/workflow/billing — not on Ladill Queue

Product framing

• Ladill Care = clinical ops (patients, visits, specialties, in-app queues, billing).
• Ladill Queue = generic ticket QMS (banks, retail, hospitality, …) with no clinical/Care packaging.

---

2. Goals & non-goals

Goals

1. One in-app Care queue substrate used by consultation, lab, pharmacy, billing, Emergency, Blood Bank, and all specialty modules.
2. Specialty modules follow the design standard (shell, workflow, queues, billing) without a second queue product.
3. Clean cutover: existing Care tenants keep working without Ladill Queue.
4. Queue product remains valuable for non-healthcare industries after healthcare surfaces are stripped.

Non-goals (this program)

• Rebuilding displays/kiosks/voice as feature-parity with Queue Day 1 (phase later if needed).
• Shared database between Care and Queue.
• Keeping a permanent dual-write to Ladill Queue.

---

3. Current state (why this plan)

Today Care is a remote adapter to Queue:

• QueueClient → CareQueueBridge / CareQueueProvisioner
• Clinical entities mirror queue_ticket_* fields; ticket truth lives in Queue
• Specialty activate provisions Queue stubs over HTTP
• Pro feature flag queue_integration + QUEUE_API_KEY_CARE

Specialty modules are a thin layer (catalog → departments → waiting list page). The specialty design standard needs a real local queue engine — building that and keeping Ladill Queue would double work.

---

4. Target architecture

┌─────────────────────────────────────────────────────────────┐
│                         Ladill Care                          │
│  Patients · Visits · Consultations · Lab · Pharmacy · Bills │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              Care Queue Engine (in-app)                 │ │
│  │  ServiceQueue · ServicePoint · Ticket · Call-next      │ │
│  │  Contexts: consultation, lab, pharmacy, billing,       │ │
│  │            specialty:{key}, emergency, blood_bank      │ │
│  └────────────────────────────────────────────────────────┘ │
│                              ▲                               │
│                              │                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │           Specialty Module Shell (shared)              │ │
│  │  Dashboard · Workflow · Clinical workspace · Billing   │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Ladill Queue (decoupled)
  Generic QMS only — no healthcare package, no Care API path

Care Queue Engine owns

• Queues per (organization, branch, context)
• Service points (rooms / desks / chairs) with shared_pool vs assigned_only
• Tickets (number, status, priority, wait time, assigned staff/point)
• Call next / recall / skip / complete / transfer (Care-flavored)
• Sync from clinical waiters (appointments, Rx, labs, bills) into tickets

Specialty modules own

• Clinical forms, stage maps, KPIs, documents, alerts
• Mapping specialty stages → Care Queue contexts/points
• Service catalog → Billing Engine line items

Visit remains the episode unit (per specialty standard). Tickets attach to visit/appointment/entity — not a parallel patient chart.

---

5. Phased program (one roadmap)

Phase 0 — Spec freeze (short)

Deliverables:

• This plan accepted
• Care Queue Engine domain model + API sketch (tables, statuses, contexts)
• Specialty shell IA locked (from design standard)
• Queue healthcare removal checklist signed off

Exit: engineering can implement without re-litigating product boundaries.

---

Phase 1 — Care Queue Engine (MVP)

Replace remote QMS for Care’s core lines inside Care.

Data model (illustrative)

• care_service_queues — org, branch, context, name, prefix, active
• care_service_points — queue_id, name, kind (practitioner/desk), staff/member/practitioner refs, routing mode
• care_queue_tickets — queue_id, point_id?, entity type/id, visit_id?, ticket_number, status, priority, called_at, completed_at, metadata
• Keep or migrate mirror columns on appointments/Rx/labs/bills to point at local ticket IDs (drop remote UUIDs over time)

Engine capabilities (MVP)

• Issue ticket when patient enters a wait line
• Call next (shared pool + assigned_only for doctors)
• Serve / complete / recall
• Backfill waiters without tickets
• UI: queue ops on consultation / lab / pharmacy / billing pages (same UX patterns as today, local backend)

Adapter rewrite

• CareQueueBridge talks to local engine (same method surface where possible)
• QueueClient / HTTP provisioner become dead code → delete
• Remove queue_integration Pro flag; Care queues are always available on Pro clinical modules (or Free waiting list + Pro ticket numbers — product call: recommend tickets on Free for consultation only, full multi-context on Pro)

Migration

• Tenants with remote Queue UUIDs: import open tickets if API still up or re-issue local tickets from current waiters (prefer re-issue for simplicity; archive remote history)
• Demo seed: stop calling Queue HTTP entirely

Exit: Care Pro demo runs call-next / tickets with QUEUE_API_* unset.

---

Phase 2 — Specialty shell on Care Queue Engine

Implement the specialty design standard once, for all modules.

1. Shared specialty shell — KPI dashboard, left nav (Overview / Visits / History / Module Tabs), standard patient header, action panel
2. Visit-backed specialty visits — not appointment-only waiting lists
3. Patient header + timeline components — reused on patient chart
4. Specialty stage maps in config (per module) → Care Queue contexts/points (e.g. Dentistry: Waiting → Chair → Procedure → Recovery)
5. Service catalog → billing — activate module seeds billable services; invoices via Billing Engine
6. Emergency & Blood Bank — already default_on_paid_plans; first modules to get full shell + local queues (templates for the rest)

Exit: Emergency (and ideally Dentistry) demonstrate the full standard on the in-app engine; remaining modules are catalog + stage map + forms on the same shell.

---

Phase 3 — Roll specialties onto the shell

Per-module work becomes incremental:

1. Stage map + queue points
2. Clinical forms / structured records
3. Service catalog items
4. Alerts + documents + KPIs
5. Role matrix

Order suggestion: Emergency → Blood Bank → Dentistry → Radiology → Maternity → … (volume / demo story first).

Do not invent new queue backends per specialty.

---

Phase 4 — Remove healthcare from Ladill Queue

Parallelizable after Phase 1 starts; finish once Care no longer calls Queue.

Remove from Queue

• industry_packages.healthcare and related templates/priorities
• Care integration: QUEUE_API_KEY_CARE, care_enabled, Care provision defaults, Care settings UI, Care tests
• Clinic DemoWorld branding (Ridge Clinic / Care staff) → neutral industry demos
• Care-oriented marketing copy (“Care & Frontdesk API” → generic integrations)

Keep in Queue

• Generic QMS, other industry packages, Frontdesk/POS/CRM integration pattern, assigned_only routing as generic features

Suite docs / DemoWorld

• Stop listing Queue as required for Care Pro
• Care staff demos no longer include queue app by default (optional)

Exit: Queue CI green without healthcare/Care paths; Care CI green without Queue env vars.

---

Phase 5 — Hard delete Care→Queue code & polish

• Delete QueueClient, remote provisioner paths, sync artisan that hits Queue API
• Remove env keys from Care .env.example
• Optional later: Care TV display / voice (only if product needs; not blocking)

---

6. How this maps to the specialty design standard

Standard requirement	Provided by
Workflow-driven stages	Specialty stage maps + Visit workflow
Queues per specialty	Care Queue Engine contexts/points
Episode / visit	Care Visit
Timeline	Shared timeline component (Phase 2)
Dashboard KPIs	Specialty shell (Phase 2)
Billing	Care Billing Engine + specialty service catalog
Call Next / Start Consultation / …	Shared actions → engine + clinical controllers
No standalone specialty apps	One shell, many module configs

---

7. Risks & mitigations

Risk	Mitigation
Ticket history only in Queue DB	Prefer re-issue open waiters locally; don’t block on full history import
Demo Pro broken mid-cutover	Feature flag care_native_queue during Phase 1; default on for new seeds
Specialty work forks before engine ready	Freeze deep specialty UIs until Phase 1 MVP + Phase 2 shell
Queue customers using healthcare package	Migrate them to Care or keep package until date-certain deprecation notice
Scope creep (kiosks/voice)	Explicitly Phase 5+ / optional

---

8. Success criteria

1. Care runs full clinical + specialty queues with no Ladill Queue dependency.
2. Specialty modules share one shell and one queue engine.
3. Ladill Queue has no healthcare package or Care integration surface.
4. Docs/demo accounts reflect the split.
5. Tests: Care queue + specialty shell coverage; Queue industry suite without healthcare.

---

9. Suggested ownership & sequencing

Week focus (indicative):

  [Phase 0] Spec freeze
      ↓
  [Phase 1] Care Queue Engine MVP  ──┬── parallel: Queue healthcare deprecation notice
      ↓                              │
  [Phase 2] Specialty shell          │
      ↓                              │
  [Phase 3] Emergency / Blood Bank / Dentistry on shell
      ↓                              ↓
  [Phase 4] Strip healthcare from Queue (hard remove)
      ↓
  [Phase 5] Delete Care remote Queue adapter

---

10. Immediate next implementation slice

When ready to code (first PR):

1. Migrations for care_service_queues, care_service_points, care_queue_tickets
2. CareNativeQueue service with issue / call-next / complete
3. Point CareQueueBridge at native service behind a config flag
4. Consultation queue page uses native tickets when flag on
5. Document flag + cutover in this file’s changelog

Specialty shell follows once native consultation queue is green in demo.