- Introduction
- Features
- Architecture
- API documentation
- How to build & How to run
- Dependencies
- Support
- Future goals
Kalaha is a game in the mancala family invented in the United States by William Julius Champion, Jr. in 1940. This game is sometimes also called "Kalahari", possibly by false etymology from the Kalahari desert in Namibia.
Rules are as below:
- At the beginning of the game, six seeds are placed in each house. This is the traditional method.
- Each player controls the six houses and their seeds on the player's side of the board. The player's score is the number of seeds in the store to their right.
- Players take turns sowing their seeds. On a turn, the player removes all seeds from one of the houses under their control. Moving counter-clockwise, the player drops one seed in each house in turn, including the player's own store but not their opponent's.
- If the last sown seed lands in an empty house owned by the player, and the opposite house contains seeds, both the last seed and the opposite seeds are captured and placed into the player's store.
- If the last sown seed lands in the player's store, the player gets an additional move. There is no limit on the number of moves a player can make in their turn.
- When one player no longer has any seeds in any of their houses, the game ends. The other player moves all remaining seeds to their store, and the player with the most seeds in their store wins.
This application features a UI where two players can take their turns and play. The player doesn't have to care about losing the state of the game, because application saves state after every move. So, by just having game ID, player can return and continue their game.
The application consists of two main and one auxiliary module:
- kalaha-core - Core library to provide gameplay experience (auxiliary)
- ms-kalaha-api - MicroService to provide backend/API
- mf-kalaha-ui - MicroFrontend to provide frontend/UI
kalaha-core library is the main provider of the gameplay logic. It's a complete package with logic and tests. The implementation is done using Java. The tests are written using Spock Framework on Groovy.
ms-kalaha-api is the main provider for the backend operations. It is designed to use any core library and database. In other words, it's not coupled with the core library used inside. In this case, the implementation uses kalaha-core library and MongoDB. Because of loose coupling any other core library can be easily integrated without needing much refactor. The microservice also provides presentation layer using REST API. The implementation is done using Spring Boot on Java. The tests are written using Spock Framework on Groovy.
mf-kalaha-ui is the main provider for the frontend operations. The implementation is done using HTML, CSS and vanilla Javascript.
ℹ️ UI could have been implemented using other technologies such as Angular, React, Vue or even Vaadin with Spring. However, as I'm a backend engineer and not an expert in the frontend area, I decided to keep it simple and easy to code.
⚠️ You need Java 17, Docker and Docker Compose installed to run the all-in-one setup.
- Start:
$ ./start.sh- Access:
- Stop:
$ ./stop.sh- Cleanup:
⚠️ Do this step only if you want to reset application data. This script is designed to delete all docker volumes and images created in Docker, so it will delete all the previous data and you'll start from scratch.
$ ./reset.shProjects:
Technologies:
If you need support, please, get in touch with rzaaeeff.
- Introduce auth mechanism (a separate auth adapter of some IDP) and use it to determine Player IDs for authorization.
- When the load increases, to save up on the DB ops, introduce distributed caching layer with Redis (using write-back strategy).
- Refactor frontend to use a better alternative, possible one these frameworks: React, Angular, Vue.
After future goals have been reached, solution design would look like this: