Skip to main content

Compatibility and Backfill Persistence

Summary​

Legacy-shaped persistence adapter, transition context, upsert behavior, resume markers, and parity checks.

Audience​

Backend engineers, database reviewers, architects, QA, support, operations, security reviewers, and product owners.

Overview​

Compatibility maps one flat legacy record to one Appraisal with one Goal and a collapsed lifecycle. Backfill reads the legacy source, writes through the derived context, preserves the legacy identity as CompatId, and performs no deletes.

Confirmed persistence behavior​

  • Dry-run performs reads and comparisons without target SaveChanges.
  • Upsert groups duplicate source identities, inserts missing appraisals, updates changed mappings, and skips matches.
  • Backfill bypasses global filters and applies explicit tenant conditions.
  • Resume uses a tenant-completion audit marker written after the tenant run; that marker is a normal audit object, not a separate checkpoint object.
  • Parity validation compares counts, cycle coverage, aggregate totals, and missing-subject conditions.
  • Status is collapsed to Draft or Approved during transition.
  • Gateway rollback changes routing only; source does not show reversal of already-written data.
  • No cutover sign-off object or final-system-of-record marker is persisted.

Classification​

Transitional migration architecture.

Requires confirmation​

Go/no-go ownership, reconciliation acceptance, rollback data policy, source retirement, and global identity collision handling require confirmation.

Diagram​

See Also​

Keywords​

  • Performance persistence
  • Compatibility and Backfill
  • Draft database documentation

Source References​

  • microservices/src/performance-service/Application/Compatibility/PerformanceCompatService.cs
  • microservices/src/performance-service/Backfill/PerformanceBackfillTypes.cs
  • microservices/src/performance-service/Backfill/PerformanceGoalBackfill.cs
  • microservices/src/performance-service/Backfill/PerformanceBackfillRunner.cs
  • microservices/src/performance-service/Backfill/PerformanceBackfillValidator.cs
  • microservices/src/gateway-api/Program.cs

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-16
  • Review cycle: Quarterly