Handlers

:::info Status Outline — expand with a full worked example (e.g. a new local handler triggered off a document field change). :::

:::tip Use the shipped skills Prefer create-handler (in your scaffolded repo's .claude/skills/) for a mid-edit server round-trip (price lookup, discount recalc), or create-local-handler for a client-side-only recompute with no server call (a row total, a derived field). :::

A handler is an independent, keyed backend service — not tied to a specific document — used for cross-cutting operations like a price lookup triggered from a Waybill line. There are two flavors:

• Remote handlers (IHandler/IHandlerBehavior) — the general case, resolved by key, callable from anywhere that has the key.
• Local handlers (ILocalHandler) — declaratively bound with [HandlerTrigger(Type, Event, Target)], wired through every line-bearing document's shared Document plumbing.

Gotchas worth knowing before you start

• Don't wire a local handler's cascade inside a remote handler's own orchestrator — cascade at the Razor call site instead, or leave the binding purely declarative via [HandlerTrigger]. Baking the cascade into the remote handler couples two things that should stay independent.

See also

• Platform doc: docs/kandra-document-handlers-design.md (remote handlers, v0.4) and the local-handler design notes in the same area.