MPHF + MVC

Model-View-Controller meets the Minimal Perfect Hash Function

Posted Nov 2, 2025 | ~3 minute read

For a few years I've been working on a method of building a reactive, component-based web framework wherein each component (including nested components) 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 component 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 component 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 component-based MPHF that computes the state space of each component 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 component-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.

I dubbed these dual purpose components "parts". A part is a reusable component with an MVC controller and a hash range from 0 to k-1, where k is the cardinality of the component's state space. Like LEGO® bricks, parts assemble arbitrarily into larger components. 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 applications.

The applications include this very notebook (more details in this note) and a surrounding app ecosystem (read more in this note). You can get get a glimpse of component definition in the framework by looking at the Demo App Ecosystem on GitHub and by exploring its components on kireji.app.