ADR-004: CL-FW Event Patterns for Clinical Workflow Automation

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Context

• cl_pm_events channel is active and handles cross-core CL/PM events (lab orders, note signing, prescriptions)
• cl_events channel is reserved but unused — intended for CL-internal and CL-to-other-core events
• FW-16 (Event-Based Workflow Triggers) provides fw_process_domain_event() for consuming events and creating automated tasks/notifications
• CL-13 (Crisis), CL-10 (Outcomes), CL-21 (MOUD), and CL-35 (Population Health) all need to publish events that FW consumes

​

Decision

​

1. Channel Routing Strategy

• PM is primary when the event directly triggers PM operations that create or modify PM billing, scheduling, or eligibility records — e.g. charge capture (pm_charge_suggestions / pm_charges), appointment create/update tied to the event, or eligibility checks that persist PM state.
• PM is secondary when the event only informs PM-side workflows (notifications, dashboards, manual follow-up) without creating or updating those PM records.

​

2. Event Naming Convention

cl_{entity}_{action}

​

3. Payload Schema Convention

interface CLDomainEvent {
  event: string;                    // e.g. 'cl_crisis_episode_opened'
  publisher: 'CL';
  subscriber: string[];             // e.g. ['FW', 'GR', 'PF']
  payload: {
    entity_id: string;              // UUID of the entity (episode, assessment, etc.)
    entity_type: string;            // e.g. 'crisis_episode', 'restraint_event'
    chart_id: string;               // Patient chart UUID
    severity?: 'info' | 'warning' | 'critical';  // For FW priority routing
    action_required?: string;       // Human-readable action hint for FW task creation
    billing_codes?: string[];       // Only for events with billing impact
    [key: string]: unknown;         // Additional event-specific fields
  };
  metadata: {
    organization_id: string;        // REQUIRED: tenant isolation
    site_id?: string;
    user_id: string;                // Actor who triggered the event
    timestamp: string;              // ISO 8601
    correlation_id: string;         // UUID for idempotency + tracing
    event_id: string;               // Unique event UUID
  };
}

​

4. Idempotency Pattern

• Every event includes a unique event_id (UUID v4) in metadata
• fw_process_domain_event() checks for duplicate event_id in fw_domain_events before processing
• Duplicate events are logged but not re-processed
• correlation_id groups related events (e.g., all events from a single crisis episode share a correlation_id)

​

5. Dead-Letter Queue Pattern

• Failed event processing (consumer throws after max retries) writes to fw_domain_events with status = 'failed'
• Failed events include error message and retry count
• Edge function cron (cl-event-dlq-processor, runs every 15 minutes) retries failed events up to 3 additional times
• After final failure: creates PF-10 notification to system admin with event details
• Retry strategy: exponential backoff (1s, 2s, 4s) on 5xx errors; no retry on 4xx except 429 (rate limit)

​

6. FW Subscription Registration

• Insert or upsert rows in fw_workflow_events only after the corresponding CL event names are implemented (publishers exist) and each referenced auto_task_template exists in FW (e.g. pf_task_templates or equivalent). Otherwise migrations fail or produce orphaned registrations that never resolve at runtime.
• Prefer idempotent seeds: use ON CONFLICT (event_name) DO NOTHING or ON CONFLICT ... DO UPDATE so re-running migrations or seed scripts does not fail on duplicate keys.

INSERT INTO fw_workflow_events (event_name, source_core, channel, description, auto_task_template)
VALUES
  ('cl_crisis_episode_opened', 'CL', 'cl_events', 'Crisis episode opened — notify supervisor', 'crisis_supervisor_notification'),
  ('cl_assessment_expired', 'CL', 'cl_events', 'Assessment overdue — create reassessment task', 'reassessment_reminder'),
  ('cl_moud_monitoring_overdue', 'CL', 'cl_events', 'MOUD monitoring overdue — alert care team', 'moud_care_team_alert'),
  ('cl_moud_adherence_risk', 'CL', 'cl_events', 'MOUD adherence risk — escalate to supervisor', 'moud_escalation'),
  ('cl_care_gap_identified', 'CL', 'cl_events', 'Care gap identified — create task for care manager', 'care_gap_task'),
  ('cl_restraint_event_initiated', 'CL', 'cl_events', 'Restraint initiated — notify GR + create incident', 'restraint_incident_creation')
ON CONFLICT (event_name) DO UPDATE SET
  description = EXCLUDED.description,
  auto_task_template = EXCLUDED.auto_task_template,
  channel = EXCLUDED.channel,
  source_core = EXCLUDED.source_core;

​

Rationale

​

Options Considered

• Pro: Simple routing, one consumer per channel
• Con: PM charge capture events mixed with FW automation events; PM team must filter irrelevant events; higher latency for time-sensitive billing events
• Rejected: Violates separation of concerns; PM consumers shouldn’t process crisis/MOUD events

• Pro: PM consumers only see billing-relevant events; FW consumes both channels but primarily cl_events; clear ownership
• Con: Publisher must decide which channel; slight complexity
• Chosen: Best balance of performance and clarity. Aligns with existing cl_pm_events usage.

• Pro: Simplest; one channel for everything
• Con: Extremely noisy; all cores’ events in one channel; consumer filtering overhead; violates EVENT_CONTRACTS.md channel ownership model
• Rejected: Doesn’t scale; contradicts established channel-per-core pattern

​

Why not a new cl_fw_events channel?

​

Consequences

​

Positive

• Consistent event naming and payload schema across all CL specs
• FW automation rules can be authored against a known, stable contract
• Idempotency and DLQ prevent lost events and duplicate processing
• PHI-safe payloads by design (UUIDs only)
• Clear channel routing reduces consumer-side filtering

​

Negative

• Publishers must make a routing decision (cl_pm_events vs cl_events) — adds minor cognitive overhead
• FW must subscribe to two CL channels (already subscribes to multiple channels for other cores)
• Seed data in fw_workflow_events must stay in sync with actual published events

​

Mitigations

• Document routing decision tree in this ADR (section 1 above)
• CI drift check: validate that all pg_notify('cl_events', ...) calls match registered events in fw_workflow_events
• EVENT_CONTRACTS.md updated whenever a new CL event is added (PR template checklist item)

​

Related Documents

• EVENT_CONTRACTS.md — Canonical event schema and channel registry
• FW-16 Event-Based Workflow Triggers — FW automation infrastructure
• CL-13 Crisis Intervention — Primary driver for crisis events
• CL-21 MOUD Tracking — MOUD monitoring events
• CL-35 Population Health — Care gap events
• ADR-002 CL-PM Cross-Core Foreign Keys — Related CL-PM integration decision
• constitution.md §1.3 — Integration pattern exceptions require ADR