PSA/ee/docs/plans/2026-02-12-deletion-ux-improvement/PRD.md

PRD — Deletion UX Improvement

• Slug: deletion-ux-improvement
• Date: 2026-02-12
• Status: Draft

Summary

Standardize deletion handling across all Alga PSA feature packages. Replace the current inconsistent mix of silent failures, generic error messages, and missing alternative actions with a unified system that validates dependencies, shows clear blocking reasons, offers alternatives (inactive/archive), and runs validation + deletion atomically in a single transaction.

Problem

Deleting items in Alga PSA is currently inconsistent and confusing:

• ~40% of delete operations fail silently with no indication of why
• ~60% show only generic "Failed to delete" messages with no context
• ~80% offer no alternative action when deletion is blocked
• 0% show a dependency preview before the user attempts deletion
• ~10% run validation and deletion in a single atomic transaction (rest have TOCTOU race conditions)
• ~30% of tag-supporting entities are missing tag cleanup on deletion
• Only the @alga-psa/clients package has a good pattern (structured error responses, dependency counts, "Mark as Inactive" alternative)

Users get stuck, file support tickets, and lose trust in the product when they can't understand why something won't delete or what to do instead.

Goals

1. Consistent deletion UX across all 20+ entity types with delete functionality
2. Clear dependency feedback showing exactly what blocks deletion (type, count, view link)
3. Alternative actions (deactivate, archive) offered when deletion is blocked
4. Dependency preview shown when the delete dialog opens, before the user confirms
5. Atomic transactions for validate-and-delete to prevent race conditions
6. Automatic tag cleanup for all taggable entities via centralized config
7. Reusable infrastructure (types, validation functions, dialog component, hook) so new entities get deletion UX for free

Non-goals

• Changing what entities can/cannot be deleted (business rules stay the same)
• Adding soft-delete or trash/recycle-bin functionality
• Building a cascading delete system (entities with deps still require manual resolution)
• Retroactively adding archive/inactive support to entities that don't have it
• Monitoring, analytics, or audit logging for deletion operations

Users and Primary Flows

Primary user: MSP admin managing clients, tickets, projects, billing, and configuration

Flow 1 — Delete entity with no dependencies:

1. User clicks Delete button on an entity
2. Dialog opens showing "Checking for dependencies..." spinner
3. Preview completes: "Are you sure you want to delete X? This action cannot be undone."
4. User clicks Delete
5. Atomic validate + delete executes in one transaction
6. Entity deleted, tags cleaned up, user redirected

Flow 2 — Delete entity with dependencies (alternative available):

1. User clicks Delete button
2. Dialog opens, preview runs
3. Dialog shows "Cannot Delete X" with itemized dependency list (e.g., "5 tickets, 2 projects")
4. Dialog shows "Alternative Options" section with "Mark as Inactive" button
5. User clicks "Mark as Inactive" (or closes dialog to manually resolve deps)

Flow 3 — Delete entity with dependencies (no alternative):

1. User clicks Delete button
2. Dialog opens, preview runs
3. Dialog shows dependency list and message: "Please remove or reassign these items before deleting."
4. User closes dialog, resolves dependencies, retries

UX / UI Notes

New component: DeleteEntityDialog in @alga-psa/ui

• Three states: validating (spinner), can-delete (confirmation), cannot-delete (dependency list + alternatives)
• Dependency list shows count + optional "View" link per dependency type
• Alternative actions shown as primary button(s) when deletion is blocked
• Loading states on all buttons during async operations
• Separate from existing ConfirmationDialog (which remains for non-deletion confirmations)

Existing ConfirmationDialog is NOT modified — it continues to serve general-purpose confirmations (unsaved changes, recurring event scope, etc.)

Requirements

Functional Requirements

FR-1: Shared deletion types (@alga-psa/types)

• DeletionValidationResult with canDelete, code, message, dependencies[], alternatives[]
• DeletionDependency with type, count, label, viewUrl
• DeletionAlternative with action, label, description, warning
• EntityDeletionConfig with dependency definitions, tag support, and alternative support flags
• EntityDependencyConfig with table, foreignKey, countQuery, viewUrlTemplate

FR-2: Deletion validation functions (@alga-psa/core)

