Skip to main content
An app is a separately deployed service that a Voyant deployment activates through OAuth. It is the second of the two customization seams, alongside adapters and providers. The defining property is where the code runs. An app runs entirely outside the Voyant process. It never contributes migrations, routes, providers, or any other executable server code to the deployment. An app may publish an immutable, declarative release artifact so it can be acquired and installed, but that artifact is never executable code and never a deployment graph unit. That constraint is the point. It is what lets a deployment install something built by someone else without giving it the ability to change how the platform itself runs.

​
When to build an app

Build an app when the integration:
  • has its own deployment, release cycle, and operational ownership
  • talks to a system that stays authoritative for its own data, such as an accounting ledger or a CRM
  • should be installable, pausable, and revocable by the operator without a platform release
  • should not be able to run code inside the deployment
Accounting and CRM integrations are the canonical examples. SmartBill is an app. If the integration needs to run inside the process — swapping a payment provider, resolving object storage, changing how a module behaves — it is an adapter, provider, or extension instead.

​
How an app integrates

An app has five seams, and no others:

Scoped APIs

The app calls the deployment’s APIs with the scopes granted at installation. Grants are explicit and revocable.

Events

The app reacts to domain events emitted by the platform’s modules.

Durable webhook subscriptions

Delivery survives the app being down. The deployment retries rather than dropping.

Namespaced custom fields

The app owns its own custom fields under its namespace, so its data does not collide with the operator’s or another app’s.

Sandboxed admin extensions

The app can render surfaces inside the admin without running in it. See Build an admin UI extension.

​
Lifecycle

The deployment-local runtime for apps lives in @voyant-travel/apps. It owns:
  • Registration — the app becomes known to the deployment.
  • Immutable declarative releases — a release artifact describes what the app asks for. It is declarative and versioned, so what was consented to cannot change underneath the operator.
  • Consent — the operator sees what is being requested before anything is granted.
  • Installation and grants — the scopes actually given, which may be narrower than what was requested.
  • Pause, revoke, uninstall — the operator can stop an app at any point without a platform release, and revocation is immediate.
Because consent is tied to an immutable release, an app that wants more access has to publish a new release and ask again.

​
Apps on Voyant

On Voyant, apps are distributed through the app marketplace: an app is reviewed and admitted before it can be acquired, and acquisition connects it to a deployment. Self-hosted Voyant OSS deployments use the same app runtime and the same install, consent, and revoke model, without the marketplace distribution around it.

Adapters and providers

The other seam: changing an implementation inside the deployment.

Admin UI extensions

Rendering an app’s surface inside the admin.

App compatibility

What an app can rely on across deployments and versions.

Consume a deployment's API

The API surface an app calls.