Why should crossword enthusiasts always solve a puzzle on their own? Wouldn’t it be much more fun and enjoyable to solve a crossword online with others? Let us introduce the Code Camp 2022 project “X-Buddies”.

Code Camp Project X-Buddies

Two times a year, Karakun developers meet in the Swiss Alps to experiment with new technologies. The crossword lovers among us decided to work on project X-Buddies.

For selecting the framework and technologies, the project group started defining functional and non-functional requirements:

• Users should see which and how many users are actively solving a crossword.
• The look and feel of the crossword should be similar to paper versions.
• The display should update itself as soon as another user types a solution into the crossword puzzle.
• A success message should appear to all users upon completion of the crossword.
• Use ServerSentEvents (see https://en.wikipedia.org/wiki/Server-sent_events ) for notification messages between the server and the clients.
• Use Spring-Boot (see https://spring.io/projects/spring-boot) for the server.
• Use React (see https://reactjs.org/) for the client.
• Pack the application as a Docker container to move it to the Karakun cluster.

Step-by-step introduction to the development of X-Buddies

Evaluation of a React-based crossword editor

With https://github.com/JaredReisinger/react-crossword, we found a flexible, responsive, and easy-to-use crossword component for React apps. We quickly realised that the open-source editor is very elegant and complete for solving crosswords by individuals. However, our ambition was to connect a team of friends to solve a puzzle simultaneously.

Therefore, we needed the ability to send all occurring events, such as selecting a cell or typing a letter in a cell, to all the other crossword buddies to see the changes in real time. In other words: the client sends an interaction-based event to the server and forwards this event to all clients via Server-Sent-Events (SSE).

Server part for event handling

To enable several clients to interact on a single crossword, we needed a server that distributes the incoming events to the recipients via SSE events. For this purpose, we set up a simple Spring-Boot server. Clients can register for a crossword via the server API. Upon successful registration, the server sends an SSE event to inform all registered clients about the new buddy. When solving the crossword, the server accepts events from a player and propagates them to all buddies.

SSE-Event Web-API

To bind a client to the server, the client starts the communication by sending a request to the server. Upon establishing the connection, you can read the message in the Devtools of your browser. The content type of the response is ‘text/event-stream’. You can see them in the tab ‘EventStream’. Such a message could look like this:

This example signals that the cell with the mentioned coordinates has received the value ‘F’. The user who set this cell to the value ‘F’ is “Fred”.

Another example could be:

This message signals all clients that someone has joined or left the crossword. A client can now react to such a message according to the type and make the necessary adjustments.

Using addEventListener('type', (e)=>{...}) on an EventSource, clients can register for different event types depending on individual use cases. Want to provide a chat window on another device so that users can focus on the crossword? No problem! Feel free to choose the event type you need for each client.

Lessons learned

After some intense hours of trying things out and searching the net for other examples and documentation, we finally reached a stable level. At the end of the Code Camp, we could play a few rounds of crossword puzzles with all participants. Visit https://xbuddies-demo.k8s.karakun.com in case you want to test it.

From a technical point of view, there are also a few things that are worth mentioning here. One of them is that communication that goes through an SSE channel always starts on the server side. One can already think of this because of the name “Server-Sent-Events”. But this also means that communication with the server has to happen differently. And you don’t need any further dependencies to use SSE in your browser - all common browsers already support SSE.

Last but not least

We had a lot of fun experimenting with React and the crossword component by Jared Reisinger. Thanks a lot to every Karakunie who participated.