How the platform works

Air-Cloud is the backend you build a product on without leaving it. Data, end-user sign-in, functions, releases, mail and the public front door come already wired together, and one CLI, aircloud, drives them from a product directory in a conventional shape. The point is the integration: the pieces know about each other, so you write your product, not the glue between services.

This page explains the ideas the other guides assume. Each section links to the guide that puts it to work.

Your account, your products, and their tenants

• Your account is you, the Builder. aircloud signup creates it and aircloud login signs you in to it (Getting started, Logging in).
• A product is one repository and everything it runs: its data, its functions, its site, its end users. aircloud products lists your account's products.
• Each product is its own tenant of the platform: a hard boundary. One product's data, end users, secrets and keys are never reachable from another product, yours or anyone else's.
• Environments. A product runs one release per environment. Every product has production; other environments are previews you activate releases in (Releases and environments).

The organization tree

Inside a product, your end users live in an organization tree that you shape: nodes with paths such as /org, /org/staff and /org/customers. Each end user holds a membership homed at a node, with role keys from your vocabulary; one person may hold several, each at its own node.

The tree decides what a request reaches. By default a session reads and writes the records of its node and of every node below it, and manages members at or below its node, conferring only roles it holds itself. An entity can narrow that to the records each user owns, open records kept higher up for reading, or hide and freeze fields record by record. Profiles, grants, groups and denies add roles at other nodes or take them away. The platform reads all of it on every request, never from the token (How authorization works, Owner and shared entities, Members, roles and registration).

Every request acts at one node

Whatever starts it, a request acts at exactly one node, and what it reads, writes, sends and is billed for is at that node:

• a session acts at the home of the end user's selected membership;
• a public route, an event trigger and a cron trigger act at the org_path they declare;
• aircloud functions invoke acts at your own node, or with --at <node> at a node at or below it.

A route or trigger with no end user must declare its org_path: aircloud check refuses one without it (route.org_path_required, trigger.org_path_required). Writing org_path = "/" is the explicit choice to act at the root, over every customer; nothing defaults to it. A function may then narrow to a node below the one it was declared at — a nightly sweep declared at a parent visits each client in turn — and never widen (The acting node and elevation).

Staff and customers

Your product's end users are not you. Your Builder identity runs the product; your end users use it. Even your own first admin account in the product is a separate end-user identity, invited at your declared admin node.

Among end users, a common split is staff — people who run the product with you — and customers — people who use it. aircloud generate authentication writes that convention: roles admin, staff and customer, a base profile for each, admins at /org, staff invited, and, with open registration, customers signing themselves up at /org/customers with the customer role. Staff are not owner-scoped by default, so they see every customer's orders while each customer sees their own (Members, roles and registration).

B2B2B: your clients get the same structure

If your product serves other businesses, each of your clients is a node of the tree, such as /org/acme, with an admin of its own who invites and manages Acme's people below that node. Acme's people see Acme's data and never another client's, because the tree, not your code, draws the line. You pass the platform's structure on to your clients instead of rebuilding it: that is what B2B2B means here.

A client node comes into being in one of three ways:

• you create it with aircloud org nodes create /org/acme, then invite its admin with aircloud members invite ada@acme.example --path /org/acme --scopes tenant:org --profile admin --profile-node / (Members, roles and registration);
• your code creates it: a function that declares the tree operation nodes.create creates nodes below the node it acts at (The acting node and elevation);
• the client creates it: with workspaces declared, any signed-in end user creates a company of their own and becomes its admin (Workspaces).

The client's admin can in turn manage Acme's own sub-nodes, profiles, groups and denies, the same way you manage yours, and never above Acme's node. Archiving a client's node suspends everything acting there until you unarchive it.

The motors you meet

The platform is built from a set of engines, called motors. These are the ones a product uses today:

• Air-Deploy — the product and its releases. The CLI, the conventional product layout, the generators, aircloud check, and releases that build, test and activate your product per environment. Also the AI-Skill and the dev MCP server that teach your coding agent all of this (Releases and environments, The AI-Skill, The dev MCP server).
• Air-Flex — your data. You declare entities in db/schema/<entity>.toml; Air-Flex stores and validates the records, enforces required fields, enum values, defaults, owners and the tree's boundaries at one chokepoint that your code cannot skip (Owner and shared entities).
• Air-Auth — sign-in and members. End users sign in on the platform's hosted login, never on a password table of yours; roles and registration are declared in config/routes.toml (Members, roles and registration, Routes).
• Air-Functions — your code. Functions run sandboxed, behind a route, on a schedule or on an event, and reach data, secrets and mail only through the platform's capabilities (Logs and invoking functions).
• Air-Reflect — screens from your schema. The site's resource pages render lists, details and forms from your entity declarations, so a field you add appears without copying it into a page.
• Air-Edge — the public front door. TLS, the web application firewall and rate limits sized by your plan, in front of every product host.
• Air-Comms — mail. The platform sends your end users' sign-in and verification mail, and a function can hand mail to it through its mail capability.
• Air-Billing — plans and metering. Every metered action (a query, a record write, an invocation, a mail send) is counted against your product's plan (see below).

Other motors are planned and not available yet: object storage (Air-Blob), analytics (Air-Insights), outbound connectors (Air-Connect), declarative automation flows (the flow generator is reserved and refuses), and billing your own customers through your own payment provider.

Plans and allowances

Every product runs on a plan. The plan declares, per metered action, how much is included and what happens past it: the action is refused with a typed error, or a warning to upgrade is raised, or the overage is counted, as the plan declares for that action. Your account's first products draw a free allowance.

Mail is one such action. A free monthly allowance of 100 platform mail recipients per product is planned: today the default plan includes no mail sends of its own. The sign-in and verification mail the platform sends to your end users is not one of your sends and will not count against that allowance.

Sovereign infrastructure

Air-Cloud runs on infrastructure the platform operates itself, not resold from a cloud provider: its own servers, its own keys, its own mail egress. For you it means the platform is not reselling another provider's services at a margin, which is what lets it bundle everything into one product, and that the keys signing what you install are held by the platform alone (Installing and verifying the CLI). You do not need to do anything about it; it is what makes the all-in-one affordable.