DEV Community: Kim Seon Woo

Building a Distributed Chat App in Spring Boot (No Redis Required)

Kim Seon Woo — Tue, 18 Nov 2025 16:27:36 +0000

Most tutorials on building distributed chat systems start with "First, install Redis..." or "Set up RabbitMQ..." But what if you didn't need any of that?

Here's how to build a production-ready distributed chat system using just Spring Boot and actors. No external message brokers. No Redis for pub/sub. Just clean code that scales across multiple nodes.

What We're Building

A real-time chat system where:

Users connect via WebSocket
Rooms are automatically distributed across cluster nodes
Messages broadcast instantly to all room participants
Everything scales horizontally without configuration changes

The architecture uses three key pieces: sharded actors for chat rooms, regular actors for user connections, and pub/sub topics for message distribution.

Step 1: The Chat Room Actor

Each chat room is a sharded actor. Sharding automatically distributes rooms across cluster nodes—create 1000 rooms, they'll spread across your nodes automatically.

@Component
public class ChatRoomActor implements SpringShardedActor<ChatRoomActor.Command> {

    public static final EntityTypeKey<Command> TYPE_KEY =
        EntityTypeKey.create(Command.class, "ChatRoomActor");

    private final SpringTopicManager topicManager;

    public ChatRoomActor(SpringTopicManager topicManager) {
        this.topicManager = topicManager;
    }

    @Override
    public EntityTypeKey<Command> typeKey() {
        return TYPE_KEY;
    }

    @Override
    public SpringShardedActorBehavior<Command> create(SpringShardedActorContext<Command> ctx) {
        String roomId = ctx.getEntityId();

        // Create a pub/sub topic for this room using SpringTopicManager
        SpringTopicRef<UserActor.Command> roomTopic = topicManager
            .topic(UserActor.Command.class)
            .withName("chat-room-" + roomId)
            .getOrCreate();

        return SpringShardedActorBehavior.builder(Command.class, ctx)
            .withState(behaviorCtx -> new ChatRoomBehavior(behaviorCtx, roomTopic))
            .onMessage(JoinRoom.class, ChatRoomBehavior::onJoinRoom)
            .onMessage(SendMessage.class, ChatRoomBehavior::onSendMessage)
            .build();
    }
}

The critical part: each room creates its own pub/sub topic. When a message arrives, broadcast it to the topic. Everyone subscribed receives it automatically.

private static class ChatRoomBehavior {
    private final SpringTopicRef<UserActor.Command> roomTopic;

    private Behavior<Command> onJoinRoom(JoinRoom msg) {
        SpringActorRef<UserActor.Command> userRef =
            new SpringActorRef<>(ctx.getSystem().scheduler(), msg.userActorRef);

        // Subscribe user to room's topic
        roomTopic.subscribe(userRef);

        // Notify everyone
        roomTopic.publish(new UserActor.JoinRoomEvent(msg.userId));
        return Behaviors.same();
    }

    private Behavior<Command> onSendMessage(SendMessage msg) {
        // Broadcast to all subscribers
        roomTopic.publish(new UserActor.SendMessageEvent(msg.userId, msg.message));
        return Behaviors.same();
    }
}

No loops. No tracking who's in the room. Just publish to a topic.

Step 2: The User Actor

Each connected WebSocket gets a user actor. This actor subscribes to room topics and forwards messages to the WebSocket.

@Component
public class UserActor implements SpringActorWithContext<
    UserActor.Command, UserActor.UserActorContext> {

    public static class UserActorContext extends SpringActorContext {
        private final SpringActorSystem actorSystem;
        private final String userId;
        private final Sinks.Many<String> messageSink;  // WebSocket output

        public UserActorContext(SpringActorSystem actorSystem,
                                String userId,
                                Sinks.Many<String> messageSink) {
            this.actorSystem = actorSystem;
            this.userId = userId;
            this.messageSink = messageSink;
        }

        @Override
        public String actorId() {
            return userId;
        }
    }

    @Override
    public SpringActorBehavior<Command> create(UserActorContext actorContext) {
        return SpringActorBehavior.builder(Command.class, actorContext)
            .withState(ctx -> new UserActorBehavior(
                ctx, actorContext.actorSystem,
                actorContext.userId, actorContext.messageSink))
            .onMessage(JoinRoom.class, UserActorBehavior::onJoinRoom)
            .onMessage(SendMessageEvent.class, UserActorBehavior::onSendMessageEvent)
            .build();
    }
}

The clever part: when the user actor receives an event from the pub/sub topic, it forwards it to the WebSocket sink:

private static class UserActorBehavior {
    private final Sinks.Many<String> messageSink;
    private String currentRoomId;

    private Behavior<Command> onJoinRoom(JoinRoom command) {
        currentRoomId = command.getRoomId();

        // Tell the room actor to subscribe us
        SpringShardedActorRef<ChatRoomActor.Command> roomActor =
            actorSystem.sharded(ChatRoomActor.class)
                .withId(currentRoomId)
                .get();

        roomActor.tell(new ChatRoomActor.JoinRoom(
            userId,
            context.getUnderlying().getSelf()  // Send raw ActorRef for cluster serialization
        ));

        return Behaviors.same();
    }

    private Behavior<Command> onSendMessageEvent(SendMessageEvent event) {
        // Received via pub/sub topic - forward to WebSocket
        String json = String.format(
            "{\"type\":\"message\",\"userId\":\"%s\",\"message\":\"%s\",\"roomId\":\"%s\"}",
            event.userId, event.message, currentRoomId
        );
        messageSink.tryEmitNext(json);
        return Behaviors.same();
    }
}

Step 3: WebSocket Handler

Connect the WebSocket to the actor system:

@Component
public class ChatWebSocketHandler implements WebSocketHandler {
    private final SpringActorSystem actorSystem;
    private final ConcurrentMap<String, SpringActorRef<UserActor.Command>> userActors =
        new ConcurrentHashMap<>();

