> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Topics

> Explore advanced techniques for leveraging event-driven architecture in Builder applications

As you become more proficient with Builder, understanding and leveraging its event-driven architecture can help you build more sophisticated, powerful, and efficient applications. This guide explores advanced topics focused on event-driven patterns and their practical applications.

## Event-Driven Architecture (EDA)

<Tabs>
  <Tab title="Core Concepts">
    Event-driven architecture is the foundation of Builder's flexibility:

    * **Events as First-Class Citizens**: All system and user actions generate events
    * **Decoupled Components**: Services communicate through events, not direct calls
    * **Asynchronous Processing**: Actions occur independently of event producers
    * **Scalability**: Components can scale independently based on event load
    * **Extensibility**: New capabilities can subscribe to existing event streams

    In Prisme.ai, events flow through the system as messages containing:

    * An event **type** (e.g., `message.created`, `user.login`)
    * A **payload** with event-specific data
    * **Metadata** about the source, timestamp, and routing information
  </Tab>

  <Tab title="Key Benefits">
    Event-driven architecture provides several advantages:

    * **Loose Coupling**: Components can evolve independently
    * **Real-Time Processing**: Events are processed as they occur
    * **Resilience**: Failures in one component don't cascade to others
    * **Auditability**: Complete event history provides audit trail
    * **Flexibility**: Easy to add new event consumers without modifying producers

    For AI applications, EDA enables:

    * Seamless integration of multiple AI models and tools
    * Progressive enhancement of features without disruption
    * Detailed tracking of user interactions for personalization
    * Complex workflows that adapt based on AI processing results
  </Tab>

  <Tab title="Implementation in Prisme.ai">
    Prisme.ai implements EDA through several mechanisms:

    * **System Events**: Generated by the platform for actions like page loads or authentication
    * **User Events**: Triggered by user interactions in pages
    * **Automation Events**: Created by automation execution
    * **Custom Events**: Defined by developers for application-specific needs

    Events can be:

    * **Emitted** by pages and automations
    * **Listened for** by automations to trigger actions
    * **Queried** for analysis and reporting
    * **Persisted** for auditing and historical analysis
  </Tab>
</Tabs>

## Working with Events

<Steps>
  <Step title="Emitting Events">
    In automations, you can emit events to trigger other processes:

    ```yaml theme={null}
    - emit:
        event: user-action-completed
        payload:
          userId: "{{user.id}}"
          action: "profile-update"
          timestamp: "{{now}}"
    ```

    Pages can also emit events when users interact with the interface:

    ```tsx theme={null}
    events.emit("user-update-profile", {
      section: "personal-info",
    })
    ```

    These events flow through the system and can trigger other automations or be recorded for analysis.
  </Step>

  <Step title="Listening for Events">
    Automations can be triggered by specific events:

    ```yaml theme={null}
    slug: "process-profile-update"
    name: "Process Profile Update"
    when:
      events:
        - user-update-profile
    do:
      - set: payload
        value: "{{event.payload}}"
      - callAPI:
          method: POST
          url: /api/profiles/update
          body: "{{payload}}"
    ```

    This creates a chain of actions that can flow through your application, each step triggered by the completion of previous steps.
  </Step>

  <Step title="Accessing Event History">
    View event history in several ways:

    * **Activity Tab**: See recent events in your workspace
    * **Event Explorer**: Query and filter events for analysis
    * **Elasticsearch or OpenSearch**: Advanced querying for deeper analysis

    The complete event stream provides valuable insights into application usage, performance, and user behavior.
  </Step>

  <Step title="Analyzing Event Patterns">
    Advanced analytics can reveal important patterns:

    * **User Journeys**: Track how users move through your application
    * **Bottlenecks**: Identify where processes slow down
    * **Error Patterns**: Detect recurring issues
    * **Usage Trends**: See how usage evolves over time
    * **Feature Adoption**: Measure which features are most used

    These insights drive continuous improvement of your applications.
  </Step>
