MPHF + MVC
Model-View-Controller meets the Minimal Perfect Hash Function
Nov 2, 2025 ⋮ The Kireji Project ⋮ 3 min read
For a few years I've been working on a method of building a reactive, "part-based" web framework wherein each part (including nested parts) can store its runtime state in the routing system.
Some of my early attempts involved query parameters, base64-encoded JSON objects, domain-specific languages, and my own custom syntax. They all had the same problem - they failed to capitalize on the actual space available in URLs.
An incredible combinatorial explosion appears when you try to compute the number of unique URLs that can exist. Query params, JSON objects, domain-specific languages and custom syntax all encode redundant information and require extra characters for namespacing and delimiters that take up space in the URL. They also make handling nested part states a nightmare.
The Solution: MPHF
A minimal perfect hash function (MPHF) is a function that assigns a unique hash (like the kind that can be stored in a URL segment) to every element of a set. I realized that this was the kind of function I needed to access the full storage potential of URLs.
Implementing this was a challenge at first, especially for nested part states. To implement an MPHF, you must first be able to enumerate the entire set of configurations you're trying to hash. That means that my framework demands a piecewise-defined MPHF that computes the state space of each part under the hood. I eventually found an approach that I liked and published it as the MPHF Coordinate System on NPM and GitHub.
While the MPHF is part-based, it isn't a reactive web framework by itself. At some point along the way, I realized that the object-oriented data structure supporting my MPHF had a surprising amount in common with the MVC architecture I wanted to use to support the reactivity of my web framework. In fact, the two ended up sharing so many features that merging them was surprisingly straightforward.
This became a guiding principle for my framework: user interaction controllers double as subfunctions in the piecewise-defined MPHF and hashes double as easy-to-compare MVC models.
A part is an MVC controller and a hash range from 0 to k-1, where k is the cardinality of the part's state space. Like LEGO® bricks, parts assemble arbitrarily into larger parts. The result always provides a minimal perfect hash function over its state domain. Whether you assign a hash (which acts as the data model) to a controller or manipulate the controller directly (for example, via user interaction), views and hashes are always in sync.
I called the framework the Kireji Web Framework and reserved an NPM package and GitHub repo for it, but I haven't populated it yet. First, I'm refining the methods and developer experience by creating and publishing a series of demo apps.
The apps include this very notebook (more details in this note) and a surrounding ecosystem (read more in this note). You can get get a glimpse of part definition in the framework by looking at the Demo Ecosystem on GitHub and by exploring its parts and components on kireji.app.