Event-driven architecture

This document provides a detailed technical overview of the event-driven architecture used for publishing ticket-related events. It is intended for developers responsible for maintaining and extending the application's messaging capabilities. The core of this system is built around RabbitMQ, leveraging Spring AMQP for seamless integration.

For a higher-level overview of the system's design, refer to the Core Architecture documentation.

Event publishing

The application employs an event-driven model to decouple core business logic from downstream processes. Whenever a ticket is created or updated, the system automatically publishes an event to a message broker. This asynchronous communication pattern ensures that the primary ticket management operations are not blocked by secondary tasks like notifications, analytics, or data warehousing.

Event publishing is encapsulated within the MessagePublisher service. This service is injected into other business-logic components (e.g., TicketService) and is responsible for sending event objects to RabbitMQ.

The implementation uses Spring's RabbitTemplate for a high-level, simplified approach to message production.

// src/main/java/com/slalom/demo/ticketing/service/MessagePublisher.java

package com.slalom.demo.ticketing.service;

import com.slalom.demo.ticketing.event.TicketEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor // Injects RabbitTemplate via constructor
@Slf4j
public class MessagePublisher {

    private final RabbitTemplate rabbitTemplate;

    // Exchange and routing key are externalized for environment flexibility
    @Value("${rabbitmq.exchange.name}")
    private String exchangeName;

    @Value("${rabbitmq.routing.key}")
    private String routingKey;

    /**
     * Publishes a TicketEvent to the configured RabbitMQ exchange.
     * The event object is automatically converted to JSON.
     * @param event The TicketEvent to publish.
     */
    public void publishTicketEvent(TicketEvent event) {
        log.info("Publishing ticket event: {} for ticket ID: {}", event.getEventType(), event.getTicketId());
        // Sends the event to the specified exchange with the routing key
        rabbitTemplate.convertAndSend(exchangeName, routingKey, event);
        log.info("Successfully published event to exchange: {}", exchangeName);
    }
}

Developer Gotcha: The MessagePublisher is designed to be a singleton bean. Any service that needs to publish an event should inject this bean rather than attempting to interact with RabbitTemplate directly. This maintains a single point of control and configuration for event publishing.

Event structure

All ticket-related events are represented by the TicketEvent Plain Old Java Object (POJO). This class serves as the data transfer object (DTO) for our messaging system. It contains a snapshot of the ticket's state at the time of the event, along with metadata about the event itself.

The use of Lombok's @Data and @Builder annotations significantly reduces boilerplate code, making the class clean and maintainable.

// src/main/java/com/slalom/demo/ticketing/event/TicketEvent.java

package com.slalom.demo.ticketing.event;

import com.slalom.demo.ticketing.model.TicketPriority;
import com.slalom.demo.ticketing.model.TicketStatus;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

@Data // Generates getters, setters, toString(), equals(), hashCode()
@NoArgsConstructor
@AllArgsConstructor
@Builder // Provides a builder pattern for object creation
public class TicketEvent {

    private String eventType; // "CREATED", "UPDATED"
    private Long ticketId;
    private String title;
    private TicketStatus status;
    private TicketPriority priority;
    private String requesterEmail;
    private String assignedTo;
    private LocalDateTime timestamp;
}

The table below details the fields within the TicketEvent payload. Consumers of this event can rely on this structure.

Field	Type	Description
eventType	String	The type of event that occurred. Expected values are CREATED and UPDATED.
ticketId	Long	The unique identifier of the ticket that this event pertains to.
title	String	A snapshot of the ticket's title at the time of the event.
status	TicketStatus	An enum representing the ticket's status (e.g., OPEN, IN_PROGRESS, CLOSED).
priority	TicketPriority	An enum representing the ticket's priority (e.g., LOW, MEDIUM, HIGH).
requesterEmail	String	The email address of the user who created the ticket.
assignedTo	String	The identifier of the user or group the ticket is assigned to. Can be null.
timestamp	LocalDateTime	The UTC timestamp indicating when the event was generated by the application.

For more details on the event payload and consumer-side expectations, see the Events API Reference.

