Skip to main content

Data Ownership Handover

This document describes the architectural concepts and rationale behind Framework M's Enterprise Data Handover system, including controller delegation, lifecycle validation, and audit trail preservation.

1. Rationale: Hook-Based Delegation vs. Raw SQL Updates​

In typical relational database systems, transferring ownership of data from one user to another (for example, when an employee departs the company) is often done via blanket database updates:

-- DANGEROUS: Blanket SQL updates bypass validation rules
UPDATE documents SET owner_id = 'new_user_uuid' WHERE owner_id = 'old_user_uuid';

While fast, this approach introduces severe business logic hazards:

  1. Bypassing Rules: It bypasses document validations (for example, a document might be locked, under review, or archived, which should prevent ownership changes).
  2. Side Effects: It fails to trigger side effects (such as notifying the new owner, updating search indices, or logging the event to external systems).
  3. Mismatched Fields: It fails to handle composite or custom structures (e.g., collaborator list arrays, nested objects, or dynamic properties).

Framework M's Solution​

Framework M delegates the transfer to each document type's repository and controller lifecycle hooks. When a transfer is initiated:

  • The OwnershipTransferService queries the registry for all registered DocTypes.
  • For each DocType, it retrieves all records owned by the departing user.
  • It instantiates the DocType's Controller and calls before_transfer_ownership().
  • If validation succeeds, it saves the changes (updating the owner_id) and triggers after_transfer_ownership().

This ensures that the transfer conforms exactly to the same business validations and side effects as standard document edits.

2. Audit Trail Preservation and Immutable Records​

A crucial requirement for enterprise compliance is the preservation of historical records. During a data handover, not all records pointing to a user's ID should be transferred:

Immutable Logs​

Certain records are historical logs of actions taken in the past. These must remain immutable and must not have their ownership transferred:

  • AuditLog: Represents an audit record of who did what and when. Modifying the user ID on an audit log would overwrite history, violating compliance policies.
  • ActivityLog: Tracks specific timeline logs or user comments. These must continue to show the departing user as the author/actor.

Mutable Documents​

Only mutable operational records (e.g., active tasks, projects, sales opportunities, document templates, drafts) are subject to ownership transfer.

The OwnershipTransferService respects this boundary by only querying and executing transfers on document types that register ownership properties and are not explicitly marked as read-only historical logs.