• validateDeletion(trx, config, entityId, tenant) — counts dependencies within a transaction
• Plain functions (not a class), matching codebase conventions

FR-3: Entity deletion configs (@alga-psa/core)

• Schema-verified configs for all 20+ entity types
• Foreign keys validated against live PostgreSQL schema
• tagEntityType field for automatic tag cleanup

FR-4: Server action helpers (@alga-psa/core)

• preCheckDeletion(entityType, entityId) — read-only preview for dialog opening
• deleteEntityWithValidation(entityType, entityId, performDelete) — atomic validate + tag cleanup + delete in one withTransaction

FR-5: Delete dialog component (@alga-psa/ui)

• DeleteEntityDialog with validation result display, dependency list, alternative actions, loading states

FR-6: Dependency preview hook (@alga-psa/core)

• useDeletionValidation(entityType) — manages validation state for UI components

FR-7: Bulk deletion validation (@alga-psa/core)

• validateBulkDeletion(entityType, entityIds) — single-transaction validation for multiple entities

FR-8: Client deletion migration (@alga-psa/clients)

• Refactor deleteClient to use deleteEntityWithValidation
• Replace ConfirmationDialog with DeleteEntityDialog in ClientDetails.tsx
• Wire onAlternativeAction to existing markClientInactiveWithContacts

FR-9: Feature package migrations (all remaining packages)

• Each package: add validate action, refactor delete action, switch to DeleteEntityDialog
• Remove manual deleteEntityTags calls (automatic via config)

Non-functional Requirements

• All deletion configs must use schema-verified foreign key names
• Validation and deletion must share a single database transaction
• Tag cleanup must be automatic for all entities with tagEntityType set
• Bulk validation must use a single transaction (not N parallel transactions)

Data / API / Integrations

Database tables involved (verified against schema):

• All entity tables (tickets, contacts, projects, invoices, assets, interactions, etc.)
• Join/association tables (team_members, schedule_entry_assignees, contract_line_services, etc.)
• Tag tables (tag_definitions, tag_mappings) via @alga-psa/tags cleanup utilities
• Document associations (document_associations with entity_type polymorphism)

Key schema corrections from v1 plan:

• company_id → client_id (contacts, tickets, projects, invoices, assets, interactions)
• user_team_members → team_members
• company_billing_plans → does not exist; use contract_line_services
• schedule_entries.user_id → schedule_entry_assignees.user_id (M2M)
• invoices.tax_rate_id → does not exist; use client_tax_rates

Security / Permissions

• preCheckDeletion and deleteEntityWithValidation both check getCurrentUser() and hasPermission(user, entity, 'delete')
• Permission entity mapping: client → company (existing convention)
• No new permissions introduced; existing RBAC delete permissions are reused

Rollout / Migration

Phase 1 (Week 1-2): Core infrastructure — types, validation functions, configs, dialog, hook Phase 2 (Week 3-4): P0 migrations — clients, users, teams Phase 3 (Week 5-6): P1 migrations — billing (contracts, services, products) Phase 4 (Week 7-8): P2 migrations — tickets, projects, reference-data Phase 5 (Week 9-10): P3 migrations — surveys, scheduling, tax rates, bulk validation

Each package migration is independently deployable. No database migrations required.

Open Questions

1. Should the DeleteEntityDialog support dark mode from the start? (The app is adding dark mode support on the dark_times branch.)
2. For entities with supportsCascade: true (tickets, projects), should the dialog explain what will be cascade-deleted?
3. Should bulk delete in TicketingDashboard use the new validateBulkDeletion immediately, or is that a P3 enhancement?

Acceptance Criteria (Definition of Done)

1. All 20+ entity types use DeleteEntityDialog for deletion confirmation
2. All delete actions use deleteEntityWithValidation for atomic transactions
3. All entity configs have schema-verified foreign keys
4. All taggable entities have automatic tag cleanup via tagEntityType
5. Dependency preview loads when the delete dialog opens (before user confirms)
6. Blocked deletions show itemized dependency list with counts
7. Entities with supportsInactive/supportsArchive offer alternative actions in the dialog
8. No manual deleteEntityTags calls remain in migrated packages
9. Existing ConfirmationDialog is unchanged and continues to work for non-deletion use cases
10. No regressions in existing deletion functionality