add-ideas/govoplan-tenancy
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
govoplan-tenancy/docs/TENANCY_MODULE_BOUNDARY.md
Albrecht Degering 0ca9bd793c Release v0.1.7
2026-07-11 02:34:58 +02:00

2.8 KiB
Raw Permalink Blame History

GovOPlaN Tenancy Module Boundary

govoplan-tenancy owns tenant registry, tenant settings, tenant lifecycle, and tenant-context route contributions.

Owned Routes

  • /api/v1/admin/tenants*: tenant registry, delta feed, owner candidates, settings, deletion plans, retirement, and guarded empty-tenant destruction.
  • /api/v1/tenancy/switch-tenant: tenant-owned route surface for interactive tenant context switching.

/api/v1/auth/switch-tenant remains in govoplan-access for API compatibility, but both routes delegate to the same auth.tenantContextSwitcher capability.

Lifecycle Rules

Tenant retirement is non-destructive. It marks the tenant inactive and stores lifecycle metadata in tenant settings.

Destructive deletion is intentionally narrow: it is allowed only when the tenant is not the caller's active tenant and all registered tenant-owned counts are zero. Populated tenants must be retired first or cleaned explicitly by their owning modules before physical deletion.

Tenant lifecycle planning uses registered tenant summary providers and delete veto providers. Modules that own tenant-scoped data must contribute summaries so destructive deletion cannot silently miss their rows.

Delete veto providers are registered through module manifests and receive (session, tenant_id, resource_id). Providers should return a structured DeleteVetoIssue, a list of issues, or None; legacy providers that raise an exception are treated as blocking module vetoes. Tenancy exposes those issues in the deletion plan with module attribution and resource details, so operators can see which module blocks or qualifies the lifecycle action.

Lifecycle Events

govoplan-tenancy.backend.lifecycle is the module-local contract for tenant lifecycle event names and payload shape. Modules that need to react to tenant lifecycle changes should depend on the event type strings or the emitted audit events, not on tenancy API route internals.

The stable lifecycle event names are:

  • tenant.created: tenant registry entry was created and owner membership provisioning was requested.
  • tenant.suspended: tenant was marked inactive through the admin lifecycle route.
  • tenant.resumed: tenant was reactivated through the admin lifecycle route.
  • tenant.deletion_requested: retirement or destructive erasure was requested after lifecycle planning passed.
  • tenant.erasure_completed: destructive tenant deletion completed.

Legacy audit actions such as tenant.updated, tenant.retired, and tenant.destroyed can still be emitted for compatibility. New module behavior should key off the explicit lifecycle events above.

Lifecycle event details use concrete tenant identifiers plus optional actor, reason, count, and mode information. Destructive erasure is only emitted after the tenant row is successfully scheduled for deletion in the same transaction.