    @Override
    public Mono<Void> handle(WebSocketSession session) {
        String userId = UUID.randomUUID().toString();

        // Create a sink for outgoing messages
        Sinks.Many<String> sink = Sinks.many().multicast().onBackpressureBuffer();

        // Create user actor with the sink
        UserActor.UserActorContext context =
            new UserActor.UserActorContext(actorSystem, userId, sink);

        return Mono.fromCompletionStage(actorSystem
                .actor(UserActor.class)
                .withContext(context)
                .spawn())
            .flatMap(userActor -> {
                userActors.put(userId, userActor);
                userActor.tell(new UserActor.Connect());

                // Handle incoming messages
                Mono<Void> input = session.receive()
                    .map(WebSocketMessage::getPayloadAsText)
                    .flatMap(payload -> handleMessage(userId, payload))
                    .then();

                // Send outgoing messages
                Mono<Void> output = session.send(
                    sink.asFlux().map(session::textMessage)
                );

                return Mono.zip(input, output)
                    .doFinally(signalType -> cleanup(userId))
                    .then();
            });
    }

    private Mono<Void> handleMessage(String userId, String payload) {
        return Mono.fromCallable(() -> {
            JsonNode json = objectMapper.readTree(payload);
            String type = json.get("type").asText();

            SpringActorRef<UserActor.Command> userActor = userActors.get(userId);
            if (userActor == null) return null;

            switch (type) {
                case "join":
                    String roomId = json.get("roomId").asText();
                    userActor.tell(new UserActor.JoinRoom(roomId));
                    break;
                case "message":
                    String message = json.get("message").asText();
                    userActor.tell(new UserActor.SendMessage(message));
                    break;
            }
            return null;
        })
        .subscribeOn(Schedulers.boundedElastic())  // Offload blocking JSON parsing
        .then();
    }

    private void cleanup(String userId) {
        SpringActorRef<UserActor.Command> userActor = userActors.remove(userId);
        if (userActor != null) {
            userActor.stop();
        }
    }
}

The Message Flow

Here's what happens when a user sends a message:

WebSocket receives JSON → handleMessage() parses it
Handler tells UserActor → "SendMessage" command
UserActor tells ChatRoomActor → "SendMessage" command
ChatRoomActor publishes to room topic
All subscribed UserActors receive the event via pub/sub
Each UserActor forwards to its WebSocket sink
WebSocket sends JSON to browser

The pub/sub topic handles distribution automatically. Works the same whether actors are on the same node or different nodes.

What Makes This Work

Three features combine to create the full system:

Sharded Actors: Chat rooms are SpringShardedActor, so they're automatically distributed across cluster nodes. Create room "lobby" on node 1, room "random" ends up on node 2. You don't control it, you don't need to.

Pub/Sub Topics: Each room creates a topic. Publish once, all subscribers receive it. Topics work across cluster boundaries transparently.

Actor Context: UserActorContext passes the WebSocket sink into the actor. The actor can now write directly to the WebSocket without coupling to HTTP infrastructure.

Running It Locally

Start a 3-node cluster:

sh cluster-start.sh chat io.github.seonwkim.example.SpringPekkoApplication 8080 2551 3

Start the frontend:

cd example/chat/frontend
npm run dev

Open multiple browser tabs. Join the same room from different tabs. Send messages. They broadcast instantly.

Check the logs—you'll see rooms distributed across different nodes, but messages flow seamlessly.

Why This Matters

You just built a distributed chat system without:

Installing Redis for pub/sub
Setting up RabbitMQ or Kafka
Writing message routing logic
Managing WebSocket connections in a shared store
Dealing with sticky sessions or load balancer config

The actor model plus pub/sub topics give you distributed messaging built into the framework. Add nodes, rooms automatically distribute. Remove nodes, rooms migrate. The cluster handles it.

When to Use This Pattern

This works well for:

Chat applications (obviously)
Live notifications
Collaborative editing
Real-time dashboards
Multiplayer game lobbies
Any broadcast messaging scenario

Skip this if you need:

Message persistence (actors are in-memory)
Exactly-once delivery guarantees
Complex message routing logic
Integration with existing message brokers

The Source Code

Full implementation: Chat Example on GitHub

Complete documentation: spring-boot-starter-actor

Wrapping Up

The actor model isn't just for academics. Combine sharded actors for distribution, pub/sub topics for broadcasting, and WebSockets for client communication, and you get a chat system that scales horizontally without external dependencies.

No Redis. No RabbitMQ. No complex configuration. Just actors, topics, and clean code.

Try it yourself and see how much simpler distributed systems can be when the framework handles the hard parts for you.

Distributed Pub/Sub in Spring Boot Without the Headache

Kim Seon Woo — Tue, 18 Nov 2025 16:15:18 +0000

You're building a chat room. Or a notification system. Or anything that needs to broadcast messages to multiple subscribers. Five minutes in, you're already knee-deep in managing collections of actor references, handling subscription lifecycles, and wondering why this simple concept requires so much plumbing.

The publish-subscribe pattern solves this elegantly—when it's done right. But implementing distributed pub/sub from scratch means dealing with cluster coordination, message routing, and subscriber cleanup. Not exactly a fun afternoon.

This is why spring-boot-starter-actor includes a topic feature that gives you distributed pub/sub with three lines of code.

What You Usually End Up With

Here's the manual approach most people start with:

@Component
public class ChatRoomActor {
    private final Set<ActorRef<Message>> subscribers = new HashSet<>();

    public void addUser(ActorRef<Message> userActor) {
        subscribers.add(userActor);
    }

    public void broadcast(Message msg) {
        for (ActorRef<Message> subscriber : subscribers) {
            subscriber.tell(msg);
        }
    }
}

Works fine until:

You need to scale across multiple nodes (subscribers are on different machines)
An actor dies and leaves a dead reference in your set
You forget to unsubscribe someone and cause a memory leak
You realize you're reinventing pub/sub poorly

What It Should Look Like

With topics, broadcasting becomes trivial:

@Service
public class ChatService {
    private final SpringTopicManager topicManager;

