Quizmania: A mobile client pubquiz app
It all started in 2009 during my time at university when a friend of mine had the idea to compete in a pub pentathlon, the (in german) “Kneipikaler Fünfkampf”. 12 friends, a bar in our student dorm, five disciplines and a whole weekend of fun (and maybe a beer or two). We started with the disciplines Pool Billard, Table Soccer, Poker, Dart and the grand finale with Ludo (a dice rolling game with almost no room for skill and tactics but therefore a lot of frustration).
Over the years we repeated this pub tournament and four of the five disciplines stayed the same but we soon exchanged Dart with a quiz format. We experimented with various quiz tournament formats: Buzzer questions, duels, group rounds — one time we even had a telephone joker because one of us couldn’t attend in person. In our last session in 2022 one friend programmed a very nice point scoring Excel sheet with graphics and animations. That was the moment I remembered that I am a software developer and I felt challenged to get rid of Excel and to build a multiplayer quiz app with point scoring, different question types, buzzer, timers and all that fancy stuff. I also hoped that a project like this would provide some topics to try out some new frameworks, technologies and software architectures.
With this and the following blog posts, I would like to take you on a journey through the design and development of my quiz app “Quizmania”, which challenges I faced and how I solved them. In this first part I’ll describe the overall business idea, the requirements and limitations of my first milestone and the basic system architecture, before going deeper into specific technical topics in the following articles.
At the beginning of every project, there is always a big brainstorming session with lots of ideas. Some ideas are amazing, some are challenging and some are quickly discarded again. After this initial brainstorming session, the next step is to prioritise the ideas. The best way to do this is to try to define a Minimum Viable Product, an MVP. Which features are absolutely necessary for my app to have a value, and which can be deferred to later milestones?
The MVP
The MVP setup of the quiz game is fairly simple. All participants as well as the quiz master are in the same room, each with a mobile device (usually a smartphone) plus a large screen that is visible to everyone.
- The large screen always shows the public game status for everyone, such as the current question, the correct answer or the overall ranking.
- The quiz master has a special screen with some administrative controls for the game (e.g. to close the current question or move on to the next question)
- The participants can answer the current question on their device and see the results of the current question
Of course any quiz is only as good as their questions. To allow for a wide variety of questions, the quiz should feature different kind of questions:
- Multiple choice questions. Simple and effective, a question with multiple possible answers to choose from, one is correct and is automatically scored by the game.
- Estimation questions. A question with a number as outcome. Whoever comes closest to the correct answer gets the points (automatically scored by the game). With a larger number of participants maybe even multiple participants in descending order.
- Free response questions. Things get more difficult. No answer options are given, just a textfield to enter the answer. This requires a fuzzy matching algorithm to eliminate small typos, capitalisation and whitespace errors when automatically scoring the answers. But the moderator should be able to overrule that matching algorithm afterwards.
- “Where is this?” questions. Even more difficult: The players don’t just have to know the correct answer to the question (a place on earth) but also have to find that place on a very simple map of the earth. Whoever is closest gets points (or multiple players there are many).
In addition all questions should have the following features:
- Time limit. The quiz master should be able to configure a time limit in which the players have to answer the questions.
- Buzzer mode. For some questions (such as multiple-choice questions or free-response questions), there should be an alternate buzzer mode where players hit the virtual buzzer and the fastest one gets to answer. This question mode is then judged manually by the moderator.
For an MVP it is also important to think about features which are not part of the first milestone and could be implemented in future iterations. For my MVP I decided to exclude the following features, since they are not mandatory for playing the game.
- Account management. For quick and uncomplicated access to the game we do not need a user and account management. Every participant chooses a guest username and can play the game.
- Rich question management. For the MVP it is necessary to define questions. But is is not important how they get into the game. So the first version will simply parse JSON files shipped directly with the app.
The Domain
If we look at the domain of such an interactive quiz game, we can see the user interactions (either by the quiz master or by the participants) as events that happen on the timeline of the game. And the core system as well as the other client devices need to react on these events in order to control the business logic or to display the occurred interactions. Therefore it is a good choice to also model the domain not only as the entities and their relations but also as domain events describing the flow of the game.
- A game is created by a GameCreatedEvent containing the setup of the questions to be asked, the game mode, the number of players and the timings.
- Players can then join (PlayerAddedEvent) or leave (PlayerRemovedEvent) the game until the quizmaster starts the game with the first question asked.
- In normal mode, while the question is not closed by the timer players can answer the question. This answer can be overridden by the quiz master before he scores the question and proceeds with the next one.
- When in buzzer mode, each player can hit the buzzer and the game will automatically select the fastest player (QuestionBuzzerWonEvent) to answer the question. This answer is then accepted or rejected by the quiz master (resulting in QuestionAnswerdedEvent and QuestionRatedEvent).
The architecture
With the domain described purely with events, a quiz game can be defined as a sequential stream of these domain events and the current state of a game can always be reconstructed from these events. This is called event sourcing. Also in such an event-sourced architecture it has advantages to separate the event producing parts (the Command side) from the event consuming parts (the Query side) of the system. To do this, I adapted the CQRS/ES architecture. As technical framework I chose the Axon Framework together with the Axon Enterprise Server since it is a very powerful JVM based CQRS/ES framework.
The backend consists of two independent domain modules:
- Game: The core module. This module is built with CQRS/ES architecture, that separates the reading side from the writing domain logic. The game domain module contains the business logic to process incoming commands into events, which are then stored in Axon’s event store. This module contains only the command model, the read models are located closer to the frontend.
- Question: Manages the questions and question sets. To keep the architecture simple, this module is not designed event-driven, but is designed as a simple service that reads the available questions from JSON files into the memory.
Right between the backend and the frontend we have the backend-for-frontend. This one serves as web API specifically tailored for the frontend. It provides:
- An HTTP-API (CommandController) to pass commands to Axon’s CommandGateway to the backend.
- An EventDispatcher to send all occurring game events to the corresponding player devices.
- Some lightweight APIs to list open games or available question sets to create new games. These are backed by small event-sourced projections and contain only the data necessary to fulfil the API.
Outlook
In this first blog post I gave you an overview of my business idea, the requirements, the developed business domain and the overall system architecture. In the following parts I will dive deeper into selected technical or architectural aspects, especially focussed on using event-sourcing and the Axon Framework.
Since the MVP of the Quizmania app still lacks features like account management and advanced question management (JSON files need to be deployed along with the app), I haven’t provided a running live version of it yet, but the whole source code is already available on Github with instructions on how to run it locally.
Stay tuned for the next part where I will talk about websocket based event sourcing and building CQRS read models in a React based frontend.
