# 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](getting-started.md), [Logging in](login.md)).
- **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](releases.md)).

## 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](authorization.md),
[Owner and shared entities](entities.md), [Members, roles and registration](members.md)).

## 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](acting-node.md)).

## 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](members.md)).

## 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](members.md#nodes));
- **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](acting-node.md#managing-the-tree-from-a-function));
- **the client creates it**: with workspaces declared, any signed-in end user creates a company of their own and
  becomes its admin ([Workspaces](workspaces.md)).

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](releases.md),
  [The AI-Skill](ai-skill.md), [The dev MCP server](mcp.md)).
- **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](entities.md)).
- **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](members.md), [Routes](routes.md)).
- **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](functions.md)).
- **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](install.md)). You do not need to do anything about
it; it is what makes the all-in-one affordable.

---

Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e.