PaperTrail timelines: subject-tagging architecture for person/org/event/registration/scholarship/CE/license/membership

Umbrella for the PaperTrail-backed timeline feature. Tracks the architecture; #2250 is a child (changeset normalization + actor rendering).

Goal

Give nonprofit admins per-subject timelines ("what happened, when, by whom") built from PaperTrail versions. We already version the financial/membership/registration/user models and stamp subject_person_id via meta.

The core insight: timelines are a graph, not a list

One version usually belongs to several timelines at once — a scholarship payment is on the person, scholarship, and event timelines; an event_registration is the root of the registration timeline and a member of person/event; a payment surfaces under person, event, scholarship, membership, and CE. So the real problem is tagging each version with the set of subjects it rolls up to, not adding one key per timeline.

Mechanism decision: polymorphic subject-tag table

Two forces rule out both naive options:

• Read-time association traversal (union the aggregate's descendants at query time) blows up for deep/wide aggregates: to render page 1 of an event you must enumerate the entire descendant id set in Ruby (registrations → payments → checklists → attendance), build an unbounded IN (...), and sort without an index. Unbounded memory, no DB pagination.
• A subject_*_id column per timeline means ~8 nullable columns + 8 indexes + a backfill migration each, on the fastest-growing table — and every shared record must compute and store all roots it belongs to (combinatorial).

Decision — one polymorphic tag table:

version_subjects(version_id, subject_type, subject_id)
  index (subject_type, subject_id, version_id)

• On version create, a hook asks the versioned record "which subjects do you roll up to?" and inserts one tag row per subject. (Same subject computation we already do for subject_person_id meta — now a set, to a table.)
• Any timeline = one indexed join with LIMIT: no descendant traversal, no giant IN, DB-paginated, bounded memory.
• New timeline = zero schema change; teach the subject-computation the new root.
• Cost: an after_create on the version model + a few association lookups per write + a handful of extra rows per version. Bounded write-time work replacing unbounded read-time traversal — right trade for a read-heavy feature.
• Migration: fold the existing subject_person_id meta into this table (backfill person tags). Early enough in the branch to unify now rather than accrete columns.

Timelines to support (each = a subject tag)

Requested

• Person — cross-cutting.
• Organization — cross-cutting.
• Event registration (+ its children: org, checklist completion, attendance time entries, form answers, payments).
• Scholarship (+ its payments).
• Continuing education registration (+ payments + attendance timestamps / signouts).
• Professional license — includes CE registrations + payments + certificate issued via the associated event registration (multi-hop; shares records with other timelines).
• Membership (+ invoices + payments).
• Event — widest/deepest aggregate (registrations → payments → checklists → attendance). Gets its own subject tag so it is index-paginated, never traversed.

Additional candidates a nonprofit admin would want (all grounded in already-versioned models)

Financial & funding

• Grant / allocation — funding lifecycle (awarded → allocated → disbursed), per grant and per grantee (allocation versioned; grant).
• Refund — usually folded into the related payment/person timeline rather than standalone (refund versioned).
• Invoice / billing — billing history per member (membership_invoice versioned).
• Discount usage — who applied which discount when (discount versioned).

People & credentials

• Facilitator credential — composite view of CE registrations + license + trainings/affiliations: "is this facilitator current / when do they lapse." Ties into the facilitator-affiliations-from-trainings rule.
• Contact / interaction — notes & interactions logged against a person/org (comment versioned) — CRM-style contact history.
• Form submission — an applicant's submission history / a form's responses over time (form_submission, form_answer versioned).

Governance & audit

• Account & permissions audit — role/admin grants & revocations, security-sensitive, often compliance-required (user versioned).
• Deletion log — all destroy events across models: "what was removed and by whom" (nearly free once destroy-diff normalization from #2250 lands).
• Org-wide activity feed — global / per-staff "what happened today," nearly free since every version carries whodunnit + subject + timestamp.

These fall into three shapes the tag table serves uniformly: single-aggregate (registration + children), cross-cutting rollup (person, org, facilitator, event), global (activity feed, deletion log).

Scope (high level)

• Add version_subjects table + index; custom version model / after_create hook to fan out tags
• Define per-model timeline_subjects (which roots each versioned record rolls up to)
• Backfill: migrate subject_person_id meta into version_subjects; backfill other subjects from existing versions
• Timeline reader/query object: subject -> paginated versions via indexed join, through the #2250 changeset normalizer
• Build the requested timelines first (person, org, event, registration, scholarship, CE, license, membership)
• Decide which additional timelines ship next (grant/allocation, facilitator credential, contact, form submission, account audit, deletion log, activity feed)

Children

• #2250 — changeset normalization (create/update/destroy) + actor (whodunnit) rendering

Start with the custom version model, the existing subject_person_id metadata handling, and child issue #2250's changeset normalizer and actor rendering. Define the version_subjects table and per-model timeline_subjects, then verify that requested timelines can read paginated versions through the indexed join and that existing person metadata is backfilled.