proxmox/docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md

Client And Division Terminology

Last Updated: 2026-04-22
Status: Canonical terminology baseline for Phoenix, Sankofa, and Gitea alignment
Related: PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md, EXPECTED_WEB_CONTENT.md, SERVICE_DESCRIPTIONS.md, ../04-configuration/PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md

---

Purpose

Define the canonical vocabulary for the commercial / governance layer and keep it distinct from:

• technical tenancy
• identity provider terminology
• network / infrastructure placement terminology
• Mifos / Fineract business-model terminology

Use these terms consistently in docs, APIs, config, and UI copy unless a client requires a more specific business label.

---

Canonical mappings

Canonical term	Equivalent / current implementation	Use
Client	GitHub Enterprise; Azure billing profile; current Gitea Organization	Top-level commercial / governance account
Division	Client-specific subdivision	Generic umbrella term below Client
Division type	realm, nexus, department, program, legal_entity, region, office, workspace, etc.	Technical normalization of how a client structures divisions
Tenant	Phoenix / Kubernetes / app isolation unit	Technical tenancy only
Site	Proxmox / network / physical location	Infrastructure placement only

Rule: when the repo needs a neutral term, prefer Client and Division.

---

Current clients

These are the canonical Phoenix client records and should be treated as the top governance / commercial layer:

• DBIS
• ICCC
• OMNL
• XOM
• AR
• EI
• PANDA
• SAID

In current Gitea implementation, each of these maps to an Organization.
In Phoenix product language, each of these maps to a Client.

---

Division model

Each client may implement subdivisions differently. Phoenix must remain flexible enough to support:

• business labels that are client-specific
• multiple subdivision types under one client
• optional mapping from business divisions to technical tenants

Recommended normalized model:

Client
  Division
    Repository / App / Service / Workspace / Environment

Examples:

• AR
  • divisions labeled Realms
  • divisions labeled Nexus
• OMNL
  • divisions labeled legal entities
  • divisions labeled programs
  • divisions labeled regional offices
• DBIS
  • divisions labeled departments
  • divisions labeled member institutions
  • divisions labeled programs

---

Reserved words and collision policy

The following words already carry specific meanings in the repo and should not be used as the global neutral replacement for Division.

Term	Reserved meaning	Why it is not the generic business term
Realm	Keycloak / OIDC identity boundary; also AR-specific business label	Would collide with both identity and AR business language
Tenant	Technical isolation boundary in Phoenix / Kubernetes / app models	Already used for namespaces, RBAC, and multi-tenant platform semantics
Site	Physical / infrastructure placement (Proxmox, network, datacenter)	Already means location / topology
Office	Org-chart / Fineract / institutional office structure	Too domain-specific for use as the global subdivision primitive
Nexus	Sankofa / Phoenix branding and AR-specific division label	Strong branding meaning; not stable as a generic structural term

---

Implementation guidance

Docs

• Use Client for the top account layer.
• Use Division when discussing subdivisions generically.
• Use the client-native label only when the business context needs it.
  • Example: “AR division type: realm”
  • Example: “Keycloak realm”

UI

• Internal platform/admin UI may display:
  • Client
  • Division
• Client-facing UI may replace Division with the client’s native label.
  • Example: Realm
  • Example: Program Office
  • Example: Legal Entity

API / config

• Prefer normalized fields such as:

  • clientId
  • divisionId
  • divisionType
  • tenantId
  • siteId

• Avoid overloading:

  • realm
  • tenant
  • site

unless that exact platform-specific meaning is intended.

---

Interpretation guide

When reading older docs in this repo:

• “organization” in Gitea context usually means Client
• “tenant” in Phoenix platform context usually means technical tenant, not client
• “realm” in identity docs means Keycloak realm
• “site” means infrastructure location

If a document mixes these layers, update it toward this terminology baseline.