</Steps>

## Advanced Event Analytics

Every event in your workspace is stored in Elasticsearch or OpenSearch, enabling custom analysis:

<CardGroup cols="2">
  <Card title="System Mapping" icon="sitemap">
    Create visual maps of your systems based on actual usage:

    <ul>
      Track event flows between components

      Visualize user journeys through your application

      Identify unused features or dead-end paths

      Discover unexpected usage patterns

      Map integration points with external systems
    </ul>
  </Card>

  <Card title="Usage Analytics" icon="chart-line">
    Understand how users engage with your applications:

    <ul>
      Measure feature adoption and frequency of use

      Track user session patterns and duration

      Identify popular and underutilized features

      Analyze conversion funnels and drop-off points

      Segment users by behavior patterns
    </ul>
  </Card>

  <Card title="Performance Monitoring" icon="gauge-high">
    Track system performance metrics:

    <ul>
      Measure response times for different operations

      Identify bottlenecks in processing flows

      Track API usage and latency

      Monitor automation execution times

      Analyze resource utilization patterns
    </ul>
  </Card>

  <Card title="Pattern Discovery" icon="magnifying-glass-chart">
    Find meaningful patterns in your event data:

    <ul>
      Discover common user behavior sequences

      Identify correlations between events

      Detect anomalies that may indicate issues

      Recognize seasonal or time-based patterns

      Find optimization opportunities
    </ul>
  </Card>
</CardGroup>

## Event Mapping for Analytics

<Accordion title="Introduction to Event Mapping">
  As part of Prisme.ai's event-driven architecture, we process events structured with a dynamic identifier `payload`. To ensure consistent and efficient aggregation in both Elasticsearch and OpenSearch, it's essential to explicitly define the mapping for fields used in the payload.

  Without proper mapping, you may encounter issues such as:

  * Aggregation inconsistencies between Elasticsearch and OpenSearch
  * Fields interpreted with incorrect data types
  * Performance issues with complex queries
  * Limitations in available analysis capabilities
</Accordion>

<Accordion title="Benefits of Explicit Mapping">
  <CardGroup cols="2">
    <Card title="Reliability and Consistency" icon="check-double">
      Ensures uniform data treatment:

      <ul>
        Consistent field types across all events

        Prevents errors caused by automatic inference

        Guarantees that aggregations work properly

        Maintains data integrity over time
      </ul>
    </Card>

    <Card title="Performance Optimization" icon="bolt">
      Improves query and analysis speed:

      <ul>
        Optimizes indexing for known data structures

        Enables more efficient storage patterns

        Improves complex aggregation performance

        Reduces processing overhead for queries
      </ul>
    </Card>

    <Card title="Maintenance and Scalability" icon="arrows-up-down-left-right">
      Simplifies ongoing management:

      <ul>
        Easy-to-read YAML configuration

        Workspace-specific mapping definitions

        Simplified schema evolution

        Better documentation of data structures
      </ul>
    </Card>

    <Card title="Cross-Platform Compatibility" icon="globe">
      Works consistently across search engines:

      <ul>
        Identical behavior in Elasticsearch and OpenSearch

        Consistent query results across environments

        Reliable migrations between search technologies

        Future-proof for search engine updates
      </ul>
    </Card>
  </CardGroup>
</Accordion>

<Accordion title="Implementing Event Mapping">
  To implement explicit event mapping, add configuration to your workspace YAML:

  ```yaml theme={null}
  events:
    types:
      usage:
        schema:
          usage:
            type: object
            title: Usage
            properties:
              total_tokens:
                type: number
              completion_tokens:
                type: number
              prompt_tokens:
                type: number
              cost:
                type: number
                format: double
              firstTokenDuration:
                type: number
  ```

  <Info>
    This example defines the schema for the `usage` event type, specifying that fields like `usage.total_tokens` and `usage.cost` should be treated as numeric values with specific formats.
  </Info>

  When implementing:

  1. Identify the event types requiring explicit mapping
  2. Define their schema with appropriate data types
  3. Add the configuration to your Workspace
  4. Emit sample events
  5. Test with analytical queries to verify proper behavior

  <Note>When declaring a new field inside events mapping, ES/OS should take it into account for any **upcoming** event. </Note>
  <Note>When updating an existing field inside events mapping, the ES/OS index must be rollover'ed to take it into account for future events. </Note>
