Skip to content

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.

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.

  • 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.

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:

src/greet/metadata.json
{
"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": []
}
src/greet/executor.ts
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.

  1. When the flow reaches the vertex, Adapt calls onStart.
  2. While it runs, Adapt calls onExchange when an exchange has an update, and onCron on schedule. Browser and External vertices also handle requests.
  3. The vertex completes when it calls send() on a standard or failure transmitter, or send() 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.

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.

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:

src/greeting/configurator.ts (excerpt)
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.

runtime.json groups vertices into programs. The vertices in a program share one bundle and its limits:

runtime.json (excerpt)
{
"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.