Hooks & Workflows: per-app requirements & how to add them

Audience: DRO platform admins and integrators who configure entity behaviour through the admin console. Scope: how lifecycle hooks, declarative EventRules, and stateful DroWorkflows fit together, how to attach each to an entity, and a per-app starter set you can copy from today.

1. The 4-layer automation model

Every entity in DRO can carry automation at four distinct layers. They differ in where they run, what they can do, and whether they can block a write. Picking the right layer is the single most important decision — putting routing logic in a hook or putting a field default in a workflow both create pain later.

How they chain

A typical end-to-end flow uses all four:

admin/API write
   └─► [1] beforeCreate hook  → normalize + validate (can ABORT)
   └─► row persisted
   └─► [1] afterCreate hook   → emit entity:created on EventBus (fire-and-forget)
            └─► [2] EventRule  → "if amount > threshold, start approval"
                   └─► [3] DroWorkflow → human-task checkpoint, timers, rollback
                          └─► uses [4] FSM spec to walk legal states

The decision rule of thumb

• Field default, normalization, validation, referential guard, "must never persist" → Layer 1 hook (BEFORE).
• Cheap cross-entity reaction, notification, projection, single declarative "when→then" → Layer 2 EventRule.
• Multi-step, spans time/days, needs human approval, retries, or rollback → Layer 3 DroWorkflow.
• A status field that must only move along legal edges → define a Layer 4 FSM spec, then enforce it from a hook.

2. Attaching a lifecycle hook to an entity

Hooks are bound through the entity's template_overrides.controller.hooks array. Each element names the lifecycle moments it fires on and the registered handler to call.

2.1 The binding shape

{
  "template_overrides": {
    "controller": {
      "hooks": [
        { "events": ["create", "update"], "handler": "set_timestamps" },
        { "events": ["create"],          "handler": "normalize_e164_did" },
        { "events": ["update"],          "handler": "guard_did_status_transition" },
        { "events": ["delete"],          "handler": "emit_did_lifecycle_event" }
      ]
    }
  }
}

• events are the lifecycle points: create, update, delete. The engine resolves these to beforeCreate/afterCreate etc. based on the handler's declared phase.
• handler is the registered name — a string key in DroCore.HookEngine.Registry, never a raw MFA in this array.
• Handlers run in array order within a phase. Put normalization before validation before event emission.

2.2 BEFORE vs AFTER semantics

Hard rule: anything that must never reach the database (plaintext secrets, unbalanced ledgers, illegal status jumps, over-allocations) goes in a BEFORE hook. AFTER hooks are observability and side-effects only.

2.3 The four steps to add a new hook

A handler must exist in all of these places or it is unreachable from one code path:

1. Write the handler in the app's *_hooks.ex registry module (mirror the closest existing one — e.g. cloudpbx_telecom_hooks.ex, finance_hooks.ex, hr_hooks.ex).
2. Register it by name: DroCore.HookEngine.Registry.register("normalize_e164_did", &MyHooks.normalize_e164_did/2) (typically from application.ex or the registry module's register_all/0).
3. Bind it on the entity by adding the entry to template_overrides.controller.hooks (via the admin entity-definition CRUD surface — not a seed file; the DB is the source of truth).
4. Verify the binding takes effect: edit the entity through the admin UI and confirm the handler fires (a Logger probe is reliable since Ecto query logging is off in dev).

2.4 Reuse the builtins before writing new ones

The HookEngine ships builtin handler families you can bind directly without code: set_timestamps, set_updated_at, normalize_email, trim_strings, generate_slug, soft_delete, publish_entity_event, audit_log, plus the guard families validation_hooks, state_transition_hook, unique_constraint_hook, geo_validation_hooks, revenue_hooks. Prefer composing these over hand-rolling a one-off.

3. EventRule vs DroWorkflow — when to use which

Both react to entity events. The dividing line is state and time.

Use an EventRule when the reaction is…

• Single-step and stateless — one condition, one action, done.
• Cross-entity but immediate — "on deals:updated to won, mark the linked quote accepted and notify finance."
• Tenant-tunable policy — thresholds, cadences, routing targets that admins change at /admin without a deploy (fraud thresholds, low-stock levels, auto-approve limits, dunning buckets).
• A projection or cache-bust — "on cc_agent_skills:updated, publish acd.skills_changed to bust the router cache."

EventRules are the right home for anything you'd otherwise hardcode in a controller. They are declarative, editable, and per-tenant.

Use a DroWorkflow when the process…

• Spans multiple steps that hold state between them (an order walking pending→paid→shipped→delivered).
• Spans time — days or weeks (number porting, AR dunning ladder, retention aging, fixed-deposit maturity).
• Has human-task checkpoints — approvals, reviews, sign-offs, dispute resolution.
• Needs retries, timers, dead-lettering, or rollback — provisioning with backoff, compensating teardown on a failed step.
• Has branches and terminal states — won/lost, approved/denied, completed/declined/voided/expired.

The litmus test

If you can express it as "WHEN this single event AND this condition, THEN do this one thing" → EventRule. If you need the words "then wait," "then a human approves," "retry," or "if step 3 fails, undo step 2" → DroWorkflow.

They compose

The common pattern is an EventRule that triggers a DroWorkflow:

invoice.overdue (event)
  └─► [EventRule] "amount_due > 0 AND past due"
         └─► starts [DroWorkflow] ar_dunning_collections
                day7 reminder → wait → day14 firm → wait → day30 final
                → human_task owner_review → {escalate | write_off | paid}

The EventRule is the cheap, tunable trigger; the workflow carries the multi-week state. Don't model a dunning ladder as five EventRules — you'll have no shared state and no terminal.

4. Per-app quick reference — recommended starter hooks & workflows

The table below is the P0/P1 starter set distilled from a per-app audit. "P0" = ship-first integrity/security/financial guards; "P1" = the stateful processes that build on them. Bind the hooks first (they protect the write boundary), then add the EventRules and Workflows.

Cross-cutting notes

• PII entities (subscribers, contacts, customers, mailboxes, employees, llm_interactions) need a normalize/mask hook and a soft-delete/erasure path — hard-deleting PII with order/audit FKs is a compliance gap (27701:7.4). Use soft-delete + anonymize, never physical delete.
• Money entities (invoices, payments, journal entries, transactions, settlements, orders) need server-side total computation + a posted-immutability guard. Never trust client-sent totals; corrections happen via reversing/credit documents, not edits.
• Dual-bridged modules (e.g. messaging conversations bridged into chat; oss entities bridged into mvno) require tenant-scoped hooks, not app-scoped — an app-wide hook leaks behaviour across the bridge.
• Bind hooks to the canonical entity_definition, not duplicate module bridges or dashboard proj_*/legacy copies — otherwise handlers fire inconsistently depending on the write path.
• The recurring anti-pattern across nearly every app: rich domain logic exists (CompromiseDetector, AutoProvisioner, agent_state GenServer, Retention, ComplianceWebhook) but is invoked imperatively from REST/Oban paths and not bound to the entity lifecycle — so admin-CRUD and API writes bypass all of it. The fix is almost always to wire existing modules in as named HookEngine handlers, not to write new logic.