# App files

This page is the format of a Volobox app as the Builder's agent writes it: `app.json`, the rules, the screens, and how they reach the rest of Volobox. You do not need it to build an app; read it to review a change under **Details** > **Changed files**, or to edit an exported app. Examples are adapted from the **Expense Claims** template.

## Folder layout

```text
app.json            data, roles, access, rules list, screens list, menu, events, secrets
AGENTS.md           the app's guide for the Builder's agent (only the agent reads it)
rules/
  submit.js         one file per rule, default-exporting an async function
  lib/              code the rules share
screens/
  MyClaims.tsx      one React component per screen
  lib/              code the screens share
locales/
  en.json           only in an app with several languages: one file per language
  tr.json
package.json        optional packages the screens use
package-lock.json   written by Volobox after each turn; never edited by hand
```

Any other file in the workspace (notes, scratch files) is not part of the app. An export holds the model, rules, screens and packages, never records, people or logs.

## `app.json`

`app.json` validates against `app.schema.json`. Only `version` and `name` are required.

| Key | Type | Meaning |
| --- | --- | --- |
| `$schema` | string | Optional path or URL of the schema, for editors. Volobox ignores it |
| `version` | integer | Format version. Always `1` |
| `name` | string | The app's name. People see the **Name** on the app's **Settings**; Volobox writes that name here when it saves the files |
| `description` | string | One or two sentences on what the app is for |
| `roles` | array | The app's own roles (see [Roles and audiences](#roles-and-audiences)) |
| `enums` | array | Named value lists that `enum` fields use |
| `entities` | array | The record types the app stores. Each becomes a table |
| `rules` | array | Server-side JavaScript: operations, endpoints, event handlers and schedules |
| `access` | object | Who may do what, per entity, endpoint and screen |
| `screens` | array | The app's pages, each a React component |
| `startPage` | string | Id of the screen the app opens on. Defaults to the first screen that is not hidden |
| `navigation` | string | Who draws the navigation: `shell` (Volobox, the default) or `screens` (the app, with `AppNav`) |
| `menu` | object | The menu's layout: `items` in order (screens, sections, folders, separators, links to other Volobox pages) and `footer` |
| `languages` | object | `{ "default": "en", "supported": ["en", "tr"] }`; each supported language has `locales/<language>.json` |
| `events` | array | The events this app announces outside itself, so workflows can start from them |
| `shares` | array | What this app offers other apps: records to read, events to handle, endpoints to call |
| `uses` | array | Other apps' shares this app reads, each under an alias |
| `secrets` | array | Credentials the rules send to other systems, read as `env.<NAME>` |
| `connections` | array | Kinds of accounts at other services that people connect, for rules to act as |
| `listens` | array | The Volobox events the app's rules react to |
| `volobox` | object | The parts of Volobox's public API the app's screens call |

## Roles and audiences

Two kinds of roles decide what a person does in an app:

- **Member roles** are Volobox's and are never written in the files. An app's Admins give them under **Settings** > **Members**: `member` uses the published app, `builder` also builds the draft and publishes (and reads and changes every record, whatever `access` says), `admin` also manages people and settings. People with **Manage all apps** count as an Admin of every app.
- **App roles** are the app's own, listed under `roles` and assigned under **Settings** > **Roles**. They only add to what a member may do.

```json
"roles": [
  { "id": "approver", "label": "Approver", "description": "Approves, sends back or rejects the claims that name them." },
  { "id": "finance", "label": "Finance", "description": "Keeps the spending policy and pays approved claims." }
]
```

`access` names **audiences**:

| Audience | Who |
| --- | --- |
| A role id, such as `approver` | The people and groups who hold that app role |
| `everyone` | Every member of the app, whatever app roles they hold (everyone in the workspace when the app is public) |
| `anyone` | Also people who are not signed in, on the published app only. Never an entity audience |

Unless asked otherwise, a new app starts with one role, `editor`, that may create, change and delete everything, and `everyone` with `list` and `read` on every entity, every screen and every GET endpoint.

## Enums

```json
{
  "id": "claim-status",
  "name": "ClaimStatus",
  "label": "Status",
  "values": [
    { "name": "draft", "label": "Draft", "value": 0, "color": "gray" },
    { "name": "submitted", "label": "Waiting for approval", "value": 1, "color": "blue" },
    { "name": "approved", "label": "Approved", "value": 3, "color": "green" }
  ]
}
```

`id` is stable, lowercase with dashes; `name` is PascalCase and is what an `enum` field names. Records hold a value's `name`; `value` is the stored number, which publishing flags when it changes for an existing name.

## Entities

| Key | Meaning |
| --- | --- |
| `id` | Stable id, lowercase with dashes. Keep it when the entity is renamed |
| `name` | PascalCase singular name, such as `Claim`. Fields, rules and access refer to it |
| `label`, `pluralLabel`, `description` | How people see it |
| `displayField` | The field that names a record in lists, pickers and references |
| `ownerField` | A reference-to-`user` field that says whose record it is. `scope: "own"` compares it with the signed-in person |
| `fields` | The entity's fields |
| `validations` | Checks that compare two fields of the same record |
| `volobox` | How the records take part in Volobox (see [The volobox block of an entity](#the-volobox-block-of-an-entity)) |

Every entity also has `id`, `createdAt`, `createdBy`, `updatedAt` and `updatedBy`, which are not listed. A record read through the API carries `$version`, which an update passes back so that a write made in between is refused rather than overwritten.

Removing a table or field parks its data; adding it back with the same `id` restores it. Publishing never deletes data.

### Field types

| `type` | Holds |
| --- | --- |
| `text` | Text, optionally with `maxLength`, `minLength`, `pattern` or `format` (`email`, `phone`, `url`) |
| `integer`, `decimal` | Numbers, with `min`, `max` and, for `decimal`, `scale` |
| `money` | An amount with `currency` (an ISO 4217 code such as `EUR`) and `scale` |
| `boolean` | Yes or no |
| `date`, `dateTime`, `time` | A day (`YYYY-MM-DD`), a moment (ISO 8601 in UTC), a time of day (`HH:MM`) |
| `enum` | One value of the enum named in `enum` |
| `reference` | A record of `entity`: another table of the app, `user` for a Volobox person, `volobox.<kind>` for a Volobox item (read only, such as `volobox.project`), or `app.<alias>.<Entity>` for another app's shared records (read only) |
| `file`, `image` | A stored file, optionally limited by `allowedContentTypes` (and image dimensions) |
| `list` | A list of `itemType` values (`text`, `integer`, `decimal`, `boolean`, `date` or `enum`), with `maxCount` and `uniqueItems` |
| `formula` | A computed value: a Power Fx `expression` over the record's fields, with a `resultType` |
| `rollup` | A summary of another entity's records: `source`, `via` (its reference field), `operation` (`count`, `sum`, `average`, `min`, `max`) and `value` |
| `secret` | A credential each record holds, stored encrypted and never read back |

### Field options

| Option | Meaning |
| --- | --- |
| `id`, `name` | Stable id (lowercase with dashes) and camelCase name |
| `label`, `description` | How people and agents see the field |
| `required` | A record cannot be saved without a value |
| `unique` | No two records hold the same value |
| `default` | The value a new record starts with |
| `readOnly` | Only rules write it |
| `serverOnly` | Never leaves the server: rules read and write it, screens never see it |
| `onDelete` | For a reference to the app's own entity: `restrict` (default), `cascade` or `setNull` |
| `scopedBy` | For a Volobox item with a parent, such as `volobox.milestone`: the field holding the parent, so the picker offers only its items |

```json
{
  "id": "expense",
  "name": "Expense",
  "displayField": "merchant",
  "ownerField": "employee",
  "fields": [
    { "id": "claim", "name": "claim", "type": "reference", "entity": "Claim", "required": true, "onDelete": "cascade" },
    { "id": "employee", "name": "employee", "type": "reference", "entity": "user", "readOnly": true },
    { "id": "amount", "name": "amount", "type": "money", "currency": "USD", "required": true, "min": 0.01 },
    { "id": "receipt", "name": "receipt", "type": "file", "allowedContentTypes": ["image/jpeg", "image/png", "application/pdf"] },
    { "id": "over-limit", "name": "overLimit", "type": "boolean", "readOnly": true, "required": true, "default": false }
  ]
}
```

### The `volobox` block of an entity

| Key | Meaning |
| --- | --- |
| `screen` | Id of the screen a record opens on in Volobox. It receives the record's id in the query parameter `param` |
| `param` | The camelCase query parameter name. Defaults to `id` |
| `copyReference` | People may copy a record's reference into chats, tasks and documents |
| `agenda` | People may add a record to their Volobox agenda |
| `discussion` | Each record has a Volobox discussion of its own, open to the people who may read the record |
| `search` | `{ fields, semanticFields }`: Volobox's quick search finds records by `fields`; `semanticFields` suggests fields an Admin may allow for search by meaning |

The block needs a `displayField` and a screen. It widens nothing: a reference, agenda link or discussion opens a record only for people the app lets read it, and only in the published app.

## `access`

```json
"access": {
  "entities": {
    "Claim": {
      "everyone": { "list": true, "read": true, "create": true, "update": true, "delete": true, "scope": "own" },
      "approver": { "list": true, "read": true },
      "finance": { "list": true, "read": true }
    }
  },
  "endpoints": { "submit": ["everyone"], "decide": ["approver", "finance"], "pay": ["finance"] },
  "screens": { "claims": ["everyone"], "approvals": ["approver", "finance"], "payments": ["finance"] }
}
```

| Key | Meaning |
| --- | --- |
| `entities.<Entity>.<audience>` | A grant: `list`, `read`, `create`, `update`, `delete`, optionally `scope: "own"` (records whose `ownerField` is the person) and `when` (a formula limiting `update` and `delete`, such as `status = "draft"`) |
| `endpoints.<rule id>` | The audiences that may call an endpoint. Left out, it is for Builders and Admins only |
| `screens.<screen id>` | The audiences that see a screen. Seeing a screen grants no data |
| `channels.<name>` | Who hears a realtime channel a rule publishes on (`everyone` or role ids) |
| `connections.<name>` | Who may connect and disconnect accounts of a connection in the published app, besides its Admins |
| `openToAnyone` | One entry per place open to `anyone`: `{ "target": "endpoint:<rule id>", "quote": "..." }` or `screen:<screen id>`, with the reason the **Review** tab shows |

Nothing is allowed unless a grant allows it, and grants only add up. A visitor who is not signed in never reads a table: a screen open to `anyone` gets data only through an endpoint open to `anyone`, and whatever that endpoint answers is public.

## Rules

Rules run on Volobox's server, never in the browser. Each one is an entry in `rules` and a file under `rules/`.

| Key | Applies to | Meaning |
| --- | --- | --- |
| `id`, `kind`, `file`, `description` | all (required) | Stable id; the kind; the file under `rules/`; one sentence people read on review |
| `entity`, `operation` | `operation` | The entity, and which write it takes over: `create`, `update` or `delete` |
| `method`, `route` | `endpoint` | `get`, `post`, `put`, `patch` or `delete`, and a path such as `/claims/{id}/submit` |
| `calledByOtherSystems` | `endpoint` | `true` for an endpoint open to `anyone` that another system calls, such as a webhook |
| `visitorLimits`, `uploads` | `endpoint` | How often one visitor may call it; files sent with the call, by body key |
| `event`, `from` | `event` | The event's name, and where it comes from: left out for the app's own events, a `uses` alias for another app, `volobox` for a Volobox event |
| `cron`, `everyMinutes` | `schedule` | A five-field cron expression in UTC, such as `0 9 * * 1-5`, or a run every so many minutes |

| `kind` | Runs |
| --- | --- |
| `operation` | In place of the create, update or delete of one table, after Volobox has checked the person's access. Use it to stamp values or refuse with a message |
| `endpoint` | When a screen, an Inbox card button, an agent or another system calls it, such as **Submit** or **Approve** |
| `event` | In the background, after a rule announces an event, another app's shared event happens, or a Volobox event the app listens to happens |
| `schedule` | On a timetable in UTC. Only the published app's schedules run |
| `background` | Long work another rule hands off, in batches |

```json
{ "id": "submit", "kind": "endpoint", "method": "post", "route": "/claims/{id}/submit", "file": "rules/submit.js",
  "description": "Sends the person's claim for approval and gives the approver an Inbox card." },
{ "id": "notify-decision", "kind": "event", "event": "claim.decided", "file": "rules/notify-decision.js",
  "description": "Tells the person whether their claim was approved, sent back or rejected." },
{ "id": "approval-reminders", "kind": "schedule", "cron": "0 9 * * 1-5", "file": "rules/approval-reminders.js",
  "description": "Every weekday at 09:00 UTC, reminds each approver of the claims that wait." }
```

### The rule function

A rule's file default-exports an async function that takes one object. Destructure what you need:

```javascript
export default async function ({ params, db, inbox, currentUser, badRequest, conflict, notFound }) {
  // ...
}
```

What it gets depends on its kind:

| Kind | Gets | `currentUser` is |
| --- | --- | --- |
| `operation`, create | `values`: the checked values, with field defaults and the owner filled in | The person creating |
| `operation`, update | `id`; `values`: only the fields sent; `previous`: the record as stored | The person updating |
| `operation`, delete | `id`; `previous` | The person deleting |
| `endpoint` | `params` (route segments), `query`, `body` (JSON, `{}` when there is none), `headers` (lower case, never `authorization` or `cookie`), `rawBody` (the text that arrived), `form` (a form-encoded body), `caller` (`{ app }` for another app's call), `visitor` | The caller; `null` for a visitor and for another app's call |
| `event` | `event` (its name), `payload`, `source` (`{ app }` or `{ volobox: true }`) | The person whose action published it; `null` for a schedule, a visitor, another app's event and a Volobox event |
| `schedule` | Nothing more | Always `null` |

`currentUser` is `{ id, name, email }`, or `null`. It is also `null` for an agent acting as itself; then `agent` is `{ id, name }`. A rule that needs a person refuses when `currentUser` is `null`.

Values arrive in fixed forms: an enum as its value's `name`, a date as `YYYY-MM-DD`, a moment as ISO 8601 in UTC, a reference as the record's id.

### What every rule gets

| Member | Use |
| --- | --- |
| `db.<Entity>` | `get(id)`, `find(id)` (or `null`), `list(filter, { fields, include, limit })` (100 records unless `limit` says otherwise), `count(filter)`, `aggregate({ operation, field, groupBy, dateBucket, filter })`, `create(values)`, `update(id, values, { version })`, `delete(id)` |
| `clock` | `now()`, `today()`, `addMinutes`, `addHours`, `addDays`; moments are ISO 8601 in UTC |
| `auth` | `isBuilder`, `hasRole(roleId)` for the person running the rule |
| `currentUser`, `agent` | Who is acting (above) |
| `app` | `key`, `environment` (`dev` or `published`), `peopleWithRole(roleId)`, `endpointUrl(route, query)`, `screenUrl(slug, params)` |
| `people` | `holders({ platformRoles, roles })` and `rolesOf(userId)` |
| `events` | `publish(name, payload)` |
| `apps.<alias>` | `call` an endpoint another app shares with this one |
| `volobox` | Reads Volobox items: `get(kind, id)` answers the item's fields, or `null` |
| `utils` | `formatDate`, `formatCurrency`, `daysBetween`, `toCsv`, `escapeHtml`, `sanitizeHtml` and more; each takes one object |
| `files`, `realtime`, `background` | Stored files, messages to screens listening on a channel, and long work in batches |
| `env` | Placeholders for the declared secrets, never their values |
| `http` | Requests to other systems' REST APIs (see [Call other systems from an app](/docs/call-external-systems)) |
| `connections` | Accounts connected to the app, for `http` to act as |
| `crypto` | `verifyHmac`, `verifySecret`, signing and hashing with secrets, `randomId()` |
| `inbox`, `notifications`, `alerts` | Inbox cards, bell notifications and alerts |
| `log` | `log(...)`, `log.info`, `log.warn`, `log.error`, `log.debug`: lines in the rule's run log |
| `userError`, `ok`, `created`, `noContent`, `badRequest`, `forbidden`, `notFound`, `conflict`, `redirect`, `response` | Refusals and answers (below) |

`db` writes with the app's own rights: it skips `access`, may write `readOnly` and `serverOnly` fields, and never runs an operation rule. Required fields, validations and uniqueness still apply. `db.create` does not fill `ownerField`; set it yourself. An operation rule replaces the write it is for, so a create rule calls `db.<Entity>.create(...)` itself and returns what it created. Volobox items are read, never written.

### Refusals and answers

- `throw userError("...")` refuses with a message the person sees, and undoes everything the run wrote.
- An endpoint answers with a helper: `ok(body)`, `created(body)`, `noContent()`, `badRequest(message)`, `forbidden(message)`, `notFound(message)`, `conflict(message)`, `redirect(app.screenUrl(...))` (a 303 to one of the app's screens) or `response(status, body)`. A plain returned object is the answer's body. Writes are kept only when the answer is below 400.
- When Volobox itself refuses a write (a value that does not fit its field, a record that does not exist), the person sees that refusal's own message, and nothing the rule wrote is kept.

A POST, PUT, PATCH or DELETE endpoint declares the body it takes, so Volobox checks every call before the rule runs:

```javascript
export const input = {
  decision: { type: "enum", values: ["approve", "reject"], required: true, description: "What the approver decided." },
  note: { type: "text", maxLength: 500 },
};

export default async function ({ params, body, db }) { /* body.decision is "approve" or "reject" */ }
```

A field takes `type` (`text`, `integer`, `decimal`, `boolean`, `date`, `dateTime`, `time`, `enum`, `reference`, `file`) and optionally `required`, `values`, `maxLength`, `min`, `max` and `description`. Write it as a plain object literal. A call that breaks it answers `400` with `{ error, errors: [{ field, code, message }] }`, and the rule does not run.

### An endpoint rule

`rules/submit.js` from the template, shortened:

```javascript
export default async function ({ params, db, app, inbox, clock, currentUser, badRequest, conflict, notFound }) {
  const claim = await db.Claim.find(params.id);
  if (!claim || claim.employee !== currentUser?.id) {
    return notFound("You have no claim with that number.");
  }
  if (claim.status !== "draft" && claim.status !== "returned") {
    return conflict(`${claim.number} is already ${claim.status}.`);
  }
  if (!claim.approver || claim.approver === claim.employee) {
    return badRequest("Choose someone else to approve your claim.");
  }

  const today = clock.today();
  await db.Claim.update(claim.id, { status: "submitted", submittedOn: today });

  // The card is named by the claim, so sending it again for a resubmitted claim brings it back.
  await inbox.notify(claim.approver, {
    id: `approve:${claim.id}`,
    title: `${currentUser.name} asks you to approve ${claim.number}`,
    screen: "claim",
    params: { id: claim.id },
    actions: [
      { key: "approve", label: "Approve", variant: "primary", endpoint: "decide", params: { id: claim.id }, body: { decision: "approve" } },
      {
        key: "reject", label: "Reject", variant: "destructive", placement: "menu",
        endpoint: "decide", params: { id: claim.id }, body: { decision: "reject" },
        confirm: "Reject this claim?", input: { field: "note", label: "Why?", required: true },
      },
    ],
  });

  return { status: "submitted", submittedOn: today };
}
```

### Events

An event a rule publishes reaches the app's own event rules. To let a workflow or another app start from it, declare it under `events`:

```json
"events": [
  { "name": "request.submitted", "label": "Request submitted", "description": "A requester submitted a draft.", "entity": "Request" }
]
```

```javascript
await events.publish("request.submitted", { id: request.id });
```

With `entity`, publish the record's id as `id`. A workflow started by the event (an **App event** trigger) is told the app, the event and that id, never the rest of the payload, and reads the record with its own access in the app. A draft's events never start a workflow.

### Telling people

| Call | Use it for |
| --- | --- |
| `notifications.send(to, { title, screen, params })` | News that needs no answer. Rings the bell |
| `inbox.notify(to, { id, title, subtitle, screen, params, actions, dismissible })` | Work someone has to do. A card stays until it is resolved and never rings the bell |
| `inbox.update(id, changes)` / `inbox.resolve(id)` | Change a pending card quietly; withdraw it when the work is done |
| `alerts.raise({ key, title, summary, severity, to })` / `alerts.resolve(key)` | A condition that holds until someone fixes it, such as low stock |

`to` is a user id, a list, `"everyone"`, or `{ users, groups, roles, platformRoles }`, where `platformRoles` is `"admin"`, `"builder"` or `"member"`. A card or notice opens a screen of the app (`screen`, `params`) or a Volobox item (`ref: { kind, id }`, such as `volobox.task`). A card's `actions` open a screen, open an item, or run an endpoint as the person who pressed it, under that endpoint's own access. In the draft, cards, notifications and alerts reach only the app's Admins and Builders; in a Builder's test run nothing is sent.

Rules have no email API. To send mail, call a mail service with `http`.

## `listens` and Volobox events

An app reacts to a Volobox event (a task closed, a pull request merged, a ticket opened) with an event rule `"from": "volobox"`:

```json
"listens": [{ "event": "task.closed", "description": "Count closed work against its request." }],
"rules": [
  { "id": "on-task-closed", "kind": "event", "from": "volobox", "event": "task.closed", "file": "rules/on-task-closed.js",
    "description": "Marks the request done when its task closes." }
]
```

```javascript
// rules/on-task-closed.js
export default async function ({ payload, db, volobox }) {
  const [request] = await db.Request.list({ task: payload.subject.id }, { limit: 1 });
  if (!request || request.status === "done") return; // a second delivery changes nothing
  const task = await volobox.get("task", payload.subject.id);
  await db.Request.update(request.id, { status: "done", closedTitle: task?.label ?? null });
}
```

| `payload` field | Meaning |
| --- | --- |
| `id` | Names the event; the same on a second delivery |
| `event`, `occurredAt` | What happened and when |
| `actor` | `{ userId, agentId }` |
| `subject` | `{ kind, id, label, number }`: the item it is about |
| `scope` | `{ projectId, repositoryId, supportDeskId, appId }` |
| `data` | The event's own fields: ids, states and labels, never a message body or description |
| `causation` | `{ workflowRunId, agentRunId, batchId, batchSize }` |

- `listens` says what the app hears, never where. An Admin of the app binds each event under **Settings** > **Volobox events**, to every project (repository, desk) or named ones; until then nothing runs. `"required": true` stops a publish until it is bound.
- Only the published app hears Volobox. Test a draft rule with **Test with a recent event** on that settings page.
- The rule runs with nobody signed in, in a transaction of its own. An event may arrive twice: write the rule so that a second run changes nothing.
- The events offered are those [webhooks](/docs/webhooks) receive that belong to a project, repository or support desk. See the [event catalog](/docs/events).

## Screens

```json
{ "id": "claims", "slug": "claims", "title": "My claims", "entry": "screens/MyClaims.tsx", "icon": "Receipt" },
{ "id": "claim", "slug": "claim", "title": "Claim", "entry": "screens/ClaimDetail.tsx", "hidden": true, "parent": "claims" }
```

| Key | Meaning |
| --- | --- |
| `id` | Stable id. `access`, `startPage` and `parent` refer to it |
| `slug` | The address segment, unique in the app. `dev` and `build` are refused |
| `title` | The title in navigation and the browser tab |
| `entry` | The file under `screens/` whose default export is the screen |
| `hidden` | Left out of the menu but still opened by a link, such as a detail page |
| `parent`, `group` | Where the screen sits in navigation |
| `icon` | An icon `@volobox/ui` exports, by name, such as `LayoutDashboard` |

A screen's default export receives `AppScreenProps`:

```tsx
import type { AppScreenProps } from "@volobox/app";
import { Button, PageHeader } from "@volobox/ui";

export default function MyClaims({ sdk, params }: AppScreenProps) {
  async function submit(id: string) {
    try {
      await sdk.data.endpoints.submit({ params: { id } });
      sdk.toast.success("Sent for approval.");
    } catch (error) {
      sdk.toast.error((error as Error).message);
    }
  }
  // ...
}
```

`params` holds the values the screen was opened with, as strings. `sdk` offers:

| Member | Use |
| --- | --- |
| `sdk.data` | `list(entity, { filters, search, sort, fields, include, skip, limit, total })` answers `{ items, totalCount }`; `get`, `create`, `update(entity, id, values, { version })`, `delete`, `aggregate`, `upload`, `fileUrls`, `export`, `importTemplate`, `importFile`, `access()` |
| `sdk.data.endpoints.<rule id>({ params, query, body, headers })` | Calls an endpoint and returns the body the rule answers with |
| `sdk.currentUser` | `{ id, displayName }`; both `null` for a visitor who is not signed in |
| `sdk.navigate(slug, params)` | Opens another screen of the app |
| `sdk.toast` | `success`, `error`, `info`, `warning`, `show({ title, description, variant, duration, action })`: a notice to this person only |
| `sdk.people` | `displayNames(userIds)`, `search(query, { limit })` |
| `sdk.references` | `search(kind, query, options)`, `get(kind, ids)`, `open(item)` for the Volobox items the app's fields refer to |
| `sdk.volobox` | Volobox's actions on a record (copy reference, agenda, discussion) and `sdk.volobox.v1`, Volobox's public API as the person on the screen |
| `sdk.realtime` | `subscribe(channel, onMessage, { onConnected })` |
| `sdk.connections` | `list(name)`, `connect(name, { returnTo })`, `disconnect(id)` |
| `sdk.locale` | `{ language, direction, timeZone }` |
| `sdk.navigation` | The app's menu, for a screen that draws its own |
| `sdk.t(key, values)` | A text from the app's `locales/` file in the person's language |

Every refused or failed call throws an `AppDataError` with `message` (ready to show), `code` (such as `Volobox:AppPlatform:FieldRequired`, or `null` for an endpoint rule's own error), `field` and `status`. Volobox checks access on every call; what a screen hides only spares people a button that would fail.

A screen may import `react`, `@volobox/ui`, `@volobox/forms`, the libraries Volobox runs (`@volobox/dates`, `@volobox/icons`, `@volobox/echarts`, `@volobox/radix`, `@volobox/utils`, `@volobox/dnd`, `@volobox/virtual`, `@volobox/query`), types from `@volobox/app` (with `import type`), other files under `screens/`, and packages listed under `dependencies` in `package.json`. Any other import fails the build.

> **Warning: Screen code runs as the viewer**
>
> A screen runs signed in as whoever opens it and can do what that person can do in Volobox. With a screen open to `anyone`, the code of every screen can be read by visitors, though none of their data.

## The `volobox` block

```json
"volobox": { "access": ["projects", "people"], "levels": { "people": "read" }, "required": ["projects"] }
```

| Key | Meaning |
| --- | --- |
| `access` | The public API groups the screens call through `sdk.volobox.v1`: `agenda`, `people`, `projects`, `conversations`, `meetings`, `files`, `docs`, `support`, `calendar`, `workspace`, `audit` |
| `levels` | Per group, `read` or `readWrite`. A group with no level reads and writes |
| `required` | Groups the app cannot work without; a publish stops until an Admin allows them |

Listing a group asks; it is allowed under **Settings** > **Volobox access**, for the draft and the published app separately: a Builder or Admin allows it for the draft, and only an Admin for the published app. The person on the screen gets only what they could already see and do in Volobox.

## Related

- [Build an app](/docs/build-an-app)
- [Call other systems from an app](/docs/call-external-systems)
- [Apps](/docs/apps)
- [Code workflow API](/docs/code-workflow-api)
