Account And Organization Lifecycle

This document is the production contract for account deletion, staff offboarding, ownership transfer, and organization closure.

Identity and access boundaries

• App, portal, and platform sign-in identities remain separate authentication realms.
• Removing one membership removes only that surface's access while another active membership exists.
• Removing the final active membership revokes all authentication credentials, sessions, MFA state, recovery state, preferences, notifications, impersonation/support sessions, and portal grants for that identity.
• The final users row becomes a minimal tombstone (Deleted user, no email, phone, image, or realm identifiers). This preserves historical foreign-key integrity without retaining sign-in or contact data.
• Minimal tombstones remain only while retained business or audit records reference them. They are not usable identities and cannot authenticate. Historical business and security records, including required actor attribution, remain subject to the product's retention and legal-obligation policy rather than being treated as active profile data.

Staff offboarding

An owner must choose an active replacement in the same organization before removing a staff member. The removal transaction hands off:

• owned client accounts
• owned projects and project membership
• open assigned project tasks
• active reminders
• submitted portal support requests

The membership, scoped client assignments, preferences, and remaining identity access are then cleaned up, and the handoff is written to the organization audit log. An owner cannot be removed through this flow; ownership must be transferred first.

Ownership transfer

Ownership transfer requires the current verified owner and a current-password check. The backend atomically:

• makes the selected active member the owner
• demotes the previous owner to an administrator
• resets both memberships to role-default, all-client access
• updates the organization owner pointer and an owner-derived billing email
• preserves a separately configured billing contact
• records an immutable audit event

Closed organizations and organizations with closure in progress cannot transfer ownership.

Organization closure

Closure is an archival shutdown, not an immediate hard-delete of business records. It requires the exact organization name, current password, verified owner status, and billing cancellation permission.

The workflow is retry-safe and checkpointed:

1. Persist the closure request and immutable external identifiers.
2. Cancel the SaaS subscription immediately, tolerating an already-cancelled provider record.
3. Remove the custom-domain router.
4. Remove staff, invite, portal, preference, and grant access in bounded, resumable batches; revoke external upload sessions, API credentials, and webhooks; end support sessions.
5. Clear stale current-workspace selections, archive the organization, and record audit/directory state.

Each external step is marked complete before the next one runs. A failure stores a sanitized error and leaves memberships available so the owner can retry the same action. Billing changes and ownership transfer are blocked during a pending or failed closure. Operator repair should inspect closureState, closureLastError, and the step timestamps before retrying.

Deployment and repair

The lifecycle schema change is backward-compatible: new fields are optional and new indexes require no data backfill. Before production rollout:

1. Deploy schema and application code.
2. Dry-run migrations:runAccountLifecycleRepairsV1.
3. Run it to remove legacy portalAccessGrants whose organization, portal identity, user, client, or contact relationship no longer exists or no longer matches.
4. Monitor migration status and lifecycle audit events.

Never hard-delete tombstoned users independently of the business/audit records that reference them. A future tenant-record purge must delete those records and their tombstones as one reviewed retention workflow.

Launch validation

• final-access deletion leaves no authentication, MFA, recovery, preference, notification, grant, or live support session
• cross-surface deletion preserves unrelated active memberships
• offboarding reassigns live operational ownership before access removal
• ownership transfer changes both membership roles and organization ownership atomically
• closure retries skip completed external steps and archives only after access cleanup succeeds
• unrelated organizations and memberships remain unchanged
• destructive UI uses alert dialogs, explicit typed/password confirmation where appropriate, stable action labels, and visible pending state