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
ctxobject
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 app | External app | |
|---|---|---|
| Users | Organization members (same accounts) | The app's own user system |
| Typical use | Internal reporting, approvals, department tooling | Customer portals, supplier collaboration, public forms |
| User management | Handled by organization member management | The Users tab in the Builder |
| Available SDKs | All, including roles and approvals | Excludes the internal-only role and approval SDKs |
| Extra file | — | src/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.
| Tool | What it does |
|---|---|
| Compile check | Runs the build pipeline to confirm the code compiles |
| Type check | Runs TypeScript type checking (tsc --noEmit) |
| Action static analysis | Detects undefined names, verifies ctx SDK methods exist, warns about blocking patterns |
| Real test run | Actually executes an action in the development environment and shows real output |
| Execution logs | Reads action execution records to self-correct |
| Runtime errors | Reads front-end errors captured from real users |
| Table tooling | Inspects and manipulates custom table structure |
| Submit release | Files 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.