openova/docs/GLOSSARY.md

# Glossary

> **Status:** Canonical. Single source of truth for OpenOva terminology AND for banned terms forbidden in code/docs/UI.
> **Updated:** 2026-05-20.
> **Note:** Terms here describe the agreed model. For which terms map to currently-implemented code vs design-stage, see [`STATUS.md`](STATUS.md).

Every other document defers to this file. When a term in another doc looks contested, this file wins. New terminology is proposed here first, then propagated. The Banned-terms section (§Banned terms below) is also authoritative: there is no separate `docs/BANNED-TERMS.md`.

---

## Core nouns

| Term | Definition |
|---|---|
| **OpenOva** | The company. Authors and maintains Catalyst, Blueprints, and the openova.io services. Used as a brand prefix in product names (e.g. "OpenOva Catalyst", "OpenOva Cortex"). When unqualified, "OpenOva" refers to the company; when referring to the platform itself, prefer **Catalyst**. |
| **Catalyst** | The OpenOva platform itself. A self-sufficient Kubernetes-native control plane. Composed of: console, marketplace, admin, catalog-svc, projector, provisioning, environment-controller, blueprint-controller, billing, identity, secret, event-spine, gitea, observability. See "Catalyst components" below. Published from this repository as signed OCI Blueprints. |
| **Sovereign** | One **deployed** instance of Catalyst on Kubernetes infrastructure chosen by its owner. Self-contained; never depends at runtime on any other Sovereign. Examples: `openova` (run by us, hosts our SaaS Organizations — formerly "Nova"), `omantel` (run by Omantel, hosts SME Organizations across Oman), `bankdhofar` (run by the bank, hosts internal Organizations). |
| **Organization** | The multi-tenancy unit inside a Sovereign. Has billing, Users, Environments, private Blueprints. Ahmed's pharmacy is one Organization on the `omantel` Sovereign; `digital-channels` is one Organization on the `bankdhofar` Sovereign. |
| **Environment** | An env-typed scope where Applications run. Named `{org}-{env_type}` where `env_type` is one of `prod | stg | uat | dev | poc` (per [`ARCHITECTURE.md`](ARCHITECTURE.md) §2.4). **Logical** concept; can span multiple regions and building blocks via Placement. Realized as a **branch** (`develop`/`staging`/`main`) inside each Application's Gitea repo, plus one or more vclusters per Placement spec. Examples: `acme-prod`, `acme-dev`, `bankdhofar-uat`. |
| **Application** | What a User installs into an Environment from a Blueprint. The user-facing object: an App Store-style card representing a running deployment (e.g. WordPress, Postgres, an internal microservice). **Each Application is realized as one Gitea repo** at `gitea.<location-code>.<sovereign-domain>/<org>/<app>` under its owning Organization. Branches `develop`/`staging`/`main` map to the `dev`/`stg`/`prod` Environments. The repo is the unit of CODEOWNERS, branch protection, webhook, and CI — giving every team self-sufficient ownership of their Apps. |
| **Blueprint** | The reusable, OCI-published, signed unit of installable software. Unifies what previously was split between "module" (primitive) and "template" (composition). A Blueprint can declare dependencies on other Blueprints, with arbitrary depth. Visibility: `listed` (catalog card) / `unlisted` / `private` (Org-scoped). Source layout: see [`RUNBOOKS.md`](RUNBOOKS.md) §2. |
| **User** | A person. Authenticates via Keycloak. Belongs to one Organization (or has cross-Org admin scope as `sovereign-admin`). |
| **Voucher** | A redeemable code that grants billing credit when applied at checkout. Issued by `sovereign-admin` (per-Sovereign campaigns) or `org-admin` (rare; intra-Org credit grants). The user-facing label for what the code calls `PromoCode` (see `core/services/billing/store/store.go`). Vouchers are the user-acquisition surface for franchised Sovereigns: a Franchisee mints codes, distributes them through their marketing channels, and a redeemer's first checkout converts the code into Organization credit. Lives as a row in the per-Sovereign billing Postgres database; soft-delete (`deleted_at`) preserves the audit trail of past redemptions. See [`BUSINESS-STRATEGY.md`](BUSINESS-STRATEGY.md) §17 (Franchise model). |