Message flow

The flow of a message from producer to consumer is orchestrated by Spring AMQP and defined in RabbitMQConfig. This configuration class programmatically declares the necessary RabbitMQ topology (exchanges, queues, and bindings).

1. Event Creation: A business operation in a service (e.g., TicketService) creates or updates a ticket.
2. Publication: The service calls messagePublisher.publishTicketEvent(event).
3. Serialization: The RabbitTemplate uses the configured Jackson2JsonMessageConverter to serialize the TicketEvent object into a JSON string. This is a critical step that makes the message payload language-agnostic.
4. Exchange Routing: The message is sent to a TopicExchange. Topic exchanges route messages to queues based on pattern matching between the message's routing key and the pattern used to bind the queue to the exchange.
5. Queueing: The message is placed in a durable queue, meaning it will persist even if the RabbitMQ broker restarts.
6. Consumption: Downstream services (consumers) listening to this queue will receive the message for processing.

The configuration below defines the necessary beans to establish this flow.

// src/main/java/com/slalom/demo/ticketing/config/RabbitMQConfig.java

package com.slalom.demo.ticketing.config;

import org.springframework.amqp.core.*;
import org.springframework.amqp.rabbit.connection.ConnectionFactory;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.amqp.support.converter.Jackson2JsonMessageConverter;
import org.springframework.amqp.support.converter.MessageConverter;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class RabbitMQConfig {

    @Value("${rabbitmq.exchange.name}")
    private String exchangeName;

    @Value("${rabbitmq.queue.name}")
    private String queueName;

    @Value("${rabbitmq.routing.key}")
    private String routingKey;

    @Bean
    public Queue queue() {
        return new Queue(queueName, true);
    }

    @Bean
    public TopicExchange exchange() {
        return new TopicExchange(exchangeName);
    }

    @Bean
    public Binding binding(Queue queue, TopicExchange exchange) {
        return BindingBuilder.bind(queue).to(exchange).with(routingKey);
    }

    @Bean
    public MessageConverter messageConverter() {
        return new Jackson2JsonMessageConverter();
    }

    @Bean
    public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
        RabbitTemplate rabbitTemplate = new RabbitTemplate(connectionFactory);
        rabbitTemplate.setMessageConverter(messageConverter());
        return rabbitTemplate;
    }
}

Key Implementation Details:

• Externalized Configuration: The names for the queue, exchange, and routing key are sourced from external configuration files. This is best practice, allowing for different topologies in different environments (dev, staging, prod). See the RabbitMQ Configuration Guide for details on these properties.
• Durable Queue: The queue is declared as durable (new Queue(queueName, true)). This ensures that if the RabbitMQ broker is restarted, any messages waiting in the queue will not be lost.
• Topic Exchange: Using a TopicExchange provides routing flexibility. While the current implementation uses a static routing key, this setup allows for future expansion where consumers could subscribe to subsets of events using wildcard routing keys (e.g., tickets.created.* or tickets.#).

Integration patterns

The messaging implementation embodies several key architectural patterns that are fundamental to building scalable and resilient distributed systems.

• Producer-Consumer Model: The application acts as a Producer of TicketEvent messages. Other applications or services within our ecosystem act as Consumers. This pattern decouples the producer from the consumers; the producer does not need to know who is consuming the events, how many consumers there are, or what they do with the information.

• Asynchronous Processing: By publishing an event and moving on, the application's primary thread is not blocked waiting for downstream tasks to complete. This improves the application's responsiveness and throughput, as it can handle the next request more quickly. For example, sending an email notification, updating a search index, and pushing data to an analytics platform can all happen in parallel and independently of the core ticket update transaction.

• Event-driven Microservices: This architecture is a cornerstone for building a microservices ecosystem. Events act as the primary means of communication between services. Instead of making direct, synchronous API calls between services (which can lead to tight coupling and cascading failures), services communicate by producing and consuming events. This promotes loose coupling and service autonomy, allowing individual services to be developed, deployed, and scaled independently. For more on how this fits into the larger system, see the Core Architecture documentation.