ADR-0027: Tenancy Model — Platform, Organization, Project

Status:

Accepted

Date:

2026-10-09

Supersedes:

ADR-0004: Tenancy Model — Organization, Customer, Project

Context

ADR-0004: Tenancy Model — Organization, Customer, Project modelled one installation as one organization (the operating shop) serving customers, each with projects. The customer is the isolation boundary.

That vocabulary assumes a single shop selling to clients. Ballet is also run by independent teams and companies sharing one installation, and each of them thinks of itself as an organization, not as somebody’s customer. The top-level entity a person works in should carry that name. The installation-wide level still exists — its operators, shared skills, the global pause and kill switch — but it is not a tenant.

Decision

A Ballet installation is the Platform. The platform hosts many Organizations; organizations have Projects.

  • The organization (formerly customer) is the hard isolation boundary for tickets, runs, knowledge, credentials, budgets and organization-scoped skills. All projects of an organization share one knowledge space.

  • The platform (formerly organization) holds what is installation wide: platform-scoped skills, role bindings at platform scope (role platform-admin, formerly org-admin), the global pause and kill switch, agent pools.

  • Roles: platform-admin (platform scope), organization-admin (formerly customer-admin), engineer, approver, viewer.

  • The rename is complete: domain, database, REST paths (/api/v1/organizations/{organization}), run-token claims, service headers, metrics labels, configuration, UI and documentation. Nothing was released before it, so no aliases are kept; database migrations rewrite existing data.

Alternatives Considered

Rename in the UI and documentation only

Advantages:

  • Small change.

Disadvantages:

  • Two vocabularies forever: the API, data, logs and metrics would say customer while people say organization.

Keep the installation level as “Organization”, call tenants something else

Advantages:

  • No change to the installation level.

Disadvantages:

  • The name people expect for their tenant stays taken by a level they never see.

No named installation level

Advantages:

  • One level fewer.

Disadvantages:

  • Shared skills, platform operators and the global kill switch still need a scope; leaving it unnamed makes authorization harder to read.

Decision Criteria

Matching how users name their tenant, one vocabulary across all layers, keeping the isolation guarantees of ADR-0004 unchanged.

Rationale

Only names change: the three levels, the isolation boundary and the authorization rules stay as ADR-0004 and ADR-0006: OIDC Claims-Based RBAC for Humans, Scoped Run Tokens for Agents define them. A complete rename before the first release is cheaper than carrying two vocabularies.

Consequences

Positive

  • Users work in organizations; operators administer the platform.

  • One vocabulary in code, data, API, metrics and documentation.

Negative

  • Breaking change for API clients, configuration (rbac.bootstrap_platform_admins), dashboards and scripts.

Risks

  • A missed rename leaves mixed vocabulary. Mitigation: the rename is checked by searching the repository for the old terms.

References