Employee Database Compatibility and Backfill

Summary

The monolith and Employee Service persist separate workforce models during transition. Employee Service uses GUID identifiers; Legacy Labor, Department, and Designation models use numeric identifiers. No Employee Service historical backfill runner or durable legacy-ID mapping object was found.

Audience

• Solution architects and backend developers
• QA and DevOps engineers planning cutover evidence

Transition model

The transformation, load, validation, and rollback mechanisms in this diagram are required concepts, not implemented Employee Service tooling.

Compatibility inventory

Concern	Employee Service	Legacy monolith	Classification	Source
Employee identity	GUID	Numeric	Transitional mismatch	Employee compatibility source and Models/Labor.cs
Organization identity	GUID	Numeric	Transitional mismatch	Employee/monolith organization models
Employee core	Aggregate-oriented model	Broad Labor row	Separate ownership models	same
Organization	Department and Designation aggregates	Monolith tables	Coexistence	EmployeeDbContext.cs, Data/AppDbContext.cs
Compatibility routes	Reject numeric identifiers in extracted service	Legacy controllers accept numeric identifiers	Client migration required	EmployeeCompatibilityEndpoints.cs
Durable legacy mapping	Not found	Native numeric identity	Not implemented	Employee migrations/snapshot
Historical backfill runner	Not found	Source data exists	Not implemented	Employee Service tree and scripts

The Employee context contains a helper that can derive a compatibility reference from employee code for supported integration messages, but it is not a persisted mapping table and is not sufficient evidence of reversible migration. Exact event representation is outside this epic.

Dual-ownership risks and reconciliation

During coexistence, writes routed to different owners can diverge unless an approved synchronization mechanism exists. Cutover should reconcile tenant coverage, identifiers, active state, organization references, profile coverage, counts, and representative API semantics. The reviewed Employee smoke script exercises each API surface but is not a historical data-parity tool.

No direct database-copy instructions are provided. Source access, transformation rules, idempotency, error quarantine, reconciliation thresholds, and rollback authority all Require confirmation.

Source References

• microservices/src/employee-service/Infrastructure/EmployeeDbContext.cs
• microservices/src/employee-service/Infrastructure/Migrations/EmployeeDbContextModelSnapshot.cs
• microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
• microservices/src/employee-service/docs/employee-compatibility-placeholders.md
• microservices/scripts/smoke-employee.ps1
• Data/AppDbContext.cs
• Models/Labor.cs
• Models/Department.cs
• Models/Designation.cs

Related Articles

• API compatibility and routing
• Gateway interaction
• Ownership and boundaries

See Also

• Database testing guide
• Future Employee Events and Integration Contracts documentation (Not implemented)

Keywords

• Legacy coexistence
• Backfill gap
• Identifier transition

Revision Information

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