Automation And Rules Engine Guide

Purpose

Task 63 adds a template-first automation system that lets Tov+ react to domain events and scheduled offsets without turning the product into an unrestricted scripting platform.

The baseline rule shape is:

• when a supported trigger occurs
• and structured conditions match
• queue a supported action

The engine currently focuses on Communications-owned actions, because delivery stays inside the Communications domain and continues to use the worker plus provider abstraction.

Supported baseline templates

• rsvp_pending_reminder
  • scheduled before event start
  • targets invitation primary actors with pending RSVP state
• guest_follow_up_form
  • triggered by rsvp.submitted
  • targets the responding actor after an attending RSVP
• vendor_timeline_change_notice
  • triggered by timeline.updated
  • targets vendor actors assigned to the affected event
• guest_seating_published_notice
  • triggered by seating_plan.published
  • targets attending guest actors for the event

Scope model

• rules are stored at the occasion level
• rules may be occasion scoped or event scoped
• event-scoped rules must reference an event in the same occasion
• planners manage rules with existing communications:view and communications:manage permissions

Runtime model

• domain systems emit webhook/domain events through the existing event emission seam
• automation trigger events are persisted and converted into worker jobs
• the worker evaluates matching rules asynchronously
• scheduled scans run through the maintenance scheduler path
• executions are deduplicated by deterministic dedupe_key values

Supported conditions

• rsvp_status_is
• invitation_has_pending_response
• module_enabled
• capability_enabled
• event_type_in

These are intentionally structured and finite. The system does not execute planner-authored code.

Supported actions

• send_communication

This action resolves recipients from occasion data, builds template data, and calls queueSystemOccasionCommunication(...). Automation does not bypass Communications, notification preferences, locale selection, or delivery logging.

Planner surface

The dashboard now exposes:

• GET /v1/occasions/:occasion_id/automations
• POST /v1/occasions/:occasion_id/automations/rules
• PATCH /v1/occasions/:occasion_id/automations/rules/:rule_id

The planner UI supports:

• viewing available templates
• activating rules from templates
• enabling, disabling, and archiving rules
• inspecting recent execution outcomes

Persistence model

The in-app runtime remains in-memory for the current server foundation, but Task 63 also adds the durable SQL model:

• automation_rules
• automation_trigger_events
• automation_executions

That keeps the production storage shape explicit for later DB-backed repository replacement.