Workflow & Event Delivery · Sete Lagoas Transportes LTDA

Evaluation Cycle Orchestration

The performance-evaluation engine inside an internal HR platform. Activating a cycle locks its roster, transitions every dependent evaluation, and queues reviewer notifications in a single transaction — then a relay delivers them afterwards under retry, rather than sending anything inside the request that triggered it.

Production
Results
Transactional outbox relayDelivery
FOR UPDATE SKIP LOCKEDClaiming
Partial unique indexDeduplication
Five attempts, capped backoffRetries
Architecture
Dispatch Request connects to Authentication. Authentication connects to Dispatch Transaction via Role + policy check. Dispatch Transaction connects to Cycle → Active. Dispatch Transaction connects to Evaluations → Pending. Cycle → Active connects to Outbox Events via Same transaction. Evaluations → Pending connects to Outbox Events. Outbox Events connects to Outbox Relay via Claimed one at a time. Outbox Relay connects to Reviewer Notified. Outbox Relay connects to Retry or Fail via Up to five attempts.
Engineering Notes

Dispatch is one transaction. A row lock on the cycle refuses the transition unless it is still a draft, the cycle and every dependent evaluation move state together, and the reviewer notifications are written to an outbox in the same commit — so a crash mid-dispatch can leave neither a half-activated cycle nor a notification with no state change behind it.

Nothing is delivered inside the request. A relay polls the outbox and claims work in a single statement — a CTE selecting one due row FOR UPDATE SKIP LOCKED, marking it processing and incrementing its attempt count in the same round trip — so concurrent workers neither block each other nor process an event twice.

Deduplication is a database constraint rather than application logic. A partial unique index over tenant, event type, aggregate, and the reviewer id read out of the JSONB payload makes a duplicate dispatch notification impossible to insert, whatever the calling code does.

Failure is bounded and legible. An event retries up to five times with backoff capped at five minutes, carries its last error on the row, and settles into a terminal failed state instead of cycling forever — while its availability timestamp doubles as the delayed-visibility clock the relay orders by.

Every table in the pipeline is tenant-scoped by foreign key, and the claim query is served by an index on exactly the columns it filters and orders on.

Traces and metrics export over OTLP, with middleware attributing spans to the acting user, tenant, and role — and normalising them to the matched route pattern rather than the raw path, so span names stay low-cardinality.

Core Technologies
TypeScriptNode.jsExpressPostgreSQLOpenTelemetrybetter-authReactDocker
All work