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.

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
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 §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 §10.8 (Franchise Model — End-to-End Mechanics).

---

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 §10.8 (Franchise Model — End-to-End Mechanics).

---

Infrastructure

Term	Definition
Cluster	A physical Kubernetes cluster. Named per docs/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
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 (2026-05-03); the platform/spire/ chart is retained as opt-in. Re-introduction roadmap: TBD-V29 #2055. See SECURITY.md §2 + 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, RUNBOOKS.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: 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 (2026-05-03); canonical workload identity is now Cilium WireGuard + K8s SA TokenReview. Re-introduction roadmap: TBD-V29 #2055.
GSLB	Global Server Load Balancing — handled at the authoritative DNS layer by PowerDNS lua-records (ifurlup, pickclosest, ifportup). See MULTI-REGION-DNS.md.
PromotionPolicy	Removed concept. Replaced by EnvironmentPolicy attached to a destination Environment, enforcing PR/approval/soak/change-window rules.

---

See also

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