Compatibility and Backfill Architecture

Summary

Legacy-shaped adapter, identifier parity, cutover routing, and migration tooling.

Audience

Engineers, architects, QA, support, security reviewers, and operators working with the Performance module.

Overview

The compatibility service maps one flat legacy goal record to one Appraisal containing one goal and collapses the canonical state model. Backfill tooling imports legacy records per tenant, preserves compatibility identifiers, supports resume/dry-run behavior, and validates source-to-target parity.

Confirmed implementation

• Compatibility create can provision a Draft cycle and bypass canonical cycle eligibility.
• Compatibility update overwrites a single goal and emits no canonical lifecycle events.
• Compatibility delete removes the mapped appraisal and records audit.
• Backfill is invoked through a dedicated command-line mode rather than the web request path.
• Gateway controls whether legacy Performance traffic reaches the service.

Classification

Transitional by design.

Requires confirmation

Cutover completion criteria, reconciliation sign-off, rollback ownership, and removal timeline require confirmation.

Related Articles

• Performance technical documentation
• Performance module

See Also

• Technical known limitations
• Performance business documentation

Keywords

• Performance service
• Compatibility and Backfill
• Draft technical documentation

Source References

• microservices/src/performance-service/Application/Compatibility/PerformanceCompatService.cs
• microservices/src/performance-service/Backfill/PerformanceBackfillRunner.cs
• microservices/src/performance-service/Backfill/PerformanceGoalBackfill.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