    public void sendMessage(String roomId, String userId, String message) {
        SpringTopicRef<ChatMessage> roomTopic = topicManager
            .topic(ChatMessage.class)
            .withName("chat-room-" + roomId)
            .getOrCreate();

        roomTopic.publish(new ChatMessage(userId, message));
    }
}

Three lines. No loops. No subscriber tracking. Works in both local mode and across a distributed cluster.

How It Works Under the Hood

The topic feature is built on three layers:

1. Topic Lifecycle Management

When you call topicManager.topic(MessageType.class).withName("name").getOrCreate(), the SpringTopicManager asks the RootGuardian actor to create or retrieve a topic. The RootGuardian maintains all top-level actors in your system and ensures topics are created exactly once.

Topics are identified by both name and message type:

// From DefaultRootGuardian.java
private String buildTopicActorName(String topicName, Class<?> messageType) {
    return "topic-" + topicName + "-" + messageType.getName().replace(".", "_");
}

This means topic(String.class).withName("chat") and topic(Integer.class).withName("chat") are completely different topics. Type safety at the infrastructure level.

2. Pekko's Distributed Pub/Sub

Under the hood, each topic is a Pekko Topic actor. Pekko handles:

Distributing messages across cluster nodes
Cleaning up dead subscribers automatically
Routing messages efficiently
Maintaining subscriber lists per node

You publish a message. Pekko makes sure every subscriber gets it, no matter which node they're on.

3. Spring-Friendly API

SpringTopicRef wraps the Pekko topic with a clean API:

public class SpringTopicRef<T> {
    public void publish(T message) { ... }
    public void subscribe(SpringActorRef<T> subscriber) { ... }
    public void unsubscribe(SpringActorRef<T> subscriber) { ... }
}

The generic type <T> prevents you from subscribing the wrong actor type to a topic at compile time. If your topic publishes ChatMessage, you can't accidentally subscribe an actor that expects UserMessage.

Putting It Together: Distributed Chat

Here's a complete chat room implementation using sharded actors and topics:

@Component
public class ChatRoomActor implements SpringShardedActor<ChatRoomActor.Command> {

    private final SpringTopicManager topicManager;

    public ChatRoomActor(SpringTopicManager topicManager) {
        this.topicManager = topicManager;
    }

    @Override
    public SpringShardedActorBehavior<Command> create(SpringShardedActorContext<Command> ctx) {
        String roomId = ctx.getEntityId();

        // Create a topic for this room
        SpringTopicRef<UserActor.Command> roomTopic = topicManager
            .topic(UserActor.Command.class)
            .withName("chat-room-" + roomId)
            .create();

        return SpringShardedActorBehavior.builder(Command.class, ctx)
            .withState(behaviorCtx -> new ChatRoomBehavior(behaviorCtx, roomTopic))
            .onMessage(JoinRoom.class, ChatRoomBehavior::onJoinRoom)
            .onMessage(SendMessage.class, ChatRoomBehavior::onSendMessage)
            .build();
    }

    private static class ChatRoomBehavior {
        private final SpringTopicRef<UserActor.Command> roomTopic;

        private Behavior<Command> onJoinRoom(JoinRoom msg) {
            // Subscribe the user actor to the room's topic
            SpringActorRef<UserActor.Command> userRef =
                new SpringActorRef<>(ctx.getSystem().scheduler(), msg.userActorRef);
            roomTopic.subscribe(userRef);

            // Broadcast join notification to all subscribers
            roomTopic.publish(new UserActor.JoinRoomEvent(msg.userId));
            return Behaviors.same();
        }

        private Behavior<Command> onSendMessage(SendMessage msg) {
            // Broadcast the message to all subscribers
            roomTopic.publish(new UserActor.SendMessageEvent(msg.userId, msg.message));
            return Behaviors.same();
        }
    }
}

Each chat room actor creates its own topic. Users subscribe to the topic when they join. Messages get broadcast to everyone. That's it.

The chat room doesn't track user references. It doesn't loop through subscribers. It just publishes to a topic, and Pekko handles the rest—including routing messages across cluster nodes if your rooms are distributed.

When Topics Make Sense

Use topics when you need:

One-to-many broadcasting - chat rooms, notifications, live feeds
Decoupled publishers and subscribers - neither side knows about the other
Dynamic subscriptions - actors join and leave freely without manual tracking
Cluster-wide messaging - seamlessly works across distributed nodes

Skip topics for:

Point-to-point messaging - just use actor references directly
Guaranteed delivery - topics are at-most-once delivery
Request-response - use the ask pattern instead
Exactly-once semantics - you'll need additional infrastructure

The Honest Trade-Offs

Topics give you simplicity and distribution at the cost of delivery guarantees. Messages are delivered at-most-once—network issues or node failures can lose messages. There's also a small overhead compared to direct actor messaging.

For most broadcast use cases (chat, notifications, event streams), this is fine. You're trading perfect reliability for much simpler code that scales horizontally without thinking about it.

Getting Started

Add the dependency to your project:

dependencyManagement {
    imports {
        mavenBom("com.fasterxml.jackson:jackson-bom:2.17.3")
    }
}

// Spring Boot 3.2.x
implementation 'io.github.seonwkim:spring-boot-starter-actor_3:0.6.3'

Enable actor support:

@SpringBootApplication
@EnableActorSupport
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Inject SpringTopicManager and start publishing:

@Service
public class NotificationService {
    private final SpringTopicManager topicManager;

    public void broadcast(Notification notification) {
        topicManager.topic(Notification.class)
            .withName("system-notifications")
            .getOrCreate()
            .publish(notification);
    }
}

Try the Chat Example

The library includes a working distributed chat application:

# Start a 3-node cluster
$ sh cluster-start.sh chat io.github.seonwkim.example.SpringPekkoApplication 8080 2551 3

# Run the frontend
$ cd example/chat/frontend
$ npm run dev

Send messages between users across the cluster. Open the browser console to see which node each room lives on—rooms are distributed, but messages flow seamlessly.

Resources

Documentation: https://seonwkim.github.io/spring-boot-starter-actor/
Pub/Sub Guide: Topic Documentation
GitHub: spring-boot-starter-actor
Chat Example: Distributed Chat

