App Studio

This section is for developers building revenexx Apps — either a custom app for one customer's specific needs, or a public app any tenant can install from the Marketplace. In the Cockpit, merchants discover, install and manage apps in App Studio; this section is the developer's side.

What an App is

An App is one Node function plus a set of declarative JSON contracts.

The function holds your logic. The contracts tell the platform what data you own, what HTTP operations you expose on the public API, what you are allowed to reach, what the Cockpit should render, what a merchant can configure, and how the app is listed. The platform reads the contracts and provisions the rest.

An App has no front end of its own. Buyers reach its logic through a storefront, and the storefront reaches the App only through the capabilities it publishes on the API. Which work belongs on which side, and how the two connect, is on Apps and Sites.

Every app ships the same eight files — six required, two optional:

The authoritative JSON Schema for each is served at https://schemas.revenexx.com/<name>.schema.json. Point your editor at them.

Apps cannot break each other

You do not have to check whether your app overlaps with anyone else's. Your tables are namespaced by vendor and app, your routes live under your own prefix, nothing reaches your code except through the gateway, and another app can only touch you through a capability grant the merchant consented to. There is no hook chain and no load order. Why apps cannot collide walks through the boundary and is honest about where apps do meet.

What you do not write

• Migrations. The platform diffs your schema.json against what is deployed. Changes are additive; removals need an explicit tombstone.
• Tenant filters. Your reads and writes only ever see the calling tenant's rows, enforced by the platform rather than by your code.
• Endpoint plumbing. A capability's declared route is served verbatim under https://api.revenexx.com/v1, and the same declaration produces the OpenAPI document, the SDK methods, the API Explorer entry and the MCP tool.
• Admin UI components. cockpit.json declares list, detail and form views; the Cockpit renders them with built-in renderers.
• A settings screen. settings.json becomes a Cockpit form, and the platform resolves each value per market.

How this section is organised

Five groups, in the order you meet them while building.

Data model and the typed client — everything about the tables your app owns and the client you read and write them with. Column types, relationships, tenant isolation, migrations, scoping, the query surface, adapters, and the two optional projection files.

Your app's API — how the routes you write become the public gateway surface. Capabilities, the capability field reference, the router, CRUD, pagination, errors, caching, calling another app, overriding another app's capability, tags, and the published OpenAPI document.

Platform services your app can reach — the access register. One page per grant kind, plus the declarative events you emit and receive, scheduled work, person-level permissions, and tracing. It is explicit about which grants are proven in production and which are not.

The Cockpit admin UI — that your app declares its UI rather than shipping it, what settings.json can express, and how your function reads a resolved setting at runtime.

Ship, publish and operate — the manifest reference, private versus Marketplace, versioning, dependencies, validation, deploying, publish and install, billing, consent, testing, verifying against the live gateway, and the App Studio screens you operate the app from.

What you would build with this

A serial-number registry for medical devices. Serials follow a device from receipt through sale into service. You declare a device_serials entity, a handful of capabilities for registering and looking one up, and a Cockpit list and detail view. Operators use it like any built-in app.

A compliance app for chemicals. Safety data sheets attached to products, hazmat rules enforced at checkout, regulatory reports. You declare your own entities, a settings page for the rules, and a capability the checkout calls.

An ERP-backed stock replacement. The customer's stock lives in SAP. You do not fork the inventory app — you declare implement on the inventories.availability capability, and your app takes over exactly that one route for that tenant while all stock-keeping CRUD stays standard. That override mechanism is the reason the app model exists.

Custom app or Marketplace app

manifest.type decides, and it is required:

• private — only the owner tenant may install and invoke the app. Never listed in the Marketplace. This is the custom app you build for one customer.
• public — once the operator publishes it, any tenant may install it. Listed in the Marketplace.

This is independent of billing.json, which is pricing only. See Private or Marketplace.

Related

• App SDK — the typed data client and the router your function uses.
• API usage — the headers, errors and conventions every call to api.revenexx.com follows.
• CLI reference — revenexx create app, revenexx deploy app and the lower-level app commands.
• Build your first App — the same ground as a long-form tutorial.

Where to go next

If you have not read Platform overview, start there. Otherwise run Your First App in 15 Minutes and have something answering on the gateway before you read any reference page.