Entity Stream Flow

Entity Stream Flow (Event Sourcing)

Entity streams store domain events per entity with optimistic concurrency. Data lives exclusively in the DB. NATS carries optional notifications for real-time subscribers and projections.

SDK / HTTP Client
     │
     │  POST /api/v1/streams/{entityId}/events
     ▼
┌──────────────────────────────────────────┐
│  DB: events table                        │
│  entity_id      = "order:123"            │  ← user stream
│  entity_type    = "order"                │    or
│  entity_version = N+1  (CAS check)       │  "ironflow:fn:{id}"
│  data           = JSON payload           │    for fn history
└──────────┬───────────────────────────────┘
           │
           │  (optionally) notify subscribers
           ▼
┌─────────────────┐
│  NATS PUBSUB    │  notification only
│  stream         │  topic: entity:{entityType}.{entityId}.{event}
│                 │  NATS:  public.{project}.{env}.entity.{type}.{id}.{event}
└─────────────────┘

Entity data lives ONLY in the DB. NATS carries the notification.

Optimistic concurrency is enforced by a unique constraint on (environment_id, entity_id, entity_version). A version conflict returns ErrVersionConflict.

Entity events also trigger workflow function matching — if a function’s trigger matches the event name, runs are created and dispatched just like emit().