Final Thoughts

Pub/sub topics aren't magic. They're Pekko's distributed Topic actor wrapped in a Spring-friendly API with lifecycle management through the RootGuardian. But that's all you need to stop writing manual subscription tracking code and let the framework handle distribution for you.

If you're building broadcast features—chat rooms, notifications, live feeds—topics will save you from a lot of error-prone plumbing. The code gets simpler, scales across nodes automatically, and you can focus on your actual business logic instead of debugging why subscriber cleanup isn't working.

Give it a try and see how much simpler your broadcast messaging becomes.

Bringing the Actor Model to Spring Boot with Pekko

Kim Seon Woo — Tue, 18 Nov 2025 11:57:18 +0000

If you've been building Spring Boot applications for a while, you've probably run into scenarios where traditional approaches to concurrency start to feel clunky. Maybe you're building a real-time chat application, an IoT platform processing thousands of device messages, or an event-driven system that needs to handle high throughput without losing its mind.

The actor model is a proven solution for these kinds of problems. But here's the thing: the Spring ecosystem doesn't have native actor support. And if your company has standardized on Spring, introducing a completely different framework just to get actors isn't exactly a trivial decision.

That's where spring-boot-starter-actor comes in.

The Actor Model Gap in Spring

Spring is great at what it does. Dependency injection, configuration management, data access—it's all there. But when it comes to building highly concurrent systems with isolated state and message passing, you're mostly on your own.

Meanwhile, in the JVM world, Pekko (an open-source fork of Akka) has been the go-to framework for actor-based systems. It's battle-tested, scales horizontally, and handles fault tolerance elegantly through supervision hierarchies. The problem? Integrating Pekko into a Spring application isn't straightforward. You end up writing a lot of glue code, managing two different dependency injection systems, and generally making things more complicated than they need to be.

What is spring-boot-starter-actor?

spring-boot-starter-actor is a Spring Boot starter that bridges this gap. It brings Pekko's actor model into Spring Boot applications with minimal friction. You get:

Auto-configuration: Just add the dependency and you're ready to go
Full Spring DI support: Your actors are Spring components with constructor injection
Local and cluster modes: Start simple, scale when you need to
Built-in monitoring: Prometheus metrics and Grafana dashboards included

Getting Started

Add the dependency to your project:

dependencyManagement {
    imports {
        mavenBom("com.fasterxml.jackson:jackson-bom:2.17.3")
    }
}

// Spring Boot 3.2.x
implementation 'io.github.seonwkim:spring-boot-starter-actor_3:0.6.3'

Enable actor support in your application:

@SpringBootApplication
@EnableActorSupport
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Creating Your First Actor

Actors are just Spring components that implement SpringActor:

@Component
public class GreeterActor implements SpringActor<GreeterActor.Command> {

    public interface Command {}

    public static class Greet extends AskCommand<String> implements Command {
        public final String name;

        public Greet(String name) {
            this.name = name;
        }
    }

    @Override
    public SpringActorBehavior<Command> create(SpringActorContext actorContext) {
        return SpringActorBehavior.builder(Command.class, actorContext)
            .onMessage(Greet.class, (ctx, msg) -> {
                msg.reply("Hello, " + msg.name + "!");
                return Behaviors.same();
            })
            .build();
    }
}

Each actor processes messages one at a time, so you never have to worry about concurrent access to its internal state. No locks, no synchronized blocks, no ConcurrentHashMap—just straightforward sequential code.

Using Actors in Your Services

Inject SpringActorSystem anywhere you need to work with actors:

@Service
public class GreeterService {
    private final SpringActorSystem actorSystem;

    public GreeterService(SpringActorSystem actorSystem) {
        this.actorSystem = actorSystem;
    }

    public CompletionStage<String> greet(String name) {
        return actorSystem.getOrSpawn(GreeterActor.class, "greeter")
            .thenCompose(actor -> actor
                .ask(new GreeterActor.Greet(name))
                .withTimeout(Duration.ofSeconds(5))
                .execute()
            );
    }
}

The getOrSpawn method either returns an existing actor or creates a new one. Actors have unique IDs within their type, so you can have thousands of greeter actors, each identified by a different ID.

Spring DI Just Works

Since actors are Spring components, you can inject whatever you need:

@Component
public class OrderActor implements SpringActor<OrderActor.Command> {

    private final OrderRepository orderRepository;
    private final PaymentService paymentService;

    public OrderActor(OrderRepository orderRepository,
                      PaymentService paymentService) {
        this.orderRepository = orderRepository;
        this.paymentService = paymentService;
    }

    // ... actor implementation
}

Your repositories, services, configurations—everything Spring knows about is available to your actors through regular constructor injection.

Scaling with Sharded Actors

When you're ready to distribute your actors across multiple nodes, switch to cluster mode and use sharded actors:

@Component
public class UserSessionActor implements SpringShardedActor<UserSessionActor.Command> {

    public static final EntityTypeKey<Command> TYPE_KEY =
        EntityTypeKey.create(Command.class, "UserSession");

    public interface Command extends JsonSerializable {}
    public record UpdateActivity(String activity) implements Command {}

    @Override
    public EntityTypeKey<Command> typeKey() {
        return TYPE_KEY;
    }

    @Override
    public SpringShardedActorBehavior<Command> create(SpringShardedActorContext<Command> ctx) {
        return SpringShardedActorBehavior.builder(Command.class, ctx)
            .withState(entityCtx -> new UserSessionState(ctx.getEntityId()))
            .onMessage(UpdateActivity.class, UserSessionState::onUpdateActivity)
            .build();
    }
}

Sharded actors are automatically distributed across your cluster nodes. When a message arrives for user "user-123", the cluster routes it to the right node. If that node goes down, the actor moves to another node. You don't have to manage any of this—it just works.

Real-World Use Cases

This isn't just theoretical. The library works well for:

Real-time applications: Chat systems, live notifications, collaborative editing
IoT platforms: Processing streams of device telemetry with per-device state
Event processing: Building event-sourced systems with aggregate actors
Rate limiting: Per-user or per-API-key rate limiters that maintain state
Saga orchestration: Long-running workflows with state and retries

