Skip to main content

Employee Gateway and Compatibility Troubleshooting

Summary​

Gateway Employee route selection, shadow route, monolith compatibility, extracted compatibility, and UI expectations.

Audience​

  • HR administrators, support engineers, developers, QA engineers, and DevOps engineers

Symptoms​

Same route behaves differently after routing change, numeric/GUID identifiers fail, or UI contract fields differ.

Scope​

Gateway Employee route selection, shadow route, monolith compatibility, extracted compatibility, and UI expectations.

Cause​

Likely causes​

  • Gateway destination differs from expected owner
  • UI sends numeric Legacy identifier while extracted service requires GUID
  • Compatibility DTO fields/actions lack parity
  • Authentication/tenant context forwarding differs
  • Rollback occurred without reconciling writes

Safe diagnostic steps​

  1. Use safe route-source evidence and identify identifier family
  2. Compare the same synthetic request against approved destinations during parity testing
  3. Check status/shape categories, not sensitive payload content
  4. Review recent cutover/rollback and migration state

Resolution​

Safe resolution​

  • Restore approved routing through gateway ownership when rollback criteria are met
  • Resolve contract/identifier mapping before reattempting cutover
  • Reconcile accepted writes through data owners; do not toggle or edit ad hoc

Validation​

Approved routes return parity for supported synthetic cases and UI actions use the correct identifier family.

Evidence to collect​

Route category/source, identifier type, status/shape difference, correlation identifier, deployment window.

Escalation​

Gateway owner first, then Employee/monolith API owners, UI owner, and data owner for write divergence.

Source References​

  • microservices/src/gateway-api/Program.cs
  • microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
  • microservices/src/employee-service/docs/employee-compatibility-placeholders.md
  • UI/salary-ui/apps/client-hrms-portal/src/pages/Labor.tsx

See Also​

Keywords​

  • Employee troubleshooting
  • Gateway and Compatibility
  • safe diagnostics

Revision Information​

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