Your Stack Is Colonizing Itself — And You're Paying the Cognitive Tax

stefanos.chr — Fri, 08 May 2026 11:32:04 +0000

Returning Each Layer to Its Rightful Place: The Architecture Behind Mycelium

There is a particular kind of fatigue that accumulates quietly. Not the fatigue of a hard sprint, but the fatigue of maintenance — of holding three abstraction layers in your head to understand one screen, of debugging a mutation that is half in a React hook, half in a REST endpoint, and half in a database trigger. Of explaining to a customer why a small change requires a deployment. Of waking up at 2am because you cannot remember whether the source of truth for that field is the cache, the API response, or the database row.

This post is about a framework called Mycelium, and the architectural philosophy behind it. It is not a benchmark post. It is not a "we're faster than X" post. It is written for developers who have started to suspect that the complexity they are managing is not inherent to their domain — it is accidental, and it was introduced by their tools.

The Problem Is Colonization

Every layer in the modern web stack has a tendency to colonize its neighbors.

SQL gets colonized by ORMs that think in objects rather than sets, flattening the most powerful query language ever built into a thin object-mapping veneer. Templates get colonized by JavaScript frameworks that treat the DOM as a reactive state machine, importing the entire rendering model of the server into the browser. The server gets colonized by the client, which expects not HTML but JSON, making the server a dumb data pipe and reassigning the job of "application" to a JavaScript bundle.

The result is that every layer is doing someone else's job badly.

Proterative design is the principle that frames the alternative. The word comes from the Latin proterare — returning things to their original, rightful place. Applied to a web system, it means:

SQL thinks in sets. Joins, aggregations, mutations, durable truth. This is what it was built for.
Templates render structure and behavior. They receive a payload and produce HTML. That is their entire job.
The server orchestrates request flow. Thin, explicit, no magic.
The network moves messages. Transport is transport. It is not storage.

This is not a new idea. It is, in fact, the oldest correct idea in web development. What is new is building a framework that enforces it as a structural constraint rather than a convention that slowly erodes under deadline pressure.

Who This Is For

Mycelium is not designed for teams building the next Figma or Linear. It is designed for a specific kind of developer — one who is also, to varying degrees, a systems thinker, a domain expert, a customer success rep, and an operator.

The target is the developer who works with SMBs: custom ERP tools, booking systems, operational dashboards, internal tooling for businesses that run on human expertise rather than viral growth. Businesses where the most valuable conversations happen not in a Jira ticket but sitting across from a warehouse manager, a hotel owner, or a clinic administrator who is explaining how their world actually works.

These developers need to move fast, stay close to the domain, and — critically — sleep at night. The codebase they ship is also the codebase they will maintain, extend, and explain to a customer who wants one small change in eighteen months.

Complexity is not their friend. Cognitive overhead is not a sign of seriousness. The simplest system that correctly models the domain is the professional result.

Filesystem Routing: The App as a Readable Artifact

In Mycelium, routes are not registered. They are discovered.

The filesystem is the routing table. An app's logic lives under:

apps_logic/<app>/routes/

Mycelium's discover_routes() function walks this directory and reads Python handlers, HTML templates, and WebSocket endpoints as first-class route definitions. No decorator registration, no central urls.py, no route array to maintain in parallel with the file that actually handles the request.

This means that opening the filesystem is reading the application. A new developer — or your future self at 11pm — can navigate the project tree and understand its structure without running the application or reading framework documentation.

Locality of behavior, the principle championed by htmx's Carson Gross, applies here at the filesystem level: the handler, the template, and the metadata for a route all live together, in one place, with no indirection.

At startup, sync_app_routes() upserts discovered routes into the app_routes table and deletes stale rows. The database becomes a verified mirror of the filesystem. If the two disagree, the framework tells you explicitly.

The `route_metadata.json`: Behavior as Data

Every route's behavior is declared in a single file:

apps_logic/<app>/route_metadata.json

A typical entry looks like this:

{
  "/cashier/dashboard": {
    "GET": {
      "db_queries": ["cRud_bl_cashier_dashboard"],
      "mqtt_reads": ["terminal_status", "payments_latest"],
      "redis_reads": ["session_state"],
      "roles": ["cashier", "manager"]
    },
    "POST": {
      "db_queries": ["cUd_bl_cashier_post_payment"],
      "redis_ops": {
        "post_db": [
          {
            "action": "set",
            "alias": "payments_latest",
            "value": "{'state': 'posted'}",
            "ttl_seconds": 1800
          }
        ]
      },
      "roles": ["cashier"]
    }
  }
}

This is not configuration in the negative sense — not XML-era ceremony. It is a declaration of intent. Reading this file answers the questions that matter when you return to a route after six months:

What data does this route need?
Where does that data come from?
Who is allowed to call it, and how?
What side effects does a POST trigger, and in what order?

The framework validates this file at sync time. Unknown endpoints are rejected. Missing discovered routes are auto-added. MQTT and Redis aliases are validated against their manifest files. The normalized result is written back. The metadata file cannot lie.

