Building Systems Check: A Programming Puzzle Game

For the longest time, I have been obsessed with programming puzzles. I first discovered this obsession in university while learning programming for the first time, it became something that I really loved to do. Even "studying" just became sitting on the couch with my laptop writing code to do something, and you could even do it while drinking a beer, what's not to love? I soon discovered Project Euler and later Advent of Code. The latter has become an almost sacred ritual for me in December.

No longer content with simply solving programming puzzles, I wanted to take a crack at starting my own, hence systemscheck.dev was born. In this article I'm going to give a brief overview of how it works and how I built it.

The basics

Firstly, to address a few people's initial reaction, yes, you do need to make an account to submit your answers. Also, yes, you have to provide an email address to create an account. I do plan to enable users to sign up with GitHub or Google etc., but I haven't had the time to build this out yet. As for having to have an account in the first place, it makes more sense when you know that each user gets their own unique input set of data for each puzzle. This is deterministically generated from a seed that is generated for the user when their account is created. This seed is used to both generate their input and validate their answer via the generators and solvers built into the app. For this reason, I need to maintain an account for each user. I do not, however, collect any other data on the users, and I have no plans to ever share or sell any information I have to any third party.

The basic flow of using the app is fairly simple: when a user lands on a puzzle for the first time, in the background I generate their unique input and store it in my database. The user can then download it and use it to solve the puzzle. At solution time, the user submits their answer and it is verified by a solver running on the server. If the answer is correct, the puzzle is marked as solved and its next part is unlocked. It might be surprising to learn, but everything is done in-line in requests. Generation of inputs and solving of problems runs live on the server in the request paths, which means each generator and solver has to be able to run extremely quickly. I am a huge fan of Rust, and it lends itself well to this application by being both very performant and safe.

How do you go about designing puzzles?

This part is tricky. The sci-fi setting provides lots of fuel for this; being a big sci-fi fan myself, I have a near endless mental collection of stuff to pull from for the setting and flavour text for the puzzles. The sci-fi setting also means I can more or less do what I want, nothing is off the table really, that helps! Aside from that, the technical aspects of what the puzzle is actually trying to solve mostly comes from my experience of doing lots of these kind of puzzles and being a professional software developer for many years. I am also using this as a vehicle to learn new things myself, including CS theory. If I happen upon a new algorithm I haven't seen before or a novel concept, I will end up building a puzzle around it.

The deterministic side of the solvers and generators is one of the biggest challenges, along with creating reliable distributions of randomness for each input. Once a puzzle is being generated consistently and the solver is solving it with no bugs, there comes a lot of hyperparameter tuning for each puzzle. In a grid-based puzzle with a maze, for example, it might be the percentage of filled vs empty nodes, or in a graph puzzle it might be the average number of connected edges. These can massively impact whether a problem is easy to solve or hard to solve, or even whether it is possible at all.

What tech are you using?

The application runs in a Linux container running in Azure (which is where all the rest of the software I manage happens to run—legacy, not deliberate). The app itself is a Rust application written in Rocket with a simple Handlebars frontend. I am using Postgres as the database and Diesel as my ORM layer. One of the things I wanted to do with this application was to run a full end-to-end Rust application with a database and to try out rhai-console (which I also wrote) as the dev tooling layer. So far I am really loving it and it's coming in very handy!

What if you run into a bug in a solver or generator?

Well, this hasn't happened yet, but it could! I have a pretty aggressive testing setup, and in the development of each puzzle I spend a lot of time trying to break it as I generate inputs and figure out the heuristics of the generators and the constraints of the input data. There is a class of bug which would be fixed by updating the problem text. For example, if a problem is stated unclearly or in a misleading way, a fix might be to update the problem text to match what is really going on.

A much worse scenario is one in which my solver or generator has a fundamental bug and it turns out many people can't get a correct answer or there exist many inputs that are unsolvable. Were this to be the case, I'd have to diagnose the issue; I'd probably have to unpublish the puzzle and spend time figuring it out. If I managed to fix it, I would likely wipe all submitted results and republish it. Given this isn't exactly a high-stakes thing, I don't think it's the end of the world to do this.

What's Next?

The main thing will be more puzzles. At the moment I only have five puzzles, and they are relatively non-trivial to write and test. I haven't committed to any cadence with them, but the plan would be to write more and more and build up a large collection over time. On a more practical note, some user analytics to show progress and completion rates of puzzles might be cool, as well as the ability to log in using GitHub or Google, and perhaps an API for submissions (maybe an SDK or two, who knows?). More puzzles is the main focus, however. I really hope you enjoy. Any and all feedback is welcome!

Keep on making things

-Ian