Argyll logo Argyll

Event Sourcing

All state in Argyll lives in append-only event logs organized by aggregate. Every state change is an event, and projections are derived deterministically. Includes the full event-type catalog.

Foundation

Every state change in Argyll is recorded as an event in an append-only log. State is derived by replaying events, never stored separately. This gives determinism, durability, and a complete audit trail.

Aggregates

Events are organized into aggregates, each identified by an ID path:

Aggregate IDContents
["catalog"]Registered step definitions
["cluster"]Per-step health across the cluster
["flow", "flow-id"]One flow’s execution history

Event Types

Catalog (["catalog"])

  • step_registered
  • step_unregistered
  • step_updated

Cluster (["cluster"])

  • step_health_changed

Flow Lifecycle (["flow", "flow-id"])

  • flow_started
  • flow_completed
  • flow_failed
  • flow_deactivated

Step Execution (["flow", "flow-id"])

  • step_started
  • step_completed
  • step_failed
  • step_skipped

Work Items (["flow", "flow-id"])

  • work_started
  • work_succeeded
  • work_failed
  • work_not_completed
  • retry_scheduled
  • dispatch_deferred — raised when a node cannot dispatch work, retry, or compensation locally; propagates to all nodes so one with a healthy path to the step can pick it up

Compensation (["flow", "flow-id"])

  • comp_started
  • comp_succeeded
  • comp_failed
  • comp_retry_scheduled

Attributes (["flow", "flow-id"])

  • attribute_set

Side Effects Follow Committed State

The engine writes the event before it triggers any external action. If a node crashes mid-write, the event either committed (and the work runs after recovery) or it didn’t (and nothing ran). Retries resume from the last committed state, with no double execution from missing acks.

State Reconstruction

A flow’s current state is the fold of all its events. You can:

  • Replay any flow’s event log to inspect its history
  • Subscribe to live events via WebSocket to track execution in real time
  • Verify why a flow reached its current state by reading the event sequence

Subscribing

The WebSocket API streams events live. Subscribers can filter by aggregate ID and event type, and request the current projected state up front. See the WebSocket API for the protocol.

Previous Architecture