{"id":15034764,"url":"https://github.com/haraj-backend/hex-monscape","last_synced_at":"2026-03-27T02:42:51.745Z","repository":{"id":179877987,"uuid":"460872929","full_name":"Haraj-backend/hex-monscape","owner":"Haraj-backend","description":"Build a simple turn-based game to learn how to write production code using Hexagonal Architecture. Onboarding reference for Haraj Solutions Team.","archived":false,"fork":false,"pushed_at":"2024-07-18T03:13:29.000Z","size":7274,"stargazers_count":75,"open_issues_count":2,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-09T22:52:25.809Z","etag":null,"topics":["getting-started","go","golang-examples","hexagonal-architecture","learning-resources","onboarding","reference-implementation","saudi-arabia","vue3","web-game"],"latest_commit_sha":null,"homepage":"https://hex-monscape.haraj.app","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Haraj-backend.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-02-18T13:55:23.000Z","updated_at":"2025-01-16T02:52:16.000Z","dependencies_parsed_at":"2024-01-05T21:47:05.755Z","dependency_job_id":null,"html_url":"https://github.com/Haraj-backend/hex-monscape","commit_stats":null,"previous_names":["haraj-backend/hex-monscape"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haraj-backend%2Fhex-monscape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haraj-backend%2Fhex-monscape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haraj-backend%2Fhex-monscape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haraj-backend%2Fhex-monscape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Haraj-backend","download_url":"https://codeload.github.com/Haraj-backend/hex-monscape/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125641,"owners_count":21051766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["getting-started","go","golang-examples","hexagonal-architecture","learning-resources","onboarding","reference-implementation","saudi-arabia","vue3","web-game"],"created_at":"2024-09-24T20:26:15.321Z","updated_at":"2026-03-27T02:42:51.697Z","avatar_url":"https://github.com/Haraj-backend.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hex Monscape [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/Haraj-backend/hex-monscape.svg)](https://pkg.go.dev/github.com/Haraj-backend/hex-monscape)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Haraj-backend/hex-monscape)](https://goreportcard.com/report/github.com/Haraj-backend/hex-monscape)\n[![Coverage Status](https://coveralls.io/repos/github/Haraj-backend/hex-monscape/badge.svg?branch=master\u0026refresh_token=4fff75f6-460c-48d9-b532-896e2aadbc5a)](https://coveralls.io/github/Haraj-backend/hex-monscape?branch=master)\n\n\n![hex_monscape_preview](./docs/images/readme-preview-cc14f47c-8a2a-41ce-b442-bdd99b4807ca.png)\n\n`Hex Monscape` is a simple turn-based game to make Haraj Solutions Team onboarding more fun.\n\nIn the game code, you can find the team's secret technique in writing production code for [Haraj](https://haraj.com.sa) services that help serve millions of people daily in Saudi Arabia despite only having a handful of team members. 🥷🏻💥\n\nThe secret technique actually lies in the architecture we choose for these services: [Hexagonal Architecture](./docs/reference/hex-architecture.md).\n\nBy using this remarkable architecture, not only can we speed up the development process of these services but also make them **maintainable by the whole team**. This is why even though our team is small, we can still do our job properly without losing good sleep at night. 🤣\n\nThe game was created using [Golang](https://go.dev/) \u0026 [Vue 3](https://vuejs.org/). To learn how we apply [Hexagonal Architecture](./docs/reference/hex-architecture.md) to the game, please refer to [this doc](./docs/reference/hex-architecture.md).\n\nTo start playing the game, please refer to [How to Run The Game](#how-to-run-the-game) section.\n\n\u003e **Note:**\n\u003e\n\u003e Many people got interested in software engineering because of games. So using them to exchange knowledge within our team seems like a fun idea. This is why we created this project. 😃\n\u003e\n\u003e Even though we are using Golang to implement [Hexagonal Architecture](./docs/reference/hex-architecture.md) in this repo, the architecture itself is language agnostic. So we can also apply it to other languages such as PHP, Typescript, \u0026 Python.\n\n## Background Story\n\nOne of the most significant engineering issues in [Haraj](https://haraj.com.sa) is code maintainability.\n\nWhat is code maintainability? Essentially it is the ability of a codebase to be easily maintained by others. So when a developer can no longer maintain the codebase, other developers could easily take over the code they left behind.\n\nAs you may already know, Haraj engineering team is small. So in our early days, we gave project ownership to the developer who started the project. This developer will be responsible for every aspect of the project development: writing the code, deploying it to production, \u0026 maintaining it.\n\nAt that time, we did not set common standards for writing code for those projects. So every developer writes code based on their style \u0026 preferences with almost no consideration for other developers.\n\nThis situation created a lot of frustration in the team. Since the project authors were the only ones who understood the code they wrote, they were also the only ones who could maintain it. So when they were on vacation or sick, the project they owned would be stuck until they came back because no one else dared to touch it. 😢\n\nOn the other hand, our developers will stay long before they leave (`~5 years`). So when a developer leaves the team, they usually own several valuable projects for the Haraj business. The problem is that since the projects were written in the developer's style, no team member could easily take over those projects. 😅\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=512 src=\"./docs/reference/assets/memes/code-maintainability-this-is-fine.jpg\" alt=\"Code Maintainability? This is fine.\"\u003e\n\u003c/p\u003e\n\nThis is why code maintainability grows into such a big issue in Haraj, and the solution to prevent more of this is to set up common standards on how to write code in Haraj projects. This is where [Hexagonal Architecture](./docs/reference/hex-architecture.md) comes into play.\n\n## Game Design\n\nIn the game you will play as a `10 years` old monster hunter that dreams to become the very best. In order to reach that, you need to make journey together with your monster partner to seek `3` strong wild monsters and kick them in the butt. 💥💪🏻\n\nThe game scenario is pretty simple, player just need to choose monster partner then won battle for `3` times to beat the game. After that player may choose to end the game or continue playing.\n\nHere is the flowchart for the game scenario:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./docs/reference/assets/game-flow.drawio.svg\" alt=\"Game Flow\" height=\"400\" /\u003e\n\u003c/p\u003e\n\nHere is the flowchart for each battle in the game:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./docs/reference/assets/battle-flow.drawio.svg\" alt=\"Battle Flow\" height=\"400\" /\u003e\n\u003c/p\u003e\n\nTo see the REST API specification for this game, please see [this doc](./docs/api/rest-api.md).\n\n## How to Run The Game\n\nYou can try out this game online by visiting this URL: https://hex-monscape.haraj.app.\n\nIf you want to run the game locally, make sure following applications already installed in your machine:\n\n- [Docker](https://docs.docker.com/get-docker/) `v20.10.23` or above =\u003e this will also install Docker Compose `v2.15.1`\n- [make](https://linuxhint.com/make-command-linux/) =\u003e to execute the scripts for running the project defined in [Makefile](./Makefile)\n\nAfter that use this command to run the game:\n\n```bash\n\u003e make run\n```\n\nWait for a moment until you see message like this:\n\n```bash\nrest-memory-client-1  | yarn run v1.22.19\nrest-memory-client-1  | $ vite --host --port 8161\nrest-memory-client-1  |\nrest-memory-client-1  |   vite v2.8.4 dev server running at:\nrest-memory-client-1  |\nrest-memory-client-1  |   \u003e Local:    http://localhost:8161/\nrest-memory-client-1  |   \u003e Network:  http://172.31.0.3:8161/\nrest-memory-client-1  |\nrest-memory-client-1  |   ready in 151ms.\n```\n\nAfter that you could access the game by visiting this URL: http://localhost:8161.\n\n## Multiple Server Variants\n\nActually there are `3` variants of game server in this project:\n\n- Server using In-Memory storage =\u003e run command: `make run-rest-memory`\n- Server using DynamoDB storage =\u003e run command: `make run-rest-dynamodb`\n- Server using MySQL storage =\u003e run command: `make run-rest-mysql`\n\nAll of them serve the same game, the only difference is the place where they store the game data.\n\nFor details on these commands, please refer to [this Makefile](./Makefile).\n\n\u003e **Note:**\n\u003e\n\u003e When we use [Hexagonal Architecture](./docs/reference/hex-architecture.md) to build an application, it is quite easy to swap its infrastructure code with another technologies.\n\u003e\n\u003e So for example, if initially we used in-memory storage to store our data, we could easily swap it with MySQL storage or something else. This is why in this project we provide `3` variants of game server for you, this is to demonstrate exactly this point.\n\n## Attribution\n\nThe monster characters used in this project is designed by [Freepik](http://www.freepik.com). To be exact we are using [this asset](https://www.freepik.com/free-vector/set-funny-monsters-hand-drawn-style_1933029.htm).\n\nThe memes used in this project is generated using [this meme generator](https://imgflip.com/memegenerator).\n\nThe project layout used in this project is inspired by [this repo](https://github.com/golang-standards/project-layout).\n\nThe font used in the words `\"Hex Monscape\"` on the Hex Monscape logo is [Lexend Deca](https://fonts.google.com/specimen/Lexend+Deca?preview.text=HEX%20MONSCAPE\u0026preview.text_type=custom\u0026category=Sans+Serif,Display) from Google Fonts.\n\n## Contributing\n\nGot more idea on how to make this learning project more fun? Or maybe you found something that can be improved from this project?\n\nFeel free to contribute to this repo by opening issue or creating a pull request! 😃\n\n## Core Maintainers\n\nGot any questions related to this project? Feel free to contact us:\n\n- [Riandy Rahman Nugraha (@riandyrn)](https://github.com/riandyrn)\n- [Muhammad Iskandar Dzulqornain (@isdzulqor)](https://github.com/isdzulqor)\n- [Muhammad Izzuddin al Fikri (@knightazura)](https://github.com/knightazura)\n- [Alfat Saputra Harun (@harunalfat)](https://github.com/harunalfat)\n- [Ilham Syahid Syamsudin (@ilhamsyahids)](https://github.com/ilhamsyahids)\n\nWe will be very happy to help you! 🚀\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaj-backend%2Fhex-monscape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharaj-backend%2Fhex-monscape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaj-backend%2Fhex-monscape/lists"}