Event-Driven Architecture

Event Emission

Use the Emit action to dispatch events to other feature sets. The target is simply the feature set name.

(* Creating a user and emitting events *)
(Create User: Registration) {
    Extract the <data> from the <request: body>.
    Create the <user: User> with <data>.
    Store the <user> in the <user-repository>.

    (* Emit to a specific feature set by name *)
    Emit to <Send Welcome Email> with {
        email: <user: email>,
        name: <user: name>
    }.

    Return a <Created: status> with <user>.
}

Receiving Events

Feature sets receive events in the <event> variable. Access fields using the familiar qualifier syntax.

(Send Welcome Email: Notifications) {
    Extract the <email> from the <event: email>.
    Extract the <name> from the <event: name>.

    Send the <welcome-email> to the <email> with {
        subject: "Welcome!",
        body: "Hello ${<name>}, welcome to our service!"
    }.

    Return an <OK: status> for the <notification>.
}

Multiple Event Handlers

A single action can emit to multiple feature sets, enabling clean separation of concerns. Each handler runs independently.

(createOrder: E-Commerce) {
    Extract the <userId> from the <request: body>.
    Extract the <items> from the <request: body>.

    Create the <order: Order> with {
        id: <generated-id>,
        userId: <userId>,
        items: <items>,
        status: "placed"
    }.

    Store the <order> in the <order-repository>.

    (* Dispatch events to multiple handlers *)
    Emit to <Send Order Confirmation> with <order>.
    Emit to <Update Inventory> with { items: <items> }.
    Emit to <Track Revenue> with { amount: <order: total> }.

    Return a <Created: status> with <order>.
}

Event Handlers

Each handler is a standard feature set that receives the event data:

(Send Order Confirmation: Notifications) {
    Extract the <orderId> from the <event: id>.
    Extract the <userEmail> from the <event: userEmail>.

    Send the <email> to the <userEmail> with {
        subject: "Order Confirmed",
        body: "Your order ${<orderId>} has been placed."
    }.

    Return an <OK: status> for the <confirmation>.
}

(Update Inventory: Inventory Management) {
    Extract the <items> from the <event: items>.

    for each <item> in <items> {
        Decrement the <stock> for the <item: productId>.
    }

    Return an <OK: status> for the <inventory>.
}

(Track Revenue: Analytics) {
    Extract the <amount> from the <event: amount>.
    Increment the <daily-revenue> by <amount>.
    Return an <OK: status> for the <analytics>.
}

Why This Approach?

Simplicity

No event bus configuration. No subscription management. No event type hierarchies. Just emit to a name, receive in <event>.

Clarity

The target feature set is explicit in the code. You can see exactly where events go without tracing through configuration files.

Decoupling

Event emitters don't need to know how handlers are implemented. Handlers can be added, removed, or modified independently.

Repository Observers

Repository observers are a special kind of event handler that automatically react to repository changes. When data is stored, updated, or deleted from a repository, observers receive the change details including both old and new values.

Observer Syntax

Create an observer by naming your feature set's business activity as {repository-name} Observer:

(* Audit all user changes *)
(Audit Changes: user-repository Observer) {
    Extract the <changeType> from the <event: changeType>.
    Extract the <newValue> from the <event: newValue>.
    Extract the <oldValue> from the <event: oldValue>.

    Log <changeType> to the <console>.
    Return an <OK: status> for the <audit>.
}

Event Payload

Observers receive an event with the following fields:

• repositoryName - The repository name (e.g., "user-repository")
• changeType - "created", "updated", or "deleted"
• entityId - ID of the changed entity (if available)
• newValue - The new value (nil for deletes)
• oldValue - The previous value (nil for creates)
• timestamp - When the change occurred

Deleting from Repositories

Use the Delete action with a where clause to remove items:

(deleteUser: User API) {
    Extract the <userId> from the <pathParameters: id>.
    Delete the <user> from the <user-repository> where id = <userId>.
    Return an <OK: status> with { deleted: <userId> }.
}