Pathology Workflow Engine

Central, editable state-flow engine for the pathology module — mirrors how encounter-orchestrator + medical-worklist already drive workflow state transitions for OPD/IPD/billing/pharmacy.

What’s In This Folder

File	Purpose
architecture.md	End-to-end architecture: where pathology state lives, how transitions propagate, where the editor plugs in
state-machine.md	Canonical pathology specimen state machine (Pending → Received → Grossing → Slide Prep → Slide Scan → Sign-out → Released) plus cancel/reject branches
node-catalog.md	The 8 pathology-specific workflow nodes, their schemas, and which canonical state each represents
side-panels.md	The 4 pathology-specific config panels (Specimen, Priority, Turnaround, Sign-out Rules) and how they extend the shared NodeConfigDrawer
workflow-editor-reuse.md	What we reuse from worklist-editor (5 hooks, 4 components) and what is pathology-specific (nodes, panels, footer, defaults)
integration-guide.md	How to wire the editor into the admin nav, hook the runtime via usePolicyGate, the GlobalModalRenderer, and aftersave callbacks
scanner-flow.md	Barcode/QR scanner + printable label flow — PathologySpecimenScanner, PathologySpecimenLabel, scan + print_label cockpit action types
demo-script.md	Real-time demo runbook — change a flow rule mid-stage and show the transition button update live

Code Location

The editor implementation lives at:

web/src/common/components/medical/builder/pathology-workflow-editor/
├── index.tsx                         ← Main page (reuses worklist-editor hooks)
├── types/index.ts                    ← PathologyNodeType enum + state types
├── defaults/pathology-default-workflow.ts  ← Seed nodes + edges
├── nodes/                            ← 6 pathology node renderers
├── panels/                           ← 4 pathology side panels
└── components/
    ├── PathologyNodeCanvas.tsx       ← Visual canvas of pathology states
    └── PathologyStateFooter.tsx      ← Sticky footer with central transition button

Existing default workflow JSON (referenced by the editor):

web/packages/medical-kit/src/medical-worklist/defaults/
├── pathology-collect-specimens-workflow.json  (collection-side)
└── pathology-laboratory-workflow.json          (laboratory-side, 2.1.0)

Reuse Contract

This folder does not fork worklist-editor. We import and reuse:

• useDepartmentSelection — clinic/sub-clinic selection (1 line import)
• useWorkflowManagement — load/save workflow_templates rows (1 line import)
• useRoleWorklistConfig — per-role node visibility + queue mode (1 line import)
• useWorkflowGraph — parent-child edge graph (1 line import)
• useQuickSetup — preset generator (1 line import)
• `` — top-bar dept picker
• `` — right-side drawer shell (we inject pathology panels into its extraTabs slot)

Pathology-specific additions:

• 6 node renderers (PathologyRegisterNode, PathologyGrossingNode, PathologySlidePrepNode, PathologySlideScanNode, PathologySignoutNode, PathologyReleaseNode)
• 4 side panels (Specimen Config, Priority Rules, Turnaround Targets, Sign-out Rules)
• 1 sticky footer (PathologyStateFooter) — the “central transition button” the user asked about
• 1 default workflow (pathology-default-workflow.ts) — references the existing JSON template

How the “Central State” Demo Works

1. Admin opens /admin/pathology-workflow (this editor)
2. Drags pathology nodes around, edits a rule in a side panel, hits Save
3. The save writes to workflow_templates (graph) + policy_gates (rule)
4. Both tables are subscribed to via Supabase realtime in the running app
5. Open clinical UI in a second tab — the transition button in PathologyStateFooter flips state (enabled/disabled/blocked) within ~300ms without a page refresh

This is the same pattern documented in docs/architecture/policy-gates.md and docs/architecture/encounter-orchestrator-triggers.md — pathology becomes a first-class citizen alongside consultation/billing/pharmacy.

Status

• [x] Master docs folder
• [x] Pathology workflow editor scaffold (reuses worklist-editor hooks)
• [x] 6 pathology node renderers
• [x] 4 pathology side panels
• [x] Sticky footer with central transition button
• [x] Default workflow seed
• [x] Editor wired to workflow_templates (load + save via useWorkflowManagement)
• [x] “Generate Gate” buttons write to policy_gates table
• [x] Footer container wired to policy_gates realtime + usePathologySpecimenState
• [x] Footer dispatches openModal() for modal actions and updateActiveOrderStatus() for transitions
• [x] Barcode/QR scanner (USB + camera + manual) with active-specimen zustand store
• [x] Printable QR + 1D barcode label generator
• [x] scan + print_label cockpit action types
• [x] Footer mounted in containers/pathology/laboratory/page.tsx
• [ ] Admin route wired in src/routes.tsx — see integration-guide.md
• [ ] usePolicyGate({ trigger: 'pathology_*' }) seed rules in production DB — see integration-guide.md
• [ ] encounter-orchestrator handlePathologyStateChange handler (deep mock) — see integration-guide.md

Do Not

1. Do not modify worklist-editor source — extend through composition only
2. Do not write directly to encounter_journey_cache or department_queues from this editor — write to workflow_templates and let the orchestrator project
3. Do not fork the hooks — if a hook needs a pathology-specific tweak, propose a prop addition upstream
4. Do not delete the existing pathology JSON defaults — the editor reads them