# Care Queue Engine + Specialty Modules — Unified Plan

**Status:** Phase 2 complete (shell); Phase 3 next  
**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
- Exit: Emergency (+ Dentistry) demonstrate the standard on the in-app queue engine

---

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