Architecture

The server owns state. The browser holds none. Security is not a layer applied on top — it is a consequence of where state lives.

Intent in, projection out. State lives on the server. The browser holds nothing between requests.

Select a step to see the implementation detail.

The two-layer state model

State is separated into two layers with different lifetimes, different storage, and a strict one-way rule about which may influence the other. The rule is enforced structurally, not by convention.

Durable state what actually happened

  • Append-only event log: events are inserted, never modified
  • Past events cannot be altered by any code path
  • Auditable by construction: the log is the audit trail
  • All writes require gateway authorisation
  • Survives server restart; loss-free by design
one-way only

Ephemeral state current session context

  • In-memory only, keyed by session ID
  • Holds UI context: current view, in-progress flows, flash messages
  • Derived from durable state, never the reverse
  • Never used as input to durable state transitions
  • Discarded on session end; nothing persists to the client

Ephemeral state flows one direction only. Durable state seeds ephemeral state. Ephemeral state never influences durable state transitions. This rule makes client-side state manipulation structurally impossible: there is no client state to manipulate.

The gateway contract

The gateway is the security boundary of the system. All state access — read or write — passes through it. No handler, no middleware, no other package touches state directly. This is not a convention: the Store type is unexported from the state package; only the Gateway is exposed. There is no path around it.

// Reading state — returns a named projection
gateway.Project(ctx, sessionID, "projection-name")

// Writing state — submits a validated intent
gateway.Dispatch(ctx, sessionID, action)

Every call through the gateway enforces the same contract:

  • Session is authenticated
  • Actor is authorised for this action or projection
  • Action is valid against current state before any change is applied
  • Every transition is appended to the audit log

Authorisation is not middleware. It runs inside the gateway, inside every request. There is no separate runtime layer that can be bypassed with a crafted header.

The action pattern

State changes are expressed as validated intents, not direct mutations. A handler never writes state directly; it submits an action to the gateway.

type Action interface {
    Type()     string
    Validate(ctx, store, sessionID) error
    Apply(ctx, store, sessionID)    (Event, error)
}

The lifecycle of a state change:

  1. Handler parses the request and constructs an action
  2. Gateway calls Validate against current state; rejects if invalid
  3. Gateway calls Apply; produces a new event
  4. Event is appended to the durable log
  5. Gateway returns the updated projection to the handler
  6. Handler renders the projection as HTML: partial for htmx, full page otherwise

No partial application. No silent failure. No client state to reconcile.

Security by construction

Security in most systems is applied as a layer: middleware checks, validation libraries, WAF rules, security headers. Each layer can be misconfigured, bypassed, or forgotten. SAUI takes a different position: the architecture excludes entire vulnerability classes structurally, before any application code runs.

  • No client state. State manipulation — the classic "isAdmin: true" attack — requires client-held state to manipulate. The browser holds none. The attack class does not apply.
  • No hydration boundary. Server state is never serialised into inline HTML for client reconstruction. The hydration XSS attack class requires this boundary. It does not exist here.
  • No middleware security gate. Authorisation runs inside the gateway, inside every request handler. There is no separate runtime layer to bypass. The middleware bypass pattern that produced CVE-2025-29927 (CVSS 9.1) in Next.js cannot occur.
  • Append-only event log. Past events cannot be altered by any code path. An attacker with database access cannot rewrite history. The audit trail is a structural property, not a policy.
  • No npm dependency graph. htmx is a single vendored file. The rest of the stack is Go standard library. There are no transitive package dependencies and therefore no supply chain attack surface.

These are not mitigations. They are the consequence of an architecture where the dangerous patterns cannot exist.

Progressive enhancement

Every feature is built across four degradation levels. All four must produce correct state; the server owns truth regardless of client capability.

L0No JS, no CSS
Native HTML forms, POST submission, PRG pattern. Must always work.
L1CSS only
Full layout applied. No visual state that depends on JS class toggling.
L2JS present, htmx not yet loaded
Native form submission holds. Full page responses.
L3htmx loaded
Partial DOM updates active. Forms intercepted. hx-boost on navigation.
L4Full baseline JS
SSE connection for real-time projection updates. View Transitions if supported.

See the Go implementation