Datapages Architecture

Architecture

Read datapages first for the build loop, hard rules and naming conventions.

Use this skill to choose the Datapages constructs a feature needs. Ask the operator when a missing requirement would change that choice. Then read the referenced skill before implementing the selected construct.

Keep authoritative state on the server, separate reads from commands and send complete page updates instead of small DOM patches.

New app

datapages init  # go.mod, app/app.go, cmd/server/main.go, compose.yaml, Makefile, CI
make up         # start the broker
make dev        # datapages watch

init creates PageIndex, PageError404, PageError500, Head and RecoverError. It writes only missing files and deletes nothing. You can run it again without overwriting existing files.

Before the first page, decide:

Add sessions, state and events when a feature needs them, not upfront.

Before implementation

Do not guess requirements that change the application model. Ask the operator when they are unclear.

Do not ask when the requirement is already explicit in the task or existing code.

Use the smallest model that satisfies the requirements. Add sessions, events, State[T], persistence or shared handlers only when a current requirement needs them.

Default architecture

For server-backed interactive or real-time data, prefer Datastar's CQRS model:

• the server stores authoritative state;
• separate reads from commands;
• long-lived SSE handlers provide reads;
• short-lived actions are commands;
• commands mutate authoritative state and notify subscribers;
• On handlers react to events and render from authoritative state;
• prefer complete page updates over small DOM patches;
• keep plain GET rendering correct.

A command should normally mutate state and dispatch an event. The event says that something changed; it is not the authoritative state. Subscribers read the current state, render the page and send the result over SSE.

Render one template for each page and let Datastar update the changed DOM. Split templates into smaller components when useful. Do not add small DOM patches only to reduce transferred HTML. SSE streams use Brotli compression.

Each stream update must contain enough current state to restore the UI after a missed event or interrupted connection. Send complete current state when a missed incremental update would make the client incorrect.

Handle local interactions on the client. Examples include opening a menu, changing a class and validating a local field.

Where to store a value

Give each value one owner:

An On handler receives no request or signals. Put what it needs on the event or in State[T].

For example, copy a user-selected filter into State[T] in StreamOpen or in the action that changes it. The event handler can then render from that state.

state.Values is valid only while the handler runs. Never retain its pointer, store it in App or use it from a goroutine. Copy the required values.

How to update the browser

The acting tab also receives subscribed events. A command that dispatches an event rarely needs SSE. Using both usually sends the same state twice.

For server-rendered updates, render a complete DOM tree from current state. Avoid coordinating many small patches or client-side signal updates.

Shrink morph targets only for a measured reason. A complete HTML fragment is often simpler because Datastar preserves unchanged DOM while morphing the received tree.

Events are notifications, not durable state. Delivery is at most once and has no replay. A hidden tab, interrupted stream or full buffer can miss an event. Later renders must use authoritative state. They must not depend on every earlier event.

Every page must also render correctly from a plain GET.