What About Fault Tolerance?

Actors can fail. When they do, supervision strategies determine what happens:

actorSystem.actor(WorkerActor.class)
    .withId("worker-1")
    .withSupervisionStrategy(SupervisorStrategy.restart().withLimit(3, Duration.ofMinutes(1)))
    .spawn();

If an actor throws an exception, it can be automatically restarted, stopped, or resumed. Parent actors can supervise child actors, creating hierarchies that isolate failures and recover gracefully.

Try It Out

The library is available on Maven Central, and there's a full example of a distributed chat application you can run locally:

# Start a 3-node cluster
$ sh cluster-start.sh chat io.github.seonwkim.example.SpringPekkoApplication 8080 2551 3

# Run the frontend
$ cd example/chat/frontend
$ npm run dev

You can send messages between users, and they'll be routed correctly even though the actors are distributed across three different JVM processes.

Resources

Documentation: https://seonwkim.github.io/spring-boot-starter-actor/
GitHub: https://github.com/seonwkim/spring-boot-starter-actor
Discord: Join the community

Final Thoughts

Building concurrent systems doesn't have to be painful. The actor model provides a proven way to handle concurrency, distribution, and fault tolerance. And now, with spring-boot-starter-actor, you can use it in your Spring Boot applications without leaving the ecosystem you already know.

Give it a try, and let me know what you build with it.

Building a Distributed Chat App without Redis/Kafka

Kim Seon Woo — Thu, 29 May 2025 13:43:59 +0000

Full source code: examples-seonwkim/spring-boot-chat

Actor library: seonWKim/spring-boot-starter-actor

🤔 Why Actors?

Most distributed chat systems rely on middleware like Redis Pub/Sub or Kafka to deliver messages between users on different servers. But there's an alternative: clustering servers with a distributed actor system.

In this post, I’ll walk you through building a fully functional distributed chat app using:

🧩 Pekko (Akka’s Apache fork)
⚙️ Spring Boot 3
🔌 WebSocket + WebFlux
💬 Actors for session & room handling

📦 Setup: spring-boot-starter-actor

To reduce integration complexity, I created spring-boot-starter-actor, a library that brings native actor system support into Spring Boot.

Key dependencies:

dependencyManagement {
    imports {
        // pekko-serialization-jackson_3 require minimum 2.17.3 version of jackson
        mavenBom("com.fasterxml.jackson:jackson-bom:2.17.3")
    }
}

dependencies {
    implementation("io.github.seonwkim:spring-boot-starter-actor_3:0.0.25")
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("org.springframework.boot:spring-boot-starter-websocket")
    implementation("org.springframework.boot:spring-boot-starter-thymeleaf")
}

🧠 Architecture Overview

The application is structured around two core actor types:

UserActor ↔ ChatRoomActor

UserActor – Handles one user's session.
ChatRoomActor – Represents a unique room across the cluster.
WebSocketHandler – Bridges WebSocket and actor system.

Each user is represented by an actor that joins/leaves rooms and sends/receives messages. The room actor manages broadcasting to all users.

💬 WebSocket Setup

Create a WebSocket endpoint via Spring config:

@Configuration
@EnableWebSocket
class WebSocketConfig(
    private val chatWebSocketHandler: ChatWebSocketHandler
) : WebSocketConfigurer {
    override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
        registry.addHandler(chatWebSocketHandler, "/ws/chat").setAllowedOrigins("*")
    }
}

This sets up /ws/chat as your chat entrypoint.

🧑‍💻 UserActor (One per connected user)

Each connected WebSocket user is handled by their own actor:

class UserActor : SpringActor {
    data class JoinRoom(val roomId: String) : Command
    data class SendMessage(val message: String) : Command
    ...
}

Behavior:

On connect → Sends connected event
On JoinRoom → Registers with the ChatRoomActor
On message → Relays to ChatRoomActor
On cluster event → Receives JoinRoomEvent, LeaveRoomEvent, SendMessageEvent

🏠 ChatRoomActor (Cluster-sharded)

Rooms are unique across the cluster thanks to Pekko's Cluster Sharding:

class ChatRoomActor : ShardedActor<ChatRoomActor.Command> {
    data class JoinRoom(val userId: String, val userRef: ActorRef<UserActor.Command>) : Command
    data class SendMessage(val userId: String, val message: String) : Command
    ...
}

Each room:

Tracks active users
Broadcasts join/leave/message events
Lives on a node chosen by Pekko’s sharding strategy

🌐 WebSocket Handler

Bridges incoming WebSocket traffic to actors:

override fun handleTextMessage(session: WebSocketSession, message: TextMessage) {
    when (payload.get("type").asText()) {
        "join" -> userActor.tell(JoinRoom(roomId))
        "message" -> userActor.tell(SendMessage(message))
    }
}

Also handles connection setup/teardown and assigns userIds.

🚀 Running Multiple Nodes (Clustering)

Spin up a 3-node cluster with one script:

sh cluster-start.sh 8080 2551 3

Each instance gets a unique port and Pekko cluster port. Open localhost:8080, 8081, and 8082 in different tabs—voilà, distributed chat!

✅ Why This Rocks

❌ No Redis/Kafka/3rd-party message queue
✅ Horizontal scalability with Pekko sharding
🧠 Stateful logic using just actors
🕸 Seamless WebSocket session per user
🎯 Built with familiar Spring Boot ergonomics

🛠 Try it Yourself

Chat App: examples-seonwkim/spring-boot-chat
Actor Integration: seonWKim/spring-boot-starter-actor

🧭 Next Steps

Make the actor library production-grade (v1.0.0)
Add observability and failover strategies
Integrate persistent actors for message durability

💬 Feedback, questions, contributions — all welcome!

Let me know if you'd like a follow-up post diving into actor design patterns or cluster internals.

Synchronization Across Distributed Servers: DB vs Redis vs Actor

Kim Seon Woo — Sun, 11 May 2025 02:42:34 +0000

