Health status aggregation and persistence
epic-external-system-integration-configuration-backend-infrastructure-task-014 — Implement the integration_health_status table and repository for storing and querying health check results. The table holds the latest status per (org_id, integration_type) pair plus a rolling 24-hour history for trend display. Implement queries that return current health status for all integrations of an org (used by the admin dashboard) and aggregate health across all orgs (used by global admins). Include RLS policies ensuring org isolation.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
The trigger-based history copy is the most reliable approach — it guarantees history is always written even if the application code path crashes after the upsert. Implement the trigger as a BEFORE INSERT OR UPDATE trigger that also prunes rows beyond the 96-row cap for the same (org_id, integration_type) pair to bound table growth. For the global admin summary, implement as a Postgres RPC function with SECURITY DEFINER and explicit role check on current_setting('request.jwt.claims') rather than relying on RLS alone, since RLS for SELECT ALL requires a bypass policy. Store the display name for each integration_type in a separate integration_types lookup table (seeded at migration time) so the getOrgHealthStatus join always has a human-readable label even for integrations with no current status row.
Testing Requirements
Unit tests with mocked Supabase client: (1) getOrgHealthStatus returns correct rows for the given orgId; (2) getHealthTrend respects the hours parameter and returns rows ordered DESC; (3) getGlobalHealthSummary rejects callers without global_admin role. Integration tests against local Supabase: (1) trigger correctly copies updated row to history table; (2) RLS blocks cross-org SELECT; (3) pg_cron cleanup deletes rows older than 30 days without deleting recent rows; (4) unique constraint on (org_id, integration_type) prevents duplicate current-status rows. Test with 97 history rows — confirm only 96 returned for 24-hour trend.
Supabase Edge Functions have cold start latency that can cause the first sync invocation after idle periods to fail or timeout when the external API has a short connection window, leading to missed scheduled syncs that go undetected.
Mitigation & Contingency
Mitigation: Configure Edge Function memory and implement a warm-up ping mechanism before heavy sync invocations. Set generous timeout values on the external API calls. Log all cold-start incidents for monitoring.
Contingency: If cold starts cause consistent sync failures, migrate the sync scheduler to a persistent Supabase cron job that pre-warms the function 30 seconds before the scheduled sync time.
The sync scheduler must execute jobs at predictable times for financial reporting accuracy. Drift in cron execution timing (due to Supabase infrastructure delays) could cause syncs to run at wrong times, leading to missing data in accounting exports or duplicate exports across reporting periods.
Mitigation & Contingency
Mitigation: Implement idempotency keys based on integration ID + scheduled period, so re-runs of a delayed sync cannot create duplicate exports. Log actual execution timestamps vs scheduled timestamps and alert on drift exceeding 5 minutes.
Contingency: If scheduler reliability is insufficient, integrate with a dedicated cron service (e.g., pg_cron on Supabase) for millisecond-precise scheduling, replacing the application-level scheduler.
Aggressive health monitoring ping frequency could trigger rate limiting on external APIs (especially Xledger and Dynamics), causing legitimate export calls to fail after the monitor exhausts the API's request quota.
Mitigation & Contingency
Mitigation: Use lightweight health check endpoints (HEAD requests or vendor-specific ping/status endpoints) rather than data requests. Set health check frequency to once per 15 minutes minimum. Implement exponential backoff after consecutive failures.
Contingency: If rate limiting occurs, disable active health monitoring for the affected integration type and switch to passive health detection (mark unhealthy only when a scheduled sync fails).