</Accordion>

<Accordion title="Advanced Usage Analytics Example">
  Here's how you might use mapped events for advanced analytics:

  ```javascript theme={null}
  // Query to analyze token usage patterns over time
  const usageAnalytics = await searchEvents({
    "query": {
      "bool": {
        "filter": [
          {
            "term": {
              "type": "usage"
            }
          }
        ]
      }
    },
    aggs: {
      usage_over_time: {
        date_histogram: {
          field: "createdAt",
          interval: "day"
        },
        aggs: {
          total_tokens: {
            sum: {
              field: "aggPayload.usage.total_tokens"
            }
          },
          avg_cost: {
            avg: {
              field: "aggPayload.usage.cost"
            }
          },
          models: {
            terms: {
              field: "aggPayload.model"
            }
          }
        }
      }
    }
  });

  // Results can be used for visualizations, billing, or optimization
  ```

  With proper mapping, these aggregations will be fast and accurate, providing valuable insights into application usage and performance.

  <Note>Note our aggregation needs to target aggPayload.\* to benefit from our custom mapping</Note>
</Accordion>

## Practical Event-Driven Patterns

<AccordionGroup>
  <Accordion title="User Activity Tracking">
    Track and analyze user behavior:

    ```yaml theme={null}
    # Emit events for user actions
    - emit:
        event: user-action
        payload:
          action: page-view
          page: "{{page.slug}}"
          sessionId: "{{session.id}}"
          timestamp: "{{now}}"
    ```

    These events can be analyzed to:

    * Create user journey maps
    * Identify popular features
    * Measure engagement
    * Detect unusual behavior
    * Personalize experiences based on usage patterns
  </Accordion>

  <Accordion title="AI Model Performance Tracking">
    Monitor and optimize AI model usage:

    ```yaml theme={null}
    # Emit events for AI model usage
    - emit:
        event: model-usage
        payload:
          model: "{{model.name}}"
          prompt_tokens: "{{result.usage.prompt_tokens}}"
          completion_tokens: "{{result.usage.completion_tokens}}"
          total_tokens: "{{result.usage.total_tokens}}"
          duration: "{{result.duration}}"
          cost: "{{result.cost}}"
    ```

    This data enables:

    * Cost tracking and optimization
    * Performance benchmarking
    * Model selection refinement
    * Usage pattern analysis
    * Identifying optimization opportunities
  </Accordion>

  <Accordion title="Multi-Step Workflows">
    Implement complex business processes through event chains:

    ```yaml theme={null}
    # First automation: Document processing initiated
    - emit:
        event: document-processing-started
        payload:
          documentId: "{{document.id}}"
          stage: "initiated"
          
    # Second automation (triggered by the first event)
    when:
      events:
        - document-processing-started
    do:
      # Process document...
      - emit:
          event: document-processing-completed
          payload:
            documentId: "{{event.payload.documentId}}"
            stage: "processed"
            
    # Third automation (triggered by the second event)
    when:
      events:
        - document-processing-completed
    do:
      # Generate summary...
      - emit:
          event: document-summary-ready
          payload:
            documentId: "{{event.payload.documentId}}"
            stage: "summarized"
    ```

    This approach creates modular, maintainable workflows that are:

    * Easily extendable with new steps
    * Resilient to failures (steps can be retried individually)
    * Transparent (full visibility into process state)
    * Analyzable (measure performance of each step)
  </Accordion>
</AccordionGroup>