In distributed systems, one of the most common and tricky challenges is ensuring synchronized access to shared resources across multiple server instances.

For example, when a user initiates a money transfer, updates a shared task list, or interacts with a counter, the request may hit any instance in your cluster. Unless synchronized properly, this can result in race conditions, inconsistent state, or data corruption.

Traditional Synchronization Techniques

Developers typically reach for one of two well-known approaches:

1. Database Locking

Using pessimistic locking (SELECT ... FOR UPDATE) or JPA's @Lock(PESSIMISTIC_WRITE):

Simple and widely supported
Ties up database connections
Increases contention and slows down unrelated queries

2. Redis Locks

Using a distributed lock pattern (e.g., Redlock via Redisson):

Offloads lock state from the DB
Requires Redis infrastructure
Needs careful retry/backoff handling to be safe and reliable

Both methods require additional complexity and infrastructure to maintain, especially at scale.

A Simpler Alternative: Clustered Sharded Actors

Thanks to spring-boot-starter-actor, there's a third option: actor-based synchronization with no external system required.

The library integrates Apache Pekko cluster sharding into Spring Boot, enabling you to model shared entities as singleton actors across your cluster.

If two concurrent requests targeting the same logical ID (like user-123) arrive at different servers, the actor system ensures that:

Only one instance of the actor is created for that ID
All messages for that ID are routed to and handled by that actor, sequentially

This eliminates the need for locks or external coordination.

Real-World Comparison: DB vs Redis vs Actor

We compared three implementations of a synchronized counter increment:

db: Uses pessimistic DB locking
redis: Uses Redis-based distributed lock
actor: Uses spring-boot-starter-actor’s sharded actor system

Test Setup

3 Spring Boot instances (ports 8080, 8081, 8082)
Each instance received 3,000 concurrent POST requests (total: 9,000)
Each method was benchmarked independently using Apache Bench (ab)
Final value was retrieved via: GET /counter/{method}/{counterId}

Results Summary

Method	Counter Final Value	External Infra	Notes
DB Lock	9,000	MySQL	High DB load;
Redis	9,000	Redis	Required retry logic; slower throughput under load
Actor	9,000	None	High throughput, simple implementation

Although many requests technically "failed" at the HTTP layer (due to thin responses or benchmarking artifacts), the counter logic worked perfectly in all cases.

Why the Actor Model Is Effective

Using actors for synchronization offers several advantages:

Correctness: Each logical ID maps to a single actor that serializes access
Simplicity: No retry logic or lock expiration handling
Infrastructure-free: No Redis or lock coordination service needed
Scalability: Naturally distributed across nodes without contention

This model fits naturally into workloads where each entity (e.g., user, session, document) can be isolated and updated independently.

How to Get Started

Refer to the examples.

Summary

Feature	DB Lock	Redis Lock	Actor
External Infra Required	Yes	Yes	No
Lock Coordination Overhead	High	Medium	Low
Error-Prone Retry Logic	No	Yes	No
Throughput Under Load	Degrades	Moderate	Stable
Code Complexity	Low	Medium	Low
Horizontal Scalability	Limited	Good	Excellent

If you're building a distributed Spring Boot system and need reliable, low-latency synchronization without operational burden, consider giving the actor model a try.

Source Code

You can find the complete working example, including the benchmarking script, on GitHub:

🔗 spring-boot-starter-actor — Synchronization Example

Introducing Spring Boot Starter Actor: Building Stateful Applications with Spring Boot and Pekko

Kim Seon Woo — Sat, 10 May 2025 06:46:29 +0000

In the world of modern application development, stateless architectures have become the norm. They're scalable, easy to reason about, and fit well with cloud-native paradigms. But what happens when you need to build features that are inherently stateful? What if you're developing a real-time chat application, a game server, or a system that needs to track complex workflows?

The Stateful Challenge

As a Spring Boot developer, I've often found myself in this situation. Spring Boot excels at building REST APIs, microservices, and traditional web applications. However, when it comes to maintaining state across requests or implementing real-time features, things get complicated.

Consider these common challenges:

Managing state across requests: In a stateless architecture, you typically push state to an external database or cache. This works, but adds latency and complexity.
Building real-time applications: Applications like chat systems require maintaining connections and state for each user.
Handling complex workflows: Some business processes involve multiple steps and state transitions that are awkward to model in a stateless way.

The traditional solutions often involve:

Using Redis for pub/sub and state management
Implementing WebSocket handlers with custom state tracking
Creating complex state machines with external persistence

These approaches work, but they often feel like fighting against the framework rather than working with it.

Enter the Actor Model

The actor model is a programming paradigm that's particularly well-suited for building stateful, concurrent systems. In this model:

Actors are lightweight entities that encapsulate state and behavior
Actors communicate by sending messages to each other
Each actor processes messages one at a time, eliminating concurrency issues

Frameworks like Akka (and its Apache-licensed fork, Pekko) have implemented the actor model successfully, but integrating them with Spring Boot has always been challenging. The programming models feel different, and making them work together requires boilerplate code and careful consideration.

Bridging the Gap: Spring Boot Starter Actor

That's why I created Spring Boot Starter Actor, a library that seamlessly integrates the actor model with Spring Boot using Pekko. This library allows you to:

Auto-configure Pekko with Spring Boot
Create and manage actors using familiar Spring patterns
Leverage Spring's dependency injection within your actors
Run in both local and clustered modes
Build distributed, stateful applications with minimal boilerplate

How It Works

Let's look at a simple example of how you might use Spring Boot Starter Actor to build a stateful application.

First, add the dependency to your project:

implementation 'io.github.seonwkim:spring-boot-starter-actor:0.0.3'

Then, enable actor support in your application.yml:

spring:
  actor-enabled: true

Now, you can create an actor that maintains state:

@Component
public class HelloActor implements SpringActor {

    public interface Command {}

    public static class SayHello implements Command {
        public final ActorRef<String> replyTo;

        public SayHello(ActorRef<String> replyTo) {
            this.replyTo = replyTo;
        }
    }

