Platform Engine

Status: Draft for review

Purpose

Own the SaaS control plane: tenants, memberships, brands, locations, plan/subscription state, entitlements, domains, provisioning and platform administration.

Owns

• Tenant lifecycle and status
• Brand/location/business-unit registration identities (not their vertical operational data)
• User-to-tenant memberships and tenant-scoped role assignments
• Plans, subscriptions, entitlements, limits and approved overrides
• Domain registration/verification/status and site association
• Provisioning state and platform-level audit references

Non-goals

It does not own offering catalogs, bookings, site page content, payment transactions, campaigns or provider-specific integration logic.

API contract — functional surface

These are contract-level resources and operations, not final controller/file names.

Method	Route	Primary actor	Contract intent
POST	/api/platform/v1/tenants	Platform Admin	Create/provision a tenant.
GET	/api/platform/v1/tenants/{tenantId}	Platform Admin	Read tenant control-plane state.
PATCH	/api/platform/v1/tenants/{tenantId}	Platform Admin	Change lifecycle/configuration fields.
POST	/api/platform/v1/tenants/{tenantId}/suspend	Platform Admin	Suspend tenant access/workflows under policy.
GET	/api/tenant/v1/organization	Tenant Owner/Admin	Read current tenant organization profile.
POST	/api/tenant/v1/business-units	Tenant Owner/Admin	Register a business unit identity and vertical profile.
POST	/api/tenant/v1/brands	Tenant Owner/Admin	Create brand.
POST	/api/tenant/v1/locations	Tenant Owner/Admin	Create location.
GET	/api/tenant/v1/entitlements	Tenant Owner/Admin	Read effective entitlements/usage limits.
POST	/api/tenant/v1/memberships	Tenant Owner/Admin	Invite/create tenant membership.
PATCH	/api/tenant/v1/memberships/{id}	Tenant Owner/Admin	Change membership role/scope/status.
POST	/api/tenant/v1/domains	Tenant Owner/Admin	Request domain association.
POST	/api/tenant/v1/domains/{id}/verify	Tenant Owner/Admin	Trigger/confirm domain verification.

All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.

Events

• tenant.created
• tenant.suspended
• tenant.reactivated
• membership.changed
• business_unit.registered
• entitlement.changed
• domain.verified
• domain.activated

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability	Platform Admin	Tenant Owner	Tenant Admin	Specialist/Manager	Customer/Visitor
Tenant lifecycle	A/R	I	—	—	—
Subscription acceptance/change	C	A/R	I	—	—
Membership administration	I	A	R	—	—
Business unit/brand/location structure	I	A	R	C	—
Domain configuration	C	A	R	C	I
Entitlement override	A/R	C	I	—	—

Dependencies

• Capability Engine for enabled vertical/capability references
• Site Engine for site/domain association
• Finance Engine for subscription billing facts
• Operations Engine for provisioning/audit/monitoring

Internationalization Contract

• Own tenant/user preference references and entitlement checks for enabled locale counts; locale semantics are defined by Internationalization Engine.
• Tenant default locale and enabled locale set must be tenant-scoped and auditable.
• Identity/membership APIs may expose preferred locale but must not infer authorization from locale.
• Platform suspension/provisioning is locale-neutral.

Security / isolation requirements

• Cross-tenant membership access must be impossible by identifier substitution.
• Headless entitlement can resolve true only for an active Custom-plan contract.
• Domain ownership/verification changes are audited.
• Platform support impersonation is explicit and audited.

Acceptance criteria

• Tenant can operate multiple business units without changing tenant type.
• Entitlements resolve deterministically and enforce limits.
• Membership scopes constrain business units/sites where configured.
• Domain lifecycle is represented independently from DNS/TLS provider implementation.
• Suspension behavior is defined across dependent engines.