Skip to main content

PLATFORM is its own OrgType

The property​

Wrkbelt itself is modeled as an organization with org_type: PLATFORM. Superadmins are members of this organization. The org type is a first-class discriminator alongside BRAND, PORTFOLIO, and PARTNER.

See libs/shared/types-data/src/lib/core/organization/organization.enum.ts:1 (the OrgType enum) and the discriminated entity variants at libs/shared/types-data/src/lib/core/organization/organization.entity.ts:26-46.

Why an org type, not a role​

A natural alternative is "make superadmin a role, not an org type." That model would assign a superadmin role to special users in any org. The platform rejected it for two reasons:

1. Identity-based authority, not role-based​

Platform authority is an identity property: certain users are platform operators. It is not a role assigned within someone else's org — the support engineer doesn't acquire platform authority by joining a customer's organization.

Modeling PLATFORM as an org type means the existing membership and permission guards work uniformly. A user with membership in the PLATFORM org has the platform capabilities; a user without it does not. There is no need for a separate "is-superadmin" check parallel to the org-scoped permission check.

2. The dual check works naturally​

The dual-check authorization pattern requires that the actor have permission both for the action and for the target org. When the actor is a PLATFORM member, the target-org check resolves via the identity-based authority that PLATFORM carries (membership in PLATFORM grants action authority across all orgs via hierarchy traversal). The same guard runs; the same code path checks; the same audit trail records.

If superadmin were a role-on-another-org, the guard would need a special-case branch for "is this user a superadmin?" — an additional code path with its own bugs.

Implementation​

  • OrgType.PLATFORM is declared in organization.enum.ts:2.
  • The PlatformOrganization discriminated variant is at organization.entity.ts:26-30.
  • The PLATFORM org is a singleton — created once via seed/migration, never directly via API.
  • Membership in PLATFORM grants identity-based authority that traverses the org hierarchy via the standard ancestry cascade.

Consequences​

  • Adding a fifth org type means extending the OrgType enum and the discriminated union in organization.entity.ts; the rest of the auth stack picks it up via the dual-check guard without code change.
  • The PLATFORM org is a singleton. Migrations that touch organization seeding must preserve the existing PLATFORM _id — it is referenced by session-stored org context and audit records, and recreating it would orphan those references.
  • PLATFORM authority cascades through the hierarchy via ancestry traversal. There is no separate platform-admin permission code path; improvements to the cascade benefit platform operations and customer-side hierarchy cascade uniformly.
  • Audit records always carry the actor's org context, including when the actor is a PLATFORM member acting on a customer org. The audit trail distinguishes platform-driven actions from tenant-driven ones via the actor's org_type — not via a separate "is-superadmin" flag.
  • Removing PLATFORM authority from a user means revoking their PLATFORM membership through the standard membership endpoint; there is no parallel "demote superadmin" call.