    @Override
    public Class<?> commandClass() {
        return Command.class;
    }

    @Override
    public Behavior<Command> create(String id) {
        return Behaviors.setup(ctx -> new HelloActorBehavior(ctx, id).create());
    }

    private static class HelloActorBehavior {
        private final ActorContext<Command> ctx;
        private final String actorId;

        HelloActorBehavior(ActorContext<Command> ctx, String actorId) {
            this.ctx = ctx;
            this.actorId = actorId;
        }

        public Behavior<Command> create() {
            return Behaviors.receive(Command.class)
                            .onMessage(SayHello.class, this::onSayHello)
                            .build();
        }

        private Behavior<Command> onSayHello(SayHello msg) {
            ctx.getLog().info("Received SayHello for id={}", actorId);
            msg.replyTo.tell("Hello from actor " + actorId);
            return Behaviors.same();
        }
    }
}

And use it in a service:

@Service
public class HelloService {

    private final SpringActorRef<Command> helloActor;

    public HelloService(SpringActorSystem springActorSystem) {
        this.helloActor = springActorSystem.spawn(HelloActor.Command.class, "default")
                                           .toCompletableFuture()
                                           .join();
    }

    public Mono<String> hello() {
        return Mono.fromCompletionStage(helloActor.ask(HelloActor.SayHello::new, Duration.ofSeconds(3)));
    }
}

Real-World Example: Building a Chat Application

One of the most compelling use cases for the actor model is building real-time distributed chat applications. With Spring Boot Starter Actor, this becomes straightforward.

The library includes a complete chat example that demonstrates:

Chat Room Actors: Each chat room is a separate actor that maintains a list of connected users and broadcasts messages.
User Actors: Each connected user has an actor that receives events from chat rooms and forwards them to WebSocket sessions.
Spring Integration: Standard Spring services coordinate between WebSockets and the actor system.

Here's a simplified look at how a chat room actor might be implemented:

@Component
public class ChatRoomActor implements ShardedActor<ChatRoomActor.Command> {

    // Command and event definitions...

    @Override
    public Behavior<Command> create(EntityContext<Command> ctx) {
        return Behaviors.setup(context -> {
            final String roomId = ctx.getEntityId();
            return chatRoom(roomId, new HashMap<>());
        });
    }

    private Behavior<Command> chatRoom(String roomId, Map<String, ActorRef<ChatEvent>> connectedUsers) {
        return Behaviors.receive(Command.class)
                .onMessage(JoinRoom.class, msg -> {
                    // Add the user to connected users
                    connectedUsers.put(msg.userId, msg.userRef);

                    // Notify all users that a new user has joined
                    UserJoined event = new UserJoined(msg.userId, roomId);
                    broadcastEvent(connectedUsers, event);

                    return chatRoom(roomId, connectedUsers);
                })
                .onMessage(LeaveRoom.class, msg -> {
                    // Remove the user from connected users
                    connectedUsers.remove(msg.userId);

                    // Notify all users that a user has left
                    UserLeft event = new UserLeft(msg.userId, roomId);
                    broadcastEvent(connectedUsers, event);

                    return chatRoom(roomId, connectedUsers);
                })
                .onMessage(SendMessage.class, msg -> {
                    // Broadcast the message to all connected users
                    MessageReceived event = new MessageReceived(msg.userId, msg.message, roomId);
                    broadcastEvent(connectedUsers, event);

                    return Behaviors.same();
                })
                .build();
    }

    private void broadcastEvent(Map<String, ActorRef<ChatEvent>> connectedUsers, ChatEvent event) {
        connectedUsers.values().forEach(userRef -> userRef.tell(event));
    }
}

This approach provides several benefits:

Natural state management: The actor maintains the list of connected users and handles message broadcasting.
Concurrency safety: The actor processes one message at a time, eliminating race conditions.
Scalability: Using sharded actors, the chat rooms can be distributed across a cluster.
Fault tolerance: If a node fails, the actors can be recreated on other nodes.

Benefits of Using Spring Boot Starter Actor

By integrating the actor model with Spring Boot, this library offers several advantages:

Simplified state management: Actors naturally encapsulate state, making it easier to reason about and maintain.
Reduced boilerplate: The library handles the integration between Spring and Pekko, allowing you to focus on your business logic.
Familiar programming model: You can continue using Spring's dependency injection and other features while leveraging the actor model.
Scalability: The library supports both local and clustered modes, allowing your application to scale as needed.
Resilience: Actors provide supervision hierarchies and failure handling mechanisms that make your application more resilient.

Conclusion

Building stateful applications with Spring Boot doesn't have to be difficult. Spring Boot Starter Actor bridges the gap between Spring's ease of use and the actor model's natural approach to state management.

Whether you're building a chat application, a game server, or any system that requires maintaining state, this library provides a clean, intuitive way to do so while staying within the Spring ecosystem.

Give it a try for your next stateful application, and experience how the actor model can simplify your code and make your system more robust.

Check out the project on GitHub

I've created command line based todo manager using Rust

Kim Seon Woo — Sat, 10 Aug 2024 04:39:15 +0000

As a big fan of Alfred, I am interested in transitioning all of my work from using the mouse to using the keyboard shortcuts. One of the most frequently used but hard to transition to keyboard shortcuts was managing my todos. Previously, I would write todos in private Slack threads, but it required a lot of mouse movements. Although there were many alternatives like Todoist available, they did not seem to offer the features that I desired. As a developer, I decided to create my own solution by developing a todo-cli using Rust, a programming language that I have recently become a fan of.