This is proterative at the metadata level: behavior belongs to the route, not scattered across middleware stacks, decorator chains, or client-side route guards.

Transport Is Not Truth: MQTT and Redis in Their Rightful Place

Two common mistakes in complex web systems:

Using a message broker as if it were a database.
Using a cache as if it were a source of truth.

Mycelium makes both mistakes structurally impossible.

MQTT is available as a transport primitive. A payment terminal publishes a retained message on a topic. A cashier dashboard renders that latest signal at page load. That is a legitimate use of MQTT — movement of state that is useful now but not durably significant. The broker is for movement. When that payment needs to be reported, audited, or reconciled, it is written to Postgres.

Redis is available as an explicit keyed state layer. Routes declare their reads and writes through aliases. Templates receive Redis results in payload["redis_results"] — explicitly, not magically. Redis is never the only proof that a business mutation happened.

Both transports are declared in their own alias manifests:

apps_logic/<app>/routes/mqtt/*.json
apps_logic/<app>/routes/redis/*.json

And referenced by alias in route_metadata.json, not by raw topic strings or key names. The runtime resolves aliases to tenant-safe topics and keys. Templates never see infrastructure.

The rule is simple and applies everywhere:

Broker for movement.
Redis for explicit keyed state.
Postgres for truth.
Templates render payload.

Metadminer: Situational Awareness in Production

A framework that enforces structural constraints needs a way to surface those constraints visibly. That is the role of Metadminer.

Metadminer is not a debugger and not a log viewer. It is a system legibility layer. Its purpose is to answer the question every experienced developer asks before touching production code: what is the system actually doing right now, and does it match what I believe it is doing?

In practice, this means Metadminer surfaces:

The route tree — every discovered and synced route across all apps, with their current sync status.
Endpoint metadata — the validated route_metadata.json for any endpoint, normalized and readable, alongside its role constraints and query bindings.
The DB query catalog — every SQL function registered across apps, with its operation type, payload contract, and last-sync timestamp.
Transport alias maps — resolved MQTT topics and Redis keys per tenant, per app, per route.
Cache state — what is warm, what is stale, what would be reloaded on the next request.
Drift indicators — explicit flags when filesystem state, database catalogs, and runtime caches have diverged.

The intended user experience is this: a developer inheriting a Mycelium app, or returning to one after six months, should be able to open Metadminer and, within five minutes, understand the entire system without reading source code. Every query, every route, every permission, every transport alias is visible and traceable.

This is situational awareness in the same sense a pilot uses the term: not an alarm system, but a persistent, reliable picture of the system's state against which anomalies become immediately visible.

The Developer Experience This Is Designed For

Mycelium is opinionated about the relationship between a developer and their customers.

The best software for an SMB is built by someone who has sat with that business and listened. Not conducted a requirements session — listened. The warehouse manager explaining why they sort pick orders by aisle rather than by timestamp. The hotel owner explaining the edge case with group bookings during local festivals. The clinic administrator explaining the three kinds of appointment cancellation that have completely different implications for the schedule.

These stories are the domain. Metabolizing them into a data model, a set of SQL functions, a route structure, and a template is the craft. The framework should not add a fourth job: managing its own complexity.

Mycelium is designed so that a solo developer or a small team can own a system end-to-end — from the Postgres schema to the deployed container to the customer conversation — without fracturing their attention across framework layers that do not correspond to anything in the domain.

The aspiration is not a framework that makes you faster. It is a framework that makes your system legible to yourself, your team, and eventually your successor — at any point in the project's life, without heroic effort.

That legibility is the condition for sleeping at night.

What Mycelium Is Not

It is not a competitor to Django or FastAPI for teams building API-first products.
It is not designed for SPAs, or for systems where the client owns significant application state.
It is not trying to eliminate JavaScript — Alpine.js is a first-class citizen for behavior that belongs in the browser.
It is not a low-code tool. It is for developers who want more control, not less, but want that control to be located correctly rather than spread across the stack.

Current State and Invitation

Mycelium is built on FastAPI, with htmx for hypermedia interactions, Alpine.js for browser-local behavior, Jinja2 for templating, and Postgres as the application's durable core. The framework is under active development.

If you are a developer who:

builds custom tools for real businesses rather than platforms for other developers,
finds the cognitive overhead of the modern JS stack disproportionate to the problems it solves,
values a codebase that reads like its domain rather than like its framework,
and cares about the long-term maintainability of what you ship as much as the speed of shipping it —

then this architecture was designed with you in mind.

The philosophy has a name. The implementation has structure. The next step is finding the people who have been thinking the same way, perhaps without a framework to anchor it.

If that is you, I would like to hear from you.
The repo is open source (Apache2 License), on github:
https://github.com/Lopofsky/mycelium

Mycelium is the framework. The proterative principle was first articulated in the experimental project proterative (2020) and remains the architectural north star for every design decision in the framework.

DEV Community: stefanos.chr