Welcome to the first part of our “Building with Akka” series, where we’ll create a Customer Registry Application using the Akka SDK. This case study, introduced in our previous article, will demonstrate core Akka patterns in action. We’ll explore how to build a robust, event-sourced system that manages customer data with reliability and scalability. Follow along as we implement this practical example step by step, showcasing the power of Akka in distributed applications.

The customer registry application allows you to create, retrieve, and update customer records while maintaining a complete history of all changes through event sourcing. It showcases how the SDK’s high-level components make it straightforward to implement complex distributed system patterns without getting bogged down in the technical details.

The implementation we’ll explore comes directly from the Akka team, ensuring you’ll learn best practices straight from the source. Let’s dive into building this application step by step.

Download the artifacts and compile the application

Akka CLI, the command line tool provided by Akka, can be used to list and download several examples.

akka quickstart list

The quickstart list command provides a list of examples. The output is similar to the following:

ID                  NAME                LANGUAGE   OUTPUT_DIR          
shopping-cart       Shopping Cart       java       shopping-cart       
customer-registry   Customer Registry   java       customer-registry   
choreography-saga   Choreography Saga   java       choreography-saga  
transfer-workflow   Transfer Workflow   java       transfer-workflow

In order to download an example, the quickstart download <ID> command is provided. Run the following command to download the customer registry example:

akka quickstart download customer-registry

The project is downloaded and unzipped into the customer-registry directory. The application is a Maven project and a pom.xml is provided. If Maven is installed, you can compile, build, and run the application with mvn.

Make sure your project compiles:

mvn compile

Then open the project in your favorite IDE.

Understanding the customer registry

This is a brief overview of the classes presented in the next sections:

Domain Classes

• Customer: Immutable record representing customer data
• Address: Immutable record for customer address
• CustomerEvent: Sealed interface for customer-related events
  • CustomerCreated: a new customer has been created
  • NameChanged: the name of an existing customer has been updated
  • AddressChanged: the address of an existing customer has been updated

Application Classes

• CustomerEntity: event-sourced entity managing the customer state
• CustomerByNameView: view for querying customers by name
• CustomerByEmailView: view for querying customers by email
• CustomerEndpoint: HTTP endpoint for customer operations

Data Transfer Objects

• CreateCustomerRequest: request payload to create a new customer
• CreateAddressRequest: represent the address in the CreateCustomerRequest
• CustomerRow: same as Customer, decouple views and entity
• AddressRow: same as Address, decouple view and entity

This example embraces the Command Query Responsibility Segregation (CQRS) pattern, by modelling events and commands separately. Events are modelled as a hierarchy of immutable classes, where the parent class is the CustomerEvent type. Commands are implemented as class methods in the CustomerEntity class. It’s important to note that commands does not directly change the status of the entity, but rather they generate a series of events that will eventually update the status.

In the next section, we will explore how to:

• model customer data using immutable records;
• define and handle domain events for customer operations;
• implement an event-sourced entity that maintains customer state.