I needed features to add, remove, mark as done and list todos(and timers for my pomodoro). And it had to be fast and ease of use. I decided to use Rust because it supports easy development of cli application and mostly, I loved the way the language works(error handling etc). This project is currently in development(adding features that I find useful or feel it's needed). If you need cli tool to manage your todo list, why not try using todo-cli?

Developed OPEN SOURCE to STOP PAYING!! for tools

Kim Seon Woo — Mon, 06 Nov 2023 22:10:06 +0000

With the advent of ChatGPT, developer productivity has greatly increased. Additionally, using services that effectively utilize ChatGPT can further maximize productivity.

However, a drawback of this kind of services is that the amount to be paid on a monthly basis is determined by the sum of "ChatGPT API Key Usage Fee" and "Service Usage Fee" requiring payment of more than $10 per month. While it is an amount that can be reasonably justified considering the enhanced productivity, I have decided that I cannot ignore the expenditure as I plan to continue using this service for a long time. As my job transition preparation has been completed recently and I have some spare time, I have decided to start developing a Chrome extension to effectively utilize ChatGPT.

Price Comparison

ChatGPT Plus: $20 per month

Sider + ChatGPT API KEY Usage: >= $100 per year

Free AI Sidebar: ChatGPT API Key Usage: Depends on usage

Introducing FREE AI Sidebar

When I search for information, I usually open multiple tabs in the Chrome browser and keep them active. However, when using ChatGPT for chatting, I prefer to open a separate tab for that. Sometimes, I accidentally close the ChatGPT tab or it gets hidden behind other tabs, causing inconvenience.

Fortunately, Chrome has a feature called the side panel. This side panel can be shared across all tabs in the same window. Therefore, even when switching tabs, the same side panel can be maintained. I started developing a Chrome extension with the belief that this can improve the inconvenience of using ChatGPT.

Main Features

The goal of the "Free AI Sidebar" project is as follows:

Provide a service that eliminates inconvenience and allows anyone to use it for free.

So the main goal is to eliminate the inconvenience encountered and provide the service for free, except for the API Key usage fee of chatGPT. Additionally, another goal is to develop highly usable software by encouraging various developers to participate. In order to achieve these objectives, the "Free AI Sidebar" project offers the following features.

Chatting

One of the basic features of ChatGPT is the chat function, which is one of the key features of the "Free AI Sidebar." as well.

Prompt Engineering

By utilizing Prompt Engineering, you can obtain more accurate answers from chatGPT. However, there is inconvenience in having to manually copy and paste the prompt every time you ask a question. To solve this problem, we have added a feature that automatically adds the prompt to the text entered by the user, and have also included a message template for this purpose.

By utilizing the message template feature, there is no need to repeatedly copy and paste the prompt as shown in the above picture.

Memorizing Previous Contexts

ChatGPT does not remember previous conversations. In other words, it cannot answer questions regarding information included in previous conversations.

When carrying on a conversation with someone, it is generally assumed that the other person remembers the context of the previous conversation. However, chatGPT has a limitation in that it cannot remember the previous context, which can give the feeling of sudden interruption in the conversation. To address this, we have added a feature that allows chatGPT to remember the previous context.

Generating Images

Sometimes, there are cases where random images need to be used, and by utilizing the API of chatGPT, it is possible to easily implement image generation functionality. Additionally, in the future, there are plans to add the ability to edit the generated images.

ETC

In addition, various features have been added including changing themes, changing AI models, and adjusting the temperature.

Open Source Contribution

When I first released it as open source, I was very worried about whether anyone would contribute, even just one person. However, my worries were unfounded as developers from various countries have contributed, which has motivated me to develop the project even harder.

Last Word

"Free AI Sidebar" is a free software that helps you make more efficient use of chatGPT. Some people use it as a tool to improve their productivity, while others use it as a means to contribute to open source. Feel free to use it and feedback is always welcome. In fact, user feedback is crucial. If you want to contribute, please feel free to register a GitHub issue and submit a pull request at any time.

Developing Open Source Prompt Engineering Tool

Kim Seon Woo — Sat, 28 Oct 2023 04:35:44 +0000

Recently, I started developing an open source tool that can ease prompt engineering. It's a chrome extension that you can use to interact with chatGPT API with more ease.

Why Another AI Tool

The reason behind I started this project was to STOP PAYING for AI tools. Most of the AI tools require the users to specify "user's chatGPT API key" AND "pay for the usage of their software". The cost isn't minor and there were missing features as well.

Because I wanted my project to be free of charge(of course you have to pay for the chatGPT API key usage), I open sourced the project. It has been released as a chrome extension as well.

Chrome extension

When installed

The main features are as follows:

Prompt engineering(Using default or custom templates)
Memorizing previous contexts so that users don't have to type previous context again and again
Selecting AI model
Selecting the temperature(how accurate the result should be)

There are still many features to develop such as

Add support for other AI(Google's Bard etc)
Support for many other chatGPT APIs(Image generation, fine tuning)
Enhancing Design
Adding test support(cypress)

It's open source and there's already been great contributors that contributed using their wonderful skills. Any feature requests or pull requests are WELCOMED!! So please, feel free to contribute.

Why should we pay for chrome extensions for AI stuff ?? 🧐🧐🧐

Kim Seon Woo — Wed, 27 Sep 2023 17:56:39 +0000

After chatGPT was released, I've been using chrome extensions such as "Sider".

Description of Sider chrome extension
How it looks when installed

It provides many features and lovely UI but the downside is... I have to pay for the usage even though I'm using api keys of my own(And I use Sider to ask questions only 😡)!! I looked for other chrome extensions but they also asked me to pay if I wanted to use more.

I know it's worth paying, but I didn't want to pay for it anymore. So I created a sidebar(which is a chrome extension) that can be used to call chatGPT APIs more easily. I am opening this into open source because I want it to have more features and used it freely by people who suffer from same problem as I did.

Please feel free to contribute to this NEW open source if you have interest. It's written in "Vue 3" and "Typescript". Minimal code has been written, so you'll find it easy to grasp the structure and ideas.

Features that has to be implemented are:

Allow users to select model
Allow users to stop streaming response from chatGPT
Better UI/UX design
Support AI other than chatGPT(Google bard etc)
... more ideas are welcome 😀

So please feel free to come and take a look, and if you want to contribute, just do it! Let's make something great together. Btw I'm planning to distribute it to chrome extension soon!

Chrome extension: https://chromewebstore.google.com/detail/free-ai-side-bar/bphjdepgpbodffelhponjdfpjdajghgc
GitHub link: https://github.com/seonwoo960000/ai-sidebar