Architecture

In most TypeScript UI frameworks, each component manages its own state and effects. In Foldkit, there’s a single state tree. Every change flows in one direction through the same loop.

This pattern is called The Elm Architecture. You don’t need to know Elm — Foldkit adapts it for TypeScript and Effect.

Every Foldkit app runs the same loop. A Message arrives — the user clicked a button, a timer fired, an HTTP response came back. The update function receives the current Model and the Message and returns a new Model along with any Commands to execute. The view function renders the new Model as HTML. When the user interacts with the view, it produces another Message, and the loop continues.

Commands are descriptions of one-shot side effects — HTTP requests, focus operations, localStorage writes, navigation calls. The Foldkit runtime executes them and sends their results back as new Messages, feeding them into the same loop. Each Command carries a name, which surfaces in tracing and tests.

Subscriptions are continuous streams of Messages from external sources — keypresses, recurring timers, WebSocket frames, window resize events. Where a Command runs once and reports back, a Subscription stays active for as long as the Model says it should, and the stream decides which source events become Messages.

ManagedResources have an acquire/release lifecycle tied to Model state — a camera stream during a video call, a WebSocket connection while the user is on a chat page. The runtime acquires them when the Model enters the relevant state, releases them when it leaves, and dispatches Messages for each transition.

That’s it. Every state transition in your app flows through a single loop. There’s no action-at-a-distance, no hidden state mutation, no effect that runs outside the cycle. If you want to know how the app got into its current state, you follow the Messages.

The complete cycle looks like this:

          +------------------------------------------+
          |                                          |
          ↓                                          |
       Message                                       |
          |                                          |
          ↓                                          |
  +---------------+                                  |
  |    update     |                                  |
  +-------+-------+                                  |
  ↓               ↓                                  |
Model    Command<Message>[]                          |
  |               |                                  |
  |               +-> Runtime -----------------------+
  |                                                  |
  +-> view -> Browser -> user events ----------------+
  |                                                  |
  +-> Subscriptions -> Stream<Message> -> Runtime ---+
  |                                                  |
  +-> ManagedResources -> lifecycle -----------------+

Every path on the right side produces a Message that feeds back into update. Four sources — Commands, Subscriptions, ManagedResources, and the Browser — one loop.

Sitting beneath the loop are Resources: app-lifetime singletons like AudioContext, RTCPeerConnection, or CanvasRenderingContext2D that Commands draw on. Resources don’t produce Messages themselves — they’re the ambient dependencies the Message-producing parts need to do their work.

Each concept in one place, in plain terms:

Think of a Foldkit app like a restaurant. The waiter keeps a notebook — a running picture of everything happening right now. Table 3 ordered the salmon. Table 5 is waiting for dessert. When something happens — a customer flags the waiter, the kitchen rings the bell — the waiter hears about it, updates their notebook, and maybe writes a slip for the kitchen. The waiter doesn’t cook the salmon — they hand the slip to the kitchen, and the kitchen reports back when it’s done.

Messages work the same way. “Table 3 asked for the check” is a fact given to the waiter, not an instruction. The waiter decides what to do — maybe bring the check immediately, maybe offer dessert first. The message stays the same either way.

That’s the architecture in the abstract. The next page shows a complete counter application — and you’ll see each of these pieces in the code.