Event Types

Ironflow organizes events into four distinct namespaces based on their purpose and behavior.

Prefix	Name	Purpose	Triggers Workflows?
system.	System Events	Engine lifecycle (runs, steps).	No
events:	User Events	Business logic triggers.	Yes
topic:	Topic Events	Pure messaging/broadcasting.	No
entity:	Entity Events	Event-sourced changes.	Yes

---

1. System Events (system.)

Generated automatically by the Ironflow engine. Use these to monitor performance or build real-time execution dashboards.

• system.run.{id}.created
• system.run.{id}.step.{sid}.completed
• system.function.{id}.registered
• system.function.{id}.updated
• system.function.{id}.deleted
• system.secret.{name}.updated

Those are examples, not the whole set. Beyond run, function and secret, the engine also publishes system.circuit_breaker.{state}.{functionId}, system.config.{name}.{event}, system.cron.{functionId}.{event}, system.environment.{environmentId}.{event}, system.outbox.{eventId}.{event}, system.projection.{name}[.{partition}].updated, system.projection_health.{name}, system.stream.{entityId}.{event}, system.webhook.{sourceId}.delivery.{outcome} and system.worker.{workerId}.{event}.

Function frames are published only for IDs that build a valid NATS subject. A function registered before this rule existed whose ID carries whitespace or an empty . segment has its system.function.{id}.* and system.circuit_breaker.{state}.{id} frames dropped — counted by ironflow_system_event_drops_total and logged at warn. Re-create it under a valid ID to resume publishing.

---

2. User Events (events:)

Emitted by your application via emit(). These are the primary entry points for starting functions.

• events:order.placed
• events:user.signup

---

3. Topic Events (topic:)

Emitted by your application via publish(). These are used for service-to-service communication where a durable workflow run is not required.

• topic:notifications.email
• topic:analytics.page_view

---

4. Entity Events (entity:)

Generated when you append events to an Entity Stream. These trigger workflows just like User Events but provide an ordered historical log.

• entity:{type}.{id}.{event_name}
• Example: entity:order.ord_123.item_added

---

Pattern Matching

When subscribing to any of these types, you can use wildcards:

• * (Star): Matches exactly one segment.
  • system.run.*.failed matches any run failure.
• > (Greater-than): Matches all remaining segments.
  • events:> matches every user event in the system.
  • system.run.run_123.> matches every event for a specific run.

Domain-Driven Design

Ironflow’s event types map to DDD concepts: emit() produces domain events (internal, trigger workflows), while publish() produces integration events (cross-context, no workflow trigger). See Commands, Events & Reactions for the full mapping.