The App Builder

The App Builder is the development environment for Custom Apps — a complete cloud IDE covering source editing, live preview, type checking, real test runs, and the release workflow.

Entry point: Dashboard → AI Applications → App Builder. Requires builder.access.


What a Custom App is

A Custom App is a self-contained application with its own source code, its own dedicated URL, its own data authorization scope, and its own runtime identity.

Technically it has two halves:

  • Front end — React/TypeScript, compiled and loaded into the platform's runtime. Entry point is src/App.tsx
  • Server-side actions — Python, executed in an isolated server environment, reaching platform capabilities through the ctx object

The front end handles the interface; actions handle anything requiring privilege or secrecy. The platform SDKs connect the two.


Two access modes

Access mode is chosen at creation and determines where users come from:

Internal appExternal app
UsersOrganization members (same accounts)The app's own user system
Typical useInternal reporting, approvals, department toolingCustomer portals, supplier collaboration, public forms
User managementHandled by organization member managementThe Users tab in the Builder
Available SDKsAll, including roles and approvalsExcludes the internal-only role and approval SDKs
Extra filesrc/auth.ts (sign-up and sign-in)

There is also a third form: Self-Built — third-party systems that skip the Builder entirely and reach platform data with an API key. See Chapter 11.


Starting points and the app marketplace

When creating an application you can either:

  • Start from a marketplace template — curated applications covering common business scenarios, installable as-is or as a base for customization
  • Start blank — minimal scaffolding only

Marketplace templates double as the best learning material — they demonstrate real SDK usage.


Builder tabs

Develop

Source editing with live preview.

  • File explorer — the application's source tree. Changes autosave; Ctrl+S saves manually
  • Editor — syntax highlighting; the preview refreshes on change
  • AI development assistant — describe what you want in natural language and the assistant writes and inserts the code; or select code and ask it to modify, debug, or optimize

The assistant does more than generate code — it holds a set of tools that actually verify its output (see below). That is its main difference from generic code generation.

References

Declare which built-in ERP tables this application may access, which columns, and which operations. This is the first layer of data authorization (Chapter 10).

The references panel embeds a data browser, so you can inspect real rows from a referenced table without switching to the Data Center to check column names.

Services

Management of server-side actions — create, edit, test — plus App Secrets (API keys and other confidential values).

External Services

Which external APIs this application may call. The platform uses a domain allowlist; unauthorized domains are unreachable. This is the application's only outbound channel (Chapter 12).

Scope

Declare and review which platform capability groups the application needs, and their approval status. This is the second layer of data authorization (Chapter 10).

Schedules

Configure scheduled tasks for this application — actions that run automatically without anyone using the interface (Chapter 9). The tab is always visible; before release it explains the prerequisites.

Publish

Version submission and go-live. Each release records a version number and changelog; depending on permission it either publishes directly or submits a request for review (Chapter 10).

Users (external apps only)

Manage the application's external users — create accounts, change emails, reset passwords.


The assistant's verification tools

This is where the Builder differs most from generic AI code generation: the assistant doesn't just produce code, it verifies it.

ToolWhat it does
Compile checkRuns the build pipeline to confirm the code compiles
Type checkRuns TypeScript type checking (tsc --noEmit)
Action static analysisDetects undefined names, verifies ctx SDK methods exist, warns about blocking patterns
Real test runActually executes an action in the development environment and shows real output
Execution logsReads action execution records to self-correct
Runtime errorsReads front-end errors captured from real users
Table toolingInspects and manipulates custom table structure
Submit releaseFiles a publish request on your behalf

The test run deserves emphasis: an action can be genuinely executed before release, hitting real permissions, real data, and real external services. That sharply reduces the "it compiled but exploded on first run" class of failure.


Application file structure

src/
  App.tsx           ← front-end entry point
  api.ts            ← custom table SDK (platform-provided)
  db.ts             ← ERP table SDK (platform-provided)
  action.ts         ← action invocation SDK (platform-provided)
  approval.ts       ← approval SDK (platform-provided, internal only)
  user.ts           ← user context SDK (platform-provided, internal only)
  auth.ts           ← sign-up / sign-in (platform-provided, external only)
actions/
  manifest.json     ← action registry and settings
  <action_name>.py  ← individual actions
  _shared/          ← code shared between actions

The SDK files under src/ are provided and maintained by the platform and should not be modified. They are the subject of Chapter 8.


A front-end styling constraint

Custom App front ends load in an isolated environment, which introduces one rule you must know: the :root selector does not apply to CSS variables there.

Always define CSS variables with both selectors:

:host, :root {
  --primary-color: #2563eb;
}

Styles written with :root alone will look correct in preview and silently fail once loaded. The same rule applies to dark-mode variable definitions.


Pre-release checks

The platform proactively detects configuration gaps before release, including:

  • Code calls an external service that isn't authorized (its domain is not on the allowlist)
  • The release has fewer actions than the previous version (possible accidental deletion) — requires explicit confirmation

Both are blocked at release time with an explanation, rather than failing in front of users after go-live.