Automation Rules: Trigger → Condition → Action (TCA) Engine + In-App Notifications

Summary Add a lightweight rules engine that lets users automate routine workflows (e.g., “When a task is moved to Done and priority is High, notify the Project Managers on Slack and assign a retrospective checklist”). Ships with in-app notifications, optional email/webhook actions, and RBAC-aware rule scoping.

---

Goals

• Let workspace/project admins define automation rules using TCA:

  • Triggers: task.created, task.updated, task.assigned, project.member_joined, schedule.cron
  • Conditions (optional): field filters (status/priority/assignee/labels), expression builder
  • Actions: create/update task, add comment, set labels/dates, in-app notification, email, Slack/Webhook, reassign, change status

• Provide UI to list, create, enable/disable, test, and reorder rules per project.

• Respect RBAC (only admins/PMs manage rules; members can view rules that affect them).

• Guarantee idempotency per event (avoid duplicate actions).

• Log audit entries for each rule execution (success/failure, latency).

---

Non-Goals

• Full BPMN or multi-step long-running workflows.
• Third-party OAuth setups beyond generic webhooks & (optional) one Slack Incoming Webhook URL per project.

---

UX / UI

• Project Settings → Automations tab:

  • Rules table (name, trigger, actions, status, last run, failures)

  • “New Rule” drawer with:

    1. Trigger select (+ optional cron)
    2. Conditions builder (simple AND of field ops; JSON preview)
    3. Actions list (multi-select with action configs)
    4. “Test with sample event” & “Create disabled” checkbox

• Notifications bell in navbar with unread count, list, pagination, “mark all read”.

---

Data Model (MongoDB)

// collections
rules {
  _id, projectId, createdBy, name, trigger: "task.updated" | ...,
  conditions: { status?: ["Todo","Doing","Done"], priority?: ["High"...], assigneeId?: string, labels?: string[], expr?: string }, // optional
  actions: [{ type: "notify"|"email"|"webhook"|"update_task"|"add_comment"|"reassign"|"set_status", config: {...} }],
  enabled: boolean,
  order: number,
  createdAt, updatedAt
}

rule_runs {
  _id, ruleId, projectId, eventId, status: "success"|"failed"|"skipped",
  reason?: string, durationMs, createdAt
}

notifications {
  _id, userId, projectId, type: "task"|"system",
  title, body, href, read: boolean, createdAt
}

webhook_endpoints { _id, projectId, url, secretHash, enabled, createdAt }

Idempotency: store a short-ttl key rule:{ruleId}:event:{eventId} (Redis/Upstash) or a unique index on (ruleId, eventId) in rule_runs.

---

API (Next.js Route Handlers)

• POST /api/automation/rules (admin only) — create rule
• GET /api/automation/rules?projectId= — list rules
• PATCH /api/automation/rules/:id — enable/disable/update
• POST /api/automation/test — dry-run with sample payload
• GET /api/automation/runs?ruleId= — recent executions
• GET /api/notifications — list for current user
• PATCH /api/notifications/read — mark read / mark all
• POST /api/webhooks/:endpointId — receive generic webhook (verifies secret)

Event Bus Create a tiny internal dispatcher:

emitEvent("task.updated", { eventId, projectId, before, after, actorId })

Handlers fetch eligible rules (by trigger & project), filter by conditions, enforce idempotency, then execute actions.

---

Auth0 / RBAC

• Only Admin/Project Manager can create/update rules.
• All users can receive notifications; only affected project members see rule-generated changes.
• Verify scopes/roles on all automation endpoints.

---

Actions (v1)

• notify (in-app): create notifications doc per target (assignee, role, custom list)
• email (optional; use existing mailer or stub)
• webhook: POST JSON payload to configured URL with HMAC signature (secret)
• update_task: set fields (status, labels, dueDate, priority)
• add_comment: append comment to task
• reassign: change assignee
• set_status: quick status switch

---

Scheduling

• Cron trigger via Next.js cron job (Vercel Cron or self-hosted scheduler). Store last run cursor per rule to avoid re-runs.

---

Telemetry & Safety

• Log run duration & outcome to rule_runs.
• Circuit-break action type if error rate > X% in Y min.
• Per-rule execution timeout (e.g., 5s) and global concurrency cap.

---

Acceptance Criteria

• Create/list/update/disable rules via UI & API with RBAC enforcement.
• Events from task create/update reliably fire matching rules; conditions evaluated correctly.
• Idempotent execution: the same eventId never triggers duplicate actions for a rule.
• In-app notifications render with unread badge, pagination, and “mark all read”.
• Audit trail visible per rule (runs list with status and timestamps).
• Documentation added to README (Automations section) with examples.
• ≥ 90% unit coverage for evaluator + dispatcher; integration tests for common flows.

---

Rollout Plan

1. Phase 1: in-app notifications + task.updated trigger, notify|set_status|add_comment actions.
2. Phase 2: webhook & email actions, cron trigger.
3. Phase 3: rule exports/imports, templates (e.g., “Auto-assign high-priority bugs to PM”).