Getting Started

Event Processing & Actors


This guide covers two complementary patterns. Event-driven workflows react to things that happen — orders placed, payments received, sensors reporting — by executing durable task chains. Actors maintain per-entity state — shopping carts, counters, device twins — with single-writer guarantees. Both are backed by PostgreSQL: every event processed and every state change is journaled.

An event becomes a durable reaction

A plain event handler is fire-and-forget: if the process dies partway through reacting, the half-done work is gone and the event is often lost with it. When the reaction is a workflow, the event is durable — the chain resumes at the step it reached, and the event is acknowledged only once its handler is safely journaled.

Handler vs. Durable Reaction
Plain handler
Fire-and-forget

Crash mid-reaction loses the in-flight work — and often the event. At-least-once delivery means the retry re-runs everything, duplicates included.

Event → workflow
Journaled task chain

Crash resumes at the reached step; completed steps replay from the journal. Delivery is at-least-once; completed steps are never repeated.

No manual offset management, no lost events, no double-processing.

One writer per entity

The hardest part of stateful event processing is concurrency: two events for the same cart arriving at once can interleave and corrupt the state. Actors remove the problem by construction — all operations for one entity are serialized through a single writer, so each operation sees the previous one's committed result. No locks, no lost updates.

Concurrent Ops on cart:42, Serialized
1
add_item(A)arrives 10:00:00.000 → applied first · total = 1
2
add_item(B)arrives 10:00:00.001 → waits, then applied · total = 2
3
checkout()arrives 10:00:00.002 → sees total = 2, not a race
Different entities (cart:42, cart:99) still run fully in parallel — only same-entity ops serialize.

The two patterns compose: an actor operation can start a child workflow, and an event-driven workflow can invoke actor operations.


Patterns