LoweringComplexity

The web is an extraordinary environment. Arbitrary, untrusted code arrives on demand, opens on nearly any machine, and is reasonably safe to run.

A product is easy to share. A programmer can get a satisfying visual result in minutes. That makes the web perhaps the easiest place to prototype an application.

It also gives the ecosystem a powerful “worse is better” instinct: make the rough thing available, let it spread, and improve it later. That instinct helped the web win. It also left us with layers of machinery—webpack-era build systems, Flux-era state management, and countless conventions built on top of conventions.

Some complexity is the honest price of that reach. The mistake is not paying the invoice. The mistake is paying invoices that belong to somebody else.

The browser should provide distribution and capabilities.

Applications should produce experiences.

Complexity is the number of ways a system can behave.

That definition is more useful than counting files, lines, dependencies, or abstractions. The real cost is the number of facts and possible behaviors that must stay coordinated before a change is safe.

Consider a harmless-looking type:

type User = {
  is_signed_in: boolean

  username: string | null
  display_name: string | null

  is_subscribed: boolean
  is_deleted: boolean
  is_banned: boolean
  is_vip: boolean
}

Those states include combinations the product may never intend: a deleted VIP, a banned subscriber, or a signed-out user with a username. If the type permits those combinations, every consumer must either decide what they mean or improvise accidentally.

Handling every possible state is responsible. Writing 128 conditionals on every route is not. The better move is to remove states that should never exist and encode the intended alternatives once.

type User =
  | {
      status: "authenticated"
      username: string
      display_name: string
    }
  | {
      status: "anonymous"
    }

The union makes a product decision structural. Consumers no longer need to remember a convention about which combinations are valid. Prefer structures that produce the right behavior over conventions that ask everybody to remember it.

Every complex system should be able to name the pressure that makes a simpler alternative inadequate.

Then interrogate it. Does that pressure apply to us now? Actually? Could the experience change instead? Could a deeper layer own the guarantee?

Those facts justify careful media systems, predictable recovery, and serious performance work. They do not justify architecture designed for a thousand frontend engineers changing one application in parallel. Organizational scalability is a real constraint—but only when it is actually yours.

Keep forced machinery narrow

Server-side rendering is a useful example. Discoverability and link previews require pages that crawlers can understand. Midjourney runs a Bun server for marketing pages and image previews, while the bulk of the application stays client-side.

The constraint is named, its effect is narrow, and the machinery remains proportional to its reason. If the pressure disappears, the machinery should be easy to remove.

Specialize around the product, scale, environment, and team you actually have.

Distributed implementation is fine. Distributed authority is expensive.

Navigation, z-order, shared state, resource loading, input, and recovery order are global facts. Giving each one an authoritative home does not mean hiding the application inside one enormous abstraction. It means deciding where disagreement is resolved.

let d = 1

export const loft = d++
export const lightBox = d++
export const sideBar = d++
export const composer = d++
export const contextMenu = d++
export const tooltip = d++

d = 9999
export const modalBase = d++
export const errorBoundary = d++
export const toaster = d++

We re-render the whole application on scroll. In some places, on mouse move.

That sounds reckless if average work is the only standard. Our standard is predictable frame behavior across the whole experience, including unusual states, large accounts, custom hit testing, scrolling, and moving interface elements.

A deliberately provocative rule

Do all the work, all the time.

If it is slow, fix it until it is always fast enough.

This is not universal advice. It is one way to prevent rare combinations from secretly becoming much slower because a memoization boundary or incremental path stopped behaving as expected. The complete path exposes the tail instead of optimizing only the friendly path.

Good engineering is not merely producing a good average. It is knowing the bounds.

Websocket reconnection is a global ordering problem. Turn it into a written protocol.

1. 01

   Preserve a durable resume cursor or sequence.

2. 02

   Reconnect and subscribe without opening a gap.

3. 03

   Fetch a sequence-tagged snapshot of running and completed work.

4. 04

   Restore progress subscriptions.

5. 05

   Reconcile idempotently and reject stale progress.

A claim such as “we never miss anything” is only defensible when the backend provides the cursor, there is no gap between snapshot and stream, and reconciliation is idempotent. Those preconditions are the engineering.

During a failure, we need to know what ran, in what order, which state it owned, and how long that state was allowed to live. Quantify tolerances, failure, and recovery. Imprecision is sometimes acceptable; unexplained imprecision is not.

An abstraction becomes dangerous when its interface makes the caller believe the problem has a simpler shape than reality.

A websocket capability may hide timers, retries, and socket APIs. It should not hide the policy for stale data, cascading failure, or reconciliation.

Pretext can hide DOM access, font loading, and measurement machinery. It deliberately keeps preparation and layout visible, along with the geometry, ordering, and placement that the product still needs to decide. That is the line: hide mechanism, expose meaning.

Prefer capabilities over frameworks. A focused library or bounded service can solve one difficult boundary without deciding the shape of the entire application. Do not build a website around the way React—or any framework—wants the code organized. Build the experience users need, and go around the framework when the experience requires it.

A screen is a state. The experience lives in the transitions between states.

The web is unusually good for prototyping. That is a gift, but prototyping and committed product engineering are different concerns.

A prototype proves that something can happen. Engineering makes it keep happening.

Engineering begins where multiple reasonable requirements cannot all win. The work is choosing the tradeoff deliberately, then finishing the unglamorous final ten percent that makes the commitment dependable.

AI lowers the cost of synchronized edits, adapters, boilerplate, migrations, and other mechanical work. That changes some architectural tradeoffs.

If a model can keep explicit code synchronized, an abstraction that existed mainly to reduce typing may no longer be worth the conceptual cost. Two intentionally unfinished experiments follow from that instinct:

These are experiments, not doctrine.

LLMs can pay mechanical complexity.

They should never conceal conceptual complexity.

Models do not decide state ownership, ordering, tolerances, failure policy, or recovery for us. Those decisions often reveal their consequences years later or only in a small tail of users. Engineers still own the operating model.