# Control plane

Identity, money, licences, the install fleet, the app-store review queue and moderation — everything Leumas does to or about its customers.


**What Leumas does TO or ABOUT its customers.**

Identity, money, licences, the install fleet, the app-store review queue, the release feed, and
moderation of what customers publish to Leumas-hosted services. If it is Leumas acting *on* a
customer, it is here.

Companions: [PLATFORM.md](PLATFORM.md) · [APPLIANCES.md](APPLIANCES.md)
Execution: [ops/todos/leumas-consolidation-roadmap.md](ops/todos/leumas-consolidation-roadmap.md)

---

## Two things, not one

This is the distinction that matters, because getting it wrong produces a console customers have to
talk to:

| | **Central services** | **The console** |
|---|---|---|
| Host | `api.leumas.tech` | `admin.leumas.tech` |
| Role | `LEUMAS_ROLE=platform` | `LEUMAS_ROLE=control` |
| Who reaches it | everyone — every Studio, iOS, leumas.tech, every browser | **Leumas staff only** |
| What it is | login, memberships, app store, relay, analytics ingest, release feed | a **window over the same data** |
| Exposure | public | edge-restricted |

Same binary, same database, different `LEUMAS_ROLE`. The console stores nothing of its own.

> **A customer's browser or Studio never contacts `admin.leumas.tech`.**
> When a flow needs a customer to visit a Leumas page, that page is on `leumas.tech` and it calls
> `api.leumas.tech`.

Staff-only is a *second axis*, not a bigger role: `admin` means "administrator of an instance",
`leumas_staff` means "works for Leumas". A customer who is an admin of their own Studio is not staff.
`pnpm check:staff` enforces the split.

---

## What it owns

| Job | Why it must be central |
|---|---|
| **Leumas identity** | one account across leumas.tech, iOS, and every self-hosted Studio |
| **Memberships & Stripe** | one billing relationship per customer |
| **Licences** | what an appliance is entitled to run, revocable |
| **The install fleet** | every Studio that has phoned home — version, health, activity |
| **The app store** | submissions, review, signing, distribution |
| **Releases** | the feed every appliance polls to update itself |
| **Ecosystem analytics** | rollups across installs |
| **Social & marketplace moderation** | content on Leumas infrastructure, under Leumas terms |

An appliance's only phone-home is a licence heartbeat carrying a key and an instance id. **It stays
that way.** The lever against a bad self-hoster is revoking their licence, not watching their machine.

---

## How it relates to the other two

```
 CONTROL ── issues licences, bills, reviews apps, publishes releases ──-> APPLIANCES
      │                                                                          │
 │ <-──────────────── licence heartbeat (key + instance id) ─────────────────┘
      │
      └── serves the identity + money API that PLATFORM's public pages call
```

The control plane is the only plane that is **not** a product anyone else can run. Everything else
ships; this stays home.

---

## The boundary rule

> Things *Leumas* does **to or about** its customers → **control plane**.
> Anything a *customer* does on their own instance → **Studio** ([APPLIANCES.md](APPLIANCES.md)).

If a tenant admin would legitimately use it on their own appliance, it is not a control-plane surface.

---

Detail — topology, security posture, the console's domains, per-job design:
[ops/reference/control-plane-detail.md](ops/reference/control-plane-detail.md)


---
Source: CONTROL-PLANE.md
Canonical: https://docs.leumas.tech/p/architecture/control-plane