isaaccladandCursor
03befd1e7f
Deploy Ladill Care / deploy (push) Failing after 57s
Call-next and recall queue announcements for lobby screens without Ladill Queue. Co-authored-by: Cursor <cursoragent@cursor.com>
318 lines
14 KiB
Markdown
318 lines
14 KiB
Markdown
# Care Queue Engine + Specialty Modules — Unified Plan
|
||
|
||
**Status:** Phase 5 complete — remote Queue adapter removed; Care TV display + voice shipped
|
||
**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 Engine only (in-app tables + `CareQueueEngine`)
|
||
- 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
|
||
|
||
## Phase 4 notes (implementation)
|
||
|
||
- Ladill Queue: removed `industry_packages.healthcare`, `QUEUE_API_KEY_CARE`, Care settings/API/integration tests
|
||
- Queue marketing/settings copy now Frontdesk & POS only; `assigned_only` kept as generic routing
|
||
- DemoWorld: Care receptionist apps no longer include `queue`; dedicated Queue operators (`demo-*-queue@ladill.com`)
|
||
- Care upgrade banner no longer lists Ladill Queue as a Pro dependency
|
||
|
||
## Phase 5 notes (implementation)
|
||
|
||
- Deleted `QueueClient`, remote provisioner/bridge arms, Ladill Queue console views/presenter
|
||
- Removed `CARE_QUEUE_DRIVER` / `QUEUE_API_*` from Care config and `.env.example`
|
||
- Bridge / provisioner / specialty activate always use Care Queue Engine tables
|
||
- `care:queue-sync-tickets` remains (native backfill only)
|
||
- Tests assert local `CareQueueTicket` / `CareServiceQueue` (no Queue HTTP fakes)
|
||
- Care TV display + browser TTS voice on call-next/recall
|
||
|
||
---
|
||
|
||
## 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.
|