Feat/backend health rollback bonus scaling 697 698 699 715

[xeladev4]

Pull Request

Summary

Closes #697 , Closes #698 , Closes #699 , Closes #715

Four backend issues addressed in one branch:

• [BACKEND] Add Health Check Endpoints for Infrastructure Monitoring #697 — Add Health Check Endpoints for Infrastructure Monitoring
• [BACKEND] Implement Database Migration Rollback Strategy #698 — Implement Database Migration Rollback Strategy
• [BACKEND] Add Support for Performance Bonuses in Payroll Engine #699 — Add Support for Performance Bonuses in Payroll Engine
• [BACKEND] Issue #270 - API & Database Scaling Part 25 #715 — API & Database Scaling Part 25

What Changed

Chore — Re-sequence migrations (prerequisite)

• Two existing migration files both had the 040_ prefix, which the migration runner rejects with a fatal duplicate-prefix error.
• Created rollback files for all previously-untracked migrations (040_api_database_scaling_part27, 041_optimize_transaction_log_indexes, 042_circuit_breaker_part11, 043_V15__scaling_indexes).
• Ran node scripts/resequence-migrations.mjs (the prescribed fix per CONTRIBUTING.md) to restore unique, contiguous numbering.
• Added a root-level eslint.config.js (ESLint v10 flat config) so the pre-commit lint-staged hook no longer errors on non-JS staged files.

#697 — Health Check Endpoints

• Added HealthController.getLiveness() — returns { status: "alive", uptime, timestamp } with no dependency checks; safe for k8s liveness probes that must never block.
• Added HealthController.getReadiness() — checks PostgreSQL and Redis; returns 200 { status: "ready" } or 503 { status: "not_ready" }.
• Registered four new routes in app.ts:
  • GET /api/v1/health/live
  • GET /api/v1/health/ready
  • GET /health/live
  • GET /health/ready
• Added 8 new unit tests covering 200/503 responses, individual dependency failures, and confirmed the liveness probe never queries the DB.

#698 — Database Migration Rollback Strategy

• Migration 044_migration_rollback_audit.sql — creates migration_rollback_log table: an immutable audit trail of every rollback event (filename, timestamp, user, reason, execution_ms).
• MigrationStatusService — reads schema_migrations and migration_rollback_log to surface a full status report. Gracefully returns an empty rollback history if the log table does not exist yet (safe for pre-044 databases).
• MigrationStatusController + migrationStatusRoutes:
  • GET /api/v1/migrations/status — full report: applied, pending (with rollback availability flag), rollback history
  • GET /api/v1/migrations/applied — applied migrations with checksums and timestamps
  • GET /api/v1/migrations/rollbacks — rollback event log, most recent first (?limit= capped at 100)
• Added 8 unit tests covering all three service methods, including limit clamping and graceful handling of missing table.

#699 — Performance Bonuses in Payroll Engine

• Migration 045_add_performance_bonus_fields.sql:
  • payroll_items.bonus_type VARCHAR(50) — CHECK constrained to ('performance','referral','project','retention','spot','other').
  • payroll_items.performance_score NUMERIC(5,2) — 0–100 range check; NULL for non-performance bonuses.
  • Partial indexes on both columns for efficient filtered queries.
• PayrollBonusService updates:
  • addBonusItem / addBatchBonusItems — now accept and persist bonus_type and performance_score.
  • listBonusesByType(orgId, bonusType) — filter bonus history by category.
  • getPerformanceBonusesByScore(orgId, minScore) — list performance bonuses above a score threshold, ordered score-descending.
• PayrollBonusController — two new methods: listBonusesByType, getPerformanceBonuses.
• payrollBonusRoutes — two new routes:
  • GET /api/v1/payroll-bonus/bonuses/by-type/:bonusType
  • GET /api/v1/payroll-bonus/bonuses/performance?minScore=
• Added 18 unit tests in payrollBonusService.test.ts covering create, add (with/without new fields), batch insert, transaction rollback on error, listBonusesByType, getPerformanceBonusesByScore, deletePayrollItem.

#715 — API & Database Scaling Part 25

• Migration 046_api_database_scaling_part25.sql:
  • api_latency_histogram table — stores pre-bucketed latency observations per endpoint/method, with a 30-day auto-prune function.
  • idx_employees_list_covering — covering index on employees(organization_id, status, created_at DESC) INCLUDE (first_name, last_name, email, wallet_address) to avoid heap fetches on the high-traffic employee list query.
  • idx_transactions_list_covering — covering index on transactions(organization_id, status, created_at DESC) INCLUDE (amount, type).
• scalingRoutes.ts — two new Part 25 endpoints:
  • GET /api/v1/scaling/latency-percentiles — computes p50/p95/p99 per endpoint from api_latency_histogram over a configurable time window (?limit=, ?windowMinutes=).
  • GET /api/v1/scaling/pool-history — time-series snapshots from db_pool_health for connection-pool saturation trend analysis (?limit=).
• Added 8 integration tests for both endpoints.

Checklist

• I linked the relevant issue(s) in the summary.
• I added or updated tests for the change.
• I ran the relevant test suite locally.
• I updated documentation where needed, or explained why it was not needed.
• If this change touches the UI, I verified responsive behavior and accessibility. (N/A — backend only)
• I included screenshots, logs, or other proof when they help review.

Testing

cd backend

# Unit tests (no live DB required)
npm run test -- src/controllers/__tests__/healthController.test.ts
npm run test -- src/services/__tests__/migrationStatusService.test.ts
npm run test -- src/services/__tests__/payrollBonusService.test.ts

# Scaling routes integration tests (mock DB)
npm run test -- src/__tests__/scalingRoutes.test.ts

# All backend tests
npm run test

For the migration runner dry-run:

cd backend
npm run db:migrate:dry-run

Documentation

• Migration guide already documents the rollback strategy (backend/src/db/MIGRATION_GUIDE.md); the new migration_rollback_log table extends that infrastructure.
• Swagger JSDoc annotations added to all new routes.

Accessibility / Responsiveness

N/A — backend API changes only.

Notes

• Migration checklist (per CONTRIBUTING.md):

  • Migration files named correctly (NNN_short_description.sql)
  • Migration numbers are unique (044, 045, 046)
  • Migrations use IF NOT EXISTS / IF EXISTS for idempotency
  • Matching rollback files created in backend/src/db/rollbacks/
  • No existing migration file was modified

• The pre-existing duplicate 040_ prefix is fixed as part of this PR via the prescribed resequence-migrations.mjs script. The two affected migration files were already merged to main by previous contributors; this PR adds their missing rollback files before resequencing, as required.

[drips-wave]

@xeladev4 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits