Architecture Overview

Read this when one app or one storefront is not the whole job. This page is for solution architects and senior developers scoping a larger project, evaluating revenexx, or working out where a request goes when something breaks. Writing a single app? The App Model Concept is enough on its own.

You get the system rather than the tour or the vocabulary, in three layers: who touches which surface, the building blocks you work with, and how a real request flows from the storefront to the data and back.

At a glance

The platform stacks like this, top to bottom: the six Studios you build in, the API gateway every request passes through on behalf of exactly one tenant, and the platform services behind it — identity, search, storage, messaging and events.

Layer 1: who touches which surface

The same four audiences the Platform Overview introduces reach the platform through different front doors. Knowing which door a piece of functionality sits behind is the fastest way to find your way around.

External systems sit at the edge: the customer's ERP, PIM, and CRM (SAP, Salesforce, Salsify, …), reached through Integration Studio.

Layer 2: the building blocks

Everything you build sits on a small set of public building blocks.

What you build in

• Cockpit — the admin UI. It's composed at runtime from the cockpit.json extension points your installed apps declare; there's no central UI that hard-codes specific apps.
• Commerce Studio — catalog, pricing, orders and checkout. These are apps themselves, built on the same app model as yours, which is why your app can extend them rather than work around them.
• Experience Studio — storefronts. A deployed storefront is a site; the code it runs is a theme, and the commerce data it shows lives in the tenant, not the site.
• App Studio — where revenexx Apps run. Each app is its declared data model plus optional UI and code.
• Integration Studio — the workflow builder for cross-system integrations (see Integration Studio).
• Analytics Studio — self-service dashboards over the customer's own data. There is no public analytics API; what you ship is an analytics.json in your app.
• AI Studio — agents and automation over your tenant's data, growing in autonomy. A Cockpit preview today, with no public API: don't build against it. See AI Studio.

What the platform handles for you

You reach all of these through the API gateway at api.revenexx.com — one entry point, every request scoped to a tenant.

• ID — sign-in for customer and partner users.
• Search — full-text and faceted search over a tenant's collections.
• Storage — per-tenant file storage; serve and transform files from your own domain.
• Messaging — transactional and marketing email.
• Events — emit business and platform events; react to them with webhooks.

You don't run or wire any of this together. You call the gateway with your tenant and credentials, and the platform operates them for you: identity, search, storage, messaging and event delivery. Each is scoped to the tenant on the request, as its own bullet above says.

Layer 3: how a request flows

The model only clicks once you trace a real request. Three examples, each showing a different aspect.

A buyer places an order

The buyer has products in their cart and clicks Checkout. The storefront's server collects the cart, validates the buyer's session, and calls the Orders app. The Orders app reads and writes the tenant's data — automatically scoped, so it only ever sees this customer's orders.

The order is written and an order.created event goes onto the event stream. What happens next — reserving stock, sending the confirmation, telling the ERP — runs as subscribers you wire up, not as something the Orders app does for you. Each route does one thing and the orchestration is yours, because the right sequence differs per merchant. The buyer sees the confirmation page.

The point: nothing in that trace filters by tenant. The Orders app doesn't implement isolation and neither will yours — the section below says what does.

A scheduled ERP sync

At 02:00 a scheduled Integration Studio workflow fires. It fetches yesterday's order changes from the customer's SAP system, reshapes the payload into revenexx's order format, and posts the updates back. If SAP is briefly down, the node retries automatically — three attempts with exponential backoff by default, and you write none of that. If the retries are exhausted the run stops and waits for a person: in Cockpit they either retry it from the top or resume it from the failed step. Retrying from the top re-runs steps that already succeeded, so a workflow that writes needs to be idempotent. The whole run is visible under Integration Studio → Runs, step by step.

A live price lookup

A buyer opens a product page that needs contract-specific pricing, computed live in the customer's ERP. The storefront starts a synchronous workflow and waits on it: the workflow hits SAP's pricing endpoint, transforms the response, and returns it.

This is the same engine and the same durable run as the nightly sync — there is no separate fast path. The only difference is whether the caller waits. A workflow's execution_mode sets who may decide that, and where it allows either, the entry point does: a webhook call waits by default, a run created directly does not. Past 30 seconds the caller gets a 504 while the run carries on to its real outcome — so never read that timeout as "it didn't happen". See Execution modes.

Multi-tenancy: you only ever see your tenant

This is the design choice that affects you most. Every request names its tenant with the X-Revenexx-Tenant header, and data is automatically scoped to that tenant.

The header selects the tenant. It does not grant access to it. Both are checked at the gateway before anything else runs. An API key identifies one tenant, so it cannot be pointed at a second. A signed-in person's token identifies the person, and naming a tenant they are not a member of is refused with 403 not a member of this tenant — not answered with another tenant's data. A request carrying no header at all is rejected with 400 missing X-Revenexx-Tenant; there is no "default tenant". See Authentication.

The scoping itself is not something each app implements. The platform injects tenant_id and org_id into every table you declare, indexes them, and applies the filter beneath the query — so there is no query you can write, from your function or from the generated client, that forgets it. Tenant isolation has the columns and what each operation does.

What this means in practice: you never write tenant filters, you can't accidentally omit one, and you can't reach another tenant's data even if your app has a bug.

A second boundary, and a weaker one. What an app may do inside the tenant it is installed in is permissions, not tenant isolation — and six of the nine permission classes are declared but not yet enforced. The strength of the paragraph above does not carry across to that one.

What's next

• Quick Start — the one to do next: build something hands-on, about 15 minutes.
• App Model — the conceptual deep-dive if you're writing an app.
• Execution modes — sync vs. async, and what has to be true before a workflow runs.