Queue & Waiting Board — How it works

Overview

The queue engine provides operational queues and the waiting boards that surface them: create a queue, add items (a logical subject — patient, referral — referenced by type+id), move/prioritise them, change their status, assign/release them, and expose a paginated, filterable board feed. All statuses are relational (never JSONB-only), and every status change is recorded append-only.

Data model & ownership

Table	Purpose
queue	A queue; relational status (OPEN/PAUSED/CLOSED), code unique per tenant/facility scope.
queue_item	An entry; relational status (WAITING/IN_SERVICE/COMPLETED/DEFERRED/REMOVED), relational priority/sort; logical subject_type/subject_id.
queue_assignment	Who is serving an item; relational active.
waiting_board	A board over a queue; code unique per scope.
queue_status_history	Append-only history of every item status change.

Key rules & invariants

• Items may be added only to OPEN queues and enter WAITING; transfers are restricted to the same tenant/facility scope; terminal items reject changes; removal soft-deletes and releases active assignments.
• queue_status_history is append-only — written on entry (null → WAITING) and every subsequent transition/removal, preserved across item removal.
• The board feed is status-filterable and paginated via a stable PagedModel DTO.

API

See the API Reference. Endpoint groups under /api/v1/queue: queues (create/get/search/status), queue items (/{id} move/reorder, status change, remove, assign/release, history), and waiting boards (create/get/search + /feed).

Configuration & feature flags

Domain-module Feign URL queue.service.url (QUEUE_SERVICE_URL).

Related features

• Workflow (operational pairing), Facility (scope). Domain plug-ins call via exchange.client.queue.