openbot-data-access

OpenBot Data Access

When To Use

This skill applies to any change under app/src that moves data between the browser and the API server. It fires on new screens, new endpoints, new query keys, and on any diff that introduces fetch anywhere but app/src/lib/client.ts.

It does not cover server handlers under server/, zod form schemas (lib/<entity>/form.ts), or page layout. It does cover lib/copilot/: the conversation itself streams over AG-UI, but the tool calls a Bot makes during a turn are ordinary authenticated requests and go through the client like everything else.

The Shape

Every entity the browser knows about owns a directory under app/src/lib/:

app/src/lib/
  client.ts      # the only fetch in the app
  <entity>/
    queries.ts   # read types, key factory, queryOptions factories
    mutations.ts # input type, mutationOptions factories
    form.ts      # zod schema (a different skill's territory)

client.ts owns the transport: credentials, the JSON content type, body serialisation, and turning a failed status into an Error carrying the server's own message. It owns nothing about meaning — the envelope key and the sentence a person reads stay at the call site, because those are facts about one endpoint rather than about requests in general.

client<T>(path, key, options?): Promise<T>    // parsed, and `key` unwrapped
client(path, options?): Promise<Response>     // for a caller that only needed it to work
tryClient(path, options?): Promise<Response>  // never throws; the status is the answer

options is { method?, body?, fallback?, signal? }. body is serialised by the client, which is also what sets the content type — so a caller passes an object, never a string. Passing JSON.stringify(x) sends a JSON string of a JSON string, which no endpoint accepts.

Three kinds of request

Not everything crossing the wire is cached state, and the shape follows from which kind it is.

1. A cached read is a queryOptions factory in queries.ts. It has a key, and something can invalidate it.
2. A write somebody asked for is a mutationOptions factory in mutations.ts. It invalidates on success.
3. Everything else is a plain exported function, living beside the factories for its entity. A verdict about this moment (decideComponent, testAgentConnection), a tool call during a Bot's turn (callPluginTool, the computer control surface), a frame of a screen, a step inside another write (storeMcpToken). These fail closed and return a value rather than throwing, because a refusal is usually the answer. Giving one a cache key would create a key nothing reads and an invalidation nothing triggers.