Algorithy Documentation

This is the complete, from-zero guide to Algorithy, the browser game that teaches algorithms by letting you drag blocks, press Run, and watch a little mouse walk to its cheese. It explains what the app is, how every piece of it works, how it is built, how it is tested, and why it makes the choices it makes. Nothing important is left out on purpose.

Who this guide is for

• Players and curious people - start with What is Algorithy, which needs no programming knowledge at all.
• Developers who want to understand or change the code - every page after that, especially Technology stack, The program tree, Simulation and Validation.
• Future-me, the project's own author, and anyone reviewing this as a master's project - the Testing and Known issues pages say honestly what is proven and what is not.

How to read it

The pages are ordered roughly from "what is this" to "how is it built", then "how do we know it works". Every page links forward and backward, so you can read straight through or jump around.

1. What is Algorithy - the idea, in plain words.
2. Getting started - run it, build it, find your way around.
3. Technology stack - every tool and why it was chosen.
4. App shell and routing - entry points, providers, URLs.
5. Levels overview - all 20 levels and what each one teaches.
6. Level schema - the exact JSON contract, field by field.
7. Blocks - the actions, the palette, and how blocks look.
8. The program tree - the data structure behind your program.
9. Simulation - how Run actually executes your program.
10. Cycles and optimization - what "cycles" mean and why they are counted.
11. Drag and drop - the pointer-based dragging system.
12. The playground - the grid, its geometry, textures and entities.
13. Design system - tokens, block colours, terrain themes, skins.
14. Persistence - what is saved in the browser and how it is validated on load.
15. Validation - why this app validates data it wrote itself.
16. Internationalization - English and Serbian, done properly.
17. Code export - turning the program into C, Python and JavaScript.
18. Accessibility - what the app does for everyone.
19. Testing - every test and what it proves.
20. This documentation - how these pages are built and served.
21. Known issues and gaps - honest inventory of what is unfinished.
22. Glossary - every term in one place.
23. Level builder - make and share your own levels.

The one-paragraph version

Algorithy is a browser game modeled on Code.org's Hour of Code maze. You drag Scratch-like blocks (move forward, turn, repeat, if, while, switch) into a program, press Run, and watch a mouse walk a grid toward a piece of cheese. Twenty levels ramp from a single move to icy slides, lava, holes and nested control flow. There is no server API: the game runs entirely in your browser, with Bun, TypeScript, hono/jsx, valibot and Tailwind CSS v4 under the hood. Every level file, every saved program and every piece of storage is validated with schemas before it is trusted, and the whole thing is covered by tests that run the actual game logic, not just toy cases.