---

## Roles

| Term | Definition |
|---|---|
| **`sovereign-admin`** | The role for Users who operate a Sovereign — configures the Catalyst control plane, manages the underlying clusters via Crossplane (which is platform plumbing, not a user-facing surface), onboards Organizations, sets Sovereign-wide policies. Omantel's cloud team and Bank Dhofar's platform team are both `sovereign-admin` on their respective Sovereigns. There is no separate entity-noun (rejected: "operator", "tenant", "client"). |
| **`org-admin`** | Role within one Organization — creates Environments, manages Users, sets Org-level policies. |
| **`org-developer`** | Role with Application install/configure rights inside specific Environments. |
| **`org-viewer`** | Read-only role within an Organization. |
| **`security-officer`** | Role with audit/policy/secret-rotation gating rights. Optional Org-level role. |
| **`billing-admin`** | Role with billing/invoice/quota rights. Optional Org-level role. |
| **`sme-end-user`** | Persona, not a role: an SME owner (Ahmed) for whom Organization onboarding is automatic on first signup. |
| **`Franchisee`** | Persona, not a role: the legal entity (telco, ISP, hyperscaler reseller, regional cloud operator) that owns and operates a franchised Sovereign under license from OpenOva. Examples: Omantel running `omantel.omani.works`, a regional reseller running `cloud.acme.example`. The Franchisee's staff hold the `sovereign-admin` role on their Sovereign and use the existing admin app (per `core/admin/`) to issue Vouchers, curate the `catalog-sovereign` Gitea Org, set marketplace branding, and pick the per-tier pricing they pass through to their tenant Organizations. Revenue split with OpenOva is governed bilaterally by the franchise contract — not a per-Sovereign config field. See [`BUSINESS-STRATEGY.md`](BUSINESS-STRATEGY.md) §17 (Franchise model). |

---

## Infrastructure

| Term | Definition |
|---|---|
| **Cluster** | A physical Kubernetes cluster. Named per [`docs/ARCHITECTURE.md`](ARCHITECTURE.md): `{provider}-{region}-{building-block}-{env_type}` — e.g. `hz-fsn-rtz-prod`. Owned by `sovereign-admin`. Never user-facing. |
| **vcluster** | A virtual Kubernetes cluster (loft.sh's vcluster) running inside a parent Cluster. One vcluster per Organization per parent Cluster. Named `{org}` within the parent (qualified globally as `{provider}-{region}-{bb}-{env_type}-{org}`). Implementation detail of an Environment; not user-facing. |
| **Building Block** | A functional security zone — `rtz` (restricted trust), `dmz` (edge), `mgt` (management). Stable across failovers. See `ARCHITECTURE.md` §1.3. |
| **Region** | Geographic location, provider-scoped 3-char code (`fsn`, `nbg`, `hel`). |
| **Env Type** | Environment dimension value: `prod | stg | uat | dev | poc`. Was `{env}` in older naming; renamed to disambiguate from the Catalyst Environment object. |
| **Placement** | Per-Application metadata declaring which regions and building blocks realize that Application. Modes: `single-region`, `active-active`, `active-hotstandby`. |

---

## Catalyst components (the control plane)

| Component | Purpose |
|---|---|
| **console** | Primary user-facing UI. Three depths: form view (default for SME), advanced view (default for corporate), in-browser Monaco IaC editor (toggle). All commits go to the relevant Application's Gitea repo (one repo per App). |
| **marketplace** | Public-facing Blueprint card grid (the "App Store"). |
| **admin** | Sovereign-level admin UI. Where `sovereign-admin` configures the deployment. |
| **catalog-svc** | Reads Blueprint CRDs (sourced from the public catalog mirror + the Sovereign-curated `catalog-sovereign` Gitea Org + Org-private `shared-blueprints` repos), serves catalog API to console + marketplace. |
| **projector** | CQRS read-side service. Subscribes to NATS JetStream, materializes per-Environment KV, serves SSE to console, handles Gitea webhooks (forces Flux reconcile on commit). |
| **provisioning** | Validates Application install requests against Blueprint configSchema, composes manifests, **creates one Gitea repo per Application** under the Org's Gitea Org, commits initial branches (`develop`/`staging`/`main`). |
| **environment-controller** | Reconciles the **Environment CRD**: creates the vcluster(s), bootstraps Flux inside (watching the appropriate branch across the Org's Application repos), wires the webhook, generates pull credentials. |
| **blueprint-controller** | Watches Blueprint sources (this monorepo + per-Sovereign Gitea Org-private repos), validates and registers Blueprint CRDs. |
| **billing** | Per-Org metering, invoicing. |
| **pool-domain-manager (PDM)** | Bootstrap-surface service that allocates pool subdomains under OpenOva-owned domains (`omani.works`, `openova.io`), creates the per-Sovereign PowerDNS zone, writes its canonical 6-record set, and updates the parent-zone NS delegation via a registrar adapter. Lives on the OpenOva-run Catalyst-Zero only, not on every Sovereign. CNPG-backed. Source: `core/pool-domain-manager/`. |
| **Registrar Adapter** | One of five PDM-internal clients (Cloudflare, Namecheap, GoDaddy, OVH, Dynadot) that flips parent-zone NS records via the registrar's API. Used by PDM for (a) pool sovereigns at the OpenOva Dynadot account and (b) BYO sovereigns in `byo-api` mode where the customer pastes a registrar token. |
| **identity** | Keycloak (per-Organization realm in SME-style Sovereigns; per-Sovereign realm in corporate-style) for human identity. Workload identity is Cilium WireGuard (kernel-layer east-west encryption) + K8s ServiceAccount TokenReview (audience-scoped 1h projected bound-tokens). SPIFFE/SPIRE was **deferred** from the canonical bootstrap-kit by founder PR [#665](https://github.com/openova-io/openova/pull/665) (2026-05-03); the `platform/spire/` chart is retained as opt-in. Re-introduction roadmap: TBD-V29 [#2055](https://github.com/openova-io/openova/issues/2055). See [`SECURITY.md`](SECURITY.md) §2 + [`STATUS.md`](STATUS.md). |
| **secret** | OpenBao + External Secrets Operator (ESO). Independent Raft cluster per region (no stretched cluster); cross-region perf replication is async. |
| **event-spine** | NATS JetStream — pub/sub + Streams + KV bucket. Workload-identity-scoped Accounts per Organization. Replaces what was previously specified as "Redpanda + Valkey" for the control plane. |
| **gitea** | Per-Sovereign Git server. Hosts five top-level Gitea Orgs by convention: `catalog` (read-only mirror of the public Blueprint catalog), `catalog-sovereign` (optional — Sovereign-owner-curated private Blueprints visible to every Org on this Sovereign), one Gitea Org per Catalyst **Organization** (each holding the Org's `shared-blueprints` repo + one repo per **Application**), and `system` (sovereign-admin scope: CRs, policy bundles, runbooks). |
| **observability** | Per-Sovereign OpenTelemetry + Grafana stack (Alloy + Loki + Mimir + Tempo + Grafana) for Catalyst's own telemetry. |

---

## Gitea Orgs (top-level Gitea namespaces)

A Sovereign's Gitea instance hosts five conventional Gitea Orgs. The unified rule: **one Catalyst Organization = one Gitea Org**, **one Application = one Gitea Repo**, regardless of SME or corporate scale.

| Term | Definition |
|---|---|
| **`catalog` Gitea Org** | Read-only nightly mirror of `github.com/openova-io/openova` synced by `bp-catalyst-gitea`. Public Blueprints visible to every Org on the Sovereign. |
| **`catalog-sovereign` Gitea Org** | Optional. Sovereign-owner-curated private Blueprints (e.g. an SME marketplace operator authoring `bp-wordpress`, `bp-jitsi`, `bp-cal-com` for their tenants). Visible to every Org on this Sovereign without being public upstream. Distinct from per-Org `shared-blueprints` (Org-scoped only). |
| **`<org>` Gitea Org** | One per Catalyst **Organization**. Holds: `shared-blueprints` (Org-private Blueprint authoring) plus **one Gitea Repo per Application** owned by that Org (e.g. `acme-pharmacy/store-frontend`, `core-banking/billing-rail`). |
| **`system` Gitea Org** | Sovereign-admin scope. Holds: `catalyst-config` (Sovereign / Organization / Environment / EnvironmentPolicy CRs), `policy-bundle` (Kyverno ClusterPolicies, Falco rules, RE Scorecard CRDs), `runbooks` (auto-remediation Runbooks). Edit access restricted to `sovereign-admin`; per-Org delegation possible via Catalyst RBAC. |

---

## Persona-facing surfaces

| Term | Definition |
|---|---|
| **UI** | The Catalyst console — full feature, three view depths. |
| **Git** | Direct push or pull-request to an Application's Gitea repo (branches `develop`/`staging`/`main` for dev/stg/prod), or to a Blueprint repo (`shared-blueprints` per-Org or `catalog-sovereign` Sovereign-wide). |
| **API** | Catalyst REST + GraphQL. Used for portal integrations (a customer's Backstage / ServiceNow / JIRA). Not a primary IaC authoring surface. |
| **kubectl** | Inside a User's own vcluster, for **debugging only**. Not a configuration surface. |
| **Crossplane** | **Platform plumbing**, never a user surface. Used internally by Blueprints to manage non-K8s cloud resources. Advanced users may author their own Crossplane Compositions and contribute them upstream as Blueprints. |

---

## Banned terms (do not use in any docs / UI / API / code / commit messages)

This section is the **single source of truth** for forbidden terminology. Cross-referenced by [`CLAUDE.md`](../CLAUDE.md), [`RUNBOOKS.md`](RUNBOOKS.md), [`DOD.md`](DOD.md), [`DOD.md`](DOD.md), and the user-global `~/.claude/CLAUDE.md`. There is no separate `docs/BANNED-TERMS.md`.

### Banned platform terminology

| Banned | Use instead | Reason |
|---|---|---|
| Tenant *(as platform terminology)* | Organization | Cloud-overloaded, ambiguous between Sovereign tenancy and Organization tenancy. |
| Operator *(as entity / person)* | `sovereign-admin` (the role) | Confused with the K8s Operator pattern. K8s Operators in the controller-pattern sense are still called Operators. |
| Client *(in product UX sense)* | User | Collides with Keycloak OIDC client. OIDC clients in technical contexts remain "clients", and K8s clients (`client-go`, etc.) are fine. |
| Module *(in Catalyst sense)* | Blueprint | Catalyst unifies modules + templates. Go modules, Terraform modules, Helm modules are exempt — they're external technologies. |
| Template *(in Catalyst sense)* | Blueprint | Same reason. K8s templates, prompt templates, scaffold templates are exempt — external technologies. |
| Backstage | Catalyst console | Backstage was decided removed from the platform. |
| Synapse *(as the OpenOva product)* | Axon | Matrix's Synapse server is fine when context is the chat server. |
| Lifecycle Manager *(as a separate product)* | Catalyst | Lifecycle management is one of Catalyst's responsibilities, not a separate product. |
| Bootstrap wizard *(as a separate product)* | Catalyst (or "Catalyst bootstrap" when referring to a phase) | Bootstrap is one phase of Catalyst provisioning, not a separate product. |
| Workspace *(as Catalyst scope OR component name)* | Environment / environment-controller | Renamed for industry alignment and to escape collision with VS Code / Slack / Backstage / Terraform workspaces. The controller previously named `workspace-controller` is now `environment-controller`. |
| Instance *(as user-facing object)* | Application | App Store metaphor. The CRD name remains internal. |

### Forbidden test domains

Test provs and tenant Organizations use the canonical pool zones defined in [`DOD.md`](DOD.md): `t<NN>.omani.works` (or `t<NN>.omantel.biz` if LE-rate-limited) for the Sovereign, and `<orgslug>.omani.homes` / `omani.rest` / `omani.trade` for tenant Organizations. The strings below are **forbidden** in any test command, screenshot, walk-script, code path, or doc that describes a test run:

| Forbidden | Why | Use instead |
|---|---|---|
| `openova.io` *(in test commands)* | `openova.io` is reserved for the mothership Catalyst-Zero. Tests must NEVER provision into `openova.io`. | `t<NN>.omani.works` |
| `omantel.openova.io` | Hallucinated subdomain — does not exist. | `omantel.omani.works` (real franchised Sovereign FQDN) |
| `Nova Cloud` *(as a product name)* | "Nova" was the predecessor brand to OpenOva. Never reintroduce as a current product. | `openova` (the Sovereign run by OpenOva) |
| `eventforge.io` | Hallucinated test app domain — does not exist. | The canonical demo app is **EventForge** installed under a real tenant Org slug, e.g. `eventforge.<orgslug>.omani.homes`. |
| `admin.<sovereign-fqdn>` *(as the voucher / billing surface)* | The legacy `admin.<fqdn>` URL is dead — BSS (voucher, billing, catalog, orders, tenants) lives inside the operator console at `console.<sovereign-fqdn>/bss`. | `console.<sovereign-fqdn>/bss` |

---

## Acronyms

| Acronym | Expansion |
|---|---|
| **OCI** | Open Container Initiative — registry artifact standard. Blueprints are published as OCI artifacts. |
| **CRD** | Custom Resource Definition — Kubernetes typed extension object. |
| **CQRS** | Command-Query Responsibility Segregation — write side (Git → Flux → K8s) vs read side (projector → JetStream KV → console). |
| **ESO** | External Secrets Operator. |
| **SPIFFE / SPIRE** | Workload identity standards. SVIDs are short-lived mTLS certs bound to K8s ServiceAccounts. **Deferred — opt-in only** per founder PR [#665](https://github.com/openova-io/openova/pull/665) (2026-05-03); canonical workload identity is now Cilium WireGuard + K8s SA TokenReview. Re-introduction roadmap: TBD-V29 [#2055](https://github.com/openova-io/openova/issues/2055). |
| **GSLB** | Global Server Load Balancing — handled at the authoritative DNS layer by PowerDNS lua-records (`ifurlup`, `pickclosest`, `ifportup`). See [`ARCHITECTURE.md`](ARCHITECTURE.md) §14 (Multi-region DNS topology). |
| **PromotionPolicy** | Removed concept. Replaced by **EnvironmentPolicy** attached to a destination Environment, enforcing PR/approval/soak/change-window rules. |

---

## See also

- [`STATUS.md`](STATUS.md) — what's built today vs what's design-only.
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — concrete naming patterns for every object type.
- [`DOD.md`](DOD.md) — Sovereign / tenant-Org FQDN patterns + forbidden test strings (cross-references the Banned terms section above).
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — how the components fit together.
- [`DOD.md`](DOD.md) — who uses each surface and what for.
- [`SECURITY.md`](SECURITY.md) — identity, secrets, rotation.
- [`RUNBOOKS.md`](RUNBOOKS.md) — provisioning, day-2 ops, Blueprint authoring (§3), chart conventions (§4), demo walk (§5), failover recovery (§6), troubleshooting (§7).