Anatomy of an application
An application offers one or more vertices. Users place them on a project canvas, connect them, and configure them. Each vertex has an executor, the code that runs when the flow reaches it, and metadata that declares its inputs and outputs. It can also have capabilities and services.
Capabilities
Section titled “Capabilities”| Capability | Executor type | The vertex gets |
|---|---|---|
| None | Action | Runs when the flow reaches it. |
| Browser | Browser | A page that people use while it runs. |
| Cron | Cron Trigger | Calls on a schedule, until it completes or stops. |
| External | External Trigger | Endpoints for callers outside Adapt, such as webhooks. |
| Configurator | A settings page with its own backend. |
You can combine them. A booking page, for example, uses Browser for its visitors and Configurator for the owner’s settings.
Project files
Section titled “Project files”Directoryticket_form/
- manifest.json
- runtime.json
- README.md
- package.json
- tsconfig.json and three environment configs
Directorysrc/
Directoryticket_form/
- vertex.json
- metadata.json
- executor.ts
- configurator.ts
Directoryui/ pages, API client, and mock
- …
| File | Contents |
|---|---|
manifest.json |
The application’s name, label, description, version, organization, author, and links. Its service definitions. |
runtime.json |
The programs: which vertices run together, and their limits. |
vertex.json |
The vertex’s name, label, description, capabilities, and services. |
metadata.json |
The vertex’s signals. |
executor.ts |
Lifecycle handlers, and the routes of Browser and External vertices. |
configurator.ts |
The routes of the settings page. |
ui/ |
The pages. |
README.md |
Documentation for the people who use the application. |
Both manifest.json and vertex.json can have a logo.
Signals
Section titled “Signals”metadata.json declares how a vertex connects to the rest of the graph. See Signals, transmitters & receivers for the concepts.
| Field | Contents |
|---|---|
receivers |
Named inputs. Each one starts the vertex, and lists the signals that it needs in bindings. |
transmitters |
Named outputs, each with a mode and the signals that it sends. |
exchanges |
Sub-graphs that the vertex can run. See Exchanges. |
complete |
Whether the vertex is configured and ready to run. |
cronSchedule |
For Cron Triggers: a cron expression, such as */5 * * * * *. |
Each signal has formats: a JTD schema, such as { "jtdSchema": { "type": "string" } }, or a MIME type for files, such as { "mimeType": "image/png" }.
This Action vertex receives an optional name, and sends a greeting:
{ "complete": true, "receivers": [ { "name": "input", "description": "Starts the vertex.", "bindings": [ { "name": "name", "label": "Name", "description": "The name to greet.", "optional": true, "accepts": [{ "jtdSchema": { "type": "string" } }] } ] } ], "transmitters": [ { "name": "output", "label": "Greeted", "description": "Sent once with the greeting. The vertex then completes.", "mode": "MODE_STANDARD", "signals": [ { "name": "greeting", "label": "Greeting", "formats": [{ "jtdSchema": { "type": "string" } }] } ] } ], "exchanges": []}import { createIERouter } from "@mochabug/adapt-sdk/router";
export const internal_http = createIERouter((router) => { router.onStart(async (_request, api) => { const name = await api.getSignal<string | undefined>("name"); await api.send("output", { greeting: `Hello, ${name ?? "world"}!` }); });});Users see the labels and descriptions when they bind signals, so write them for people who are not developers.
Lifecycle
Section titled “Lifecycle”- When the flow reaches the vertex, Adapt calls
onStart. - While it runs, Adapt calls
onExchangewhen an exchange has an update, andonCronon schedule. Browser and External vertices also handle requests. - The vertex completes when it calls
send()on a standard or failure transmitter, orsend()without a transmitter.
A vertex does not have to complete. A dashboard, for example, can stay active for the whole session. Adapt calls onStop only when someone stops the session, so clean up before your vertex completes.
Transmitter modes
Section titled “Transmitter modes”| Mode | send() |
|---|---|
MODE_STANDARD |
Sends once, and completes the vertex. The default. |
MODE_STREAM |
Starts a new fork of the downstream graph each time. The vertex stays active. |
MODE_FAILURE |
Sends once with a failure flag, and completes the vertex. The graph’s failure handling takes over. |
Use a failure transmitter for errors that the flow must handle, such as a provider that rejects a request. Expected outcomes, such as an approval or a rejection, use standard transmitters.
Configurators
Section titled “Configurators”A settings page saves the vertex’s settings with postConfig. It can also change the vertex’s metadata, for example to add an input for each field of a form. A vertex with a settings page starts with "complete": false, and can run only after the page marks it complete:
router.addRoute("POST", "/api/settings", async (request, api) => { const input = (await request.json()) as { heading?: unknown }; if (typeof input.heading !== "string" || input.heading.trim() === "") { return Response.json({ error: "Enter a heading." }, { status: 400 }); } const config = { heading: input.heading.trim() }; const { metadata } = await api.getConfig("metadata"); await api.postConfig({ config, metadata: { ...metadata, complete: true } }); return Response.json(config);});The executor reads the settings with api.getConfig("config"). Validate them: the result is undefined when nothing valid is saved.
Settings belong to one vertex instance. Credentials and shared settings belong in services.
Programs
Section titled “Programs”runtime.json groups vertices into programs. The vertices in a program share one bundle and its limits:
{ "executors": [ { "vertices": ["greet", "ticket_form"], "runtime": { "runtime": "js_1.0", "jsCompatibility": "node24" }, "maxMemoryMb": 64, "wallTimeSec": 30, "cpuTimeMs": 100 } ]}Each vertex belongs to one executor program, and each vertex with a settings page also to one program under configurators. Give a vertex its own program to isolate it, or to give it other limits. Measure your use before you change the limits.