Edge Function project scaffold and deployment config

epic-external-system-integration-configuration-backend-infrastructure-task-001 — Scaffold the Supabase Edge Functions project structure for the integration adapter dispatch layer. Configure Deno runtime, set up the functions directory layout, define environment variable bindings for Vault access, and configure the supabase/functions deployment pipeline including local development with supabase functions serve.

critical priority medium complexity infrastructure pending infrastructure specialist Tier 0

Acceptance Criteria

supabase/functions/ directory exists with at minimum one entry-point function (e.g., integration-dispatch/index.ts) following Supabase Edge Function conventions

Deno runtime version is pinned in a .dvmrc or import_map.json and matches the Supabase-supported Deno version

All required environment variable names (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, VAULT_SECRET_NAME) are declared in supabase/functions/.env.example with placeholder values and documentation comments

supabase/config.toml includes the functions section with correct function names, verify_jwt settings, and any import map references

Local development works end-to-end: running supabase functions serve integration-dispatch serves the function and responds to a curl health-check request with HTTP 200

CI deployment step (GitHub Actions or equivalent) is configured to run supabase functions deploy on merge to the main branch using a stored SUPABASE_ACCESS_TOKEN secret

The scaffold includes a shared/ or _shared/ directory for utilities (credential provider, adapter registry) that can be imported by multiple functions without duplication

A README.md in supabase/functions/ documents the directory layout, how to add a new function, and how to run locally

Technical Requirements

frameworks

Supabase Edge Functions (Deno runtime)

Deno standard library

apis

Supabase Management API (for deployment)

Supabase Vault API

performance requirements

Cold start time for the dispatch function must be under 500ms — keep imports minimal and avoid heavy dependencies at module level

security requirements

Service role key must only be passed via environment variable, never hardcoded

verify_jwt must be set to true in config.toml unless a specific function requires public access, in which case document the reason

.env files must be in .gitignore — only .env.example is committed

Execution Context

Execution Tier

Tier 0

Tier 0 - 440 tasks

Integration Task

Handles integration between different epics or system components. Requires coordination across multiple development streams.

View Full Execution Plan

Implementation Notes

Use Supabase's official Edge Function quickstart as the baseline. Structure the functions directory as: supabase/functions/integration-dispatch/index.ts (entry point), supabase/functions/_shared/credential-provider.ts, supabase/functions/_shared/adapter-registry.ts, supabase/functions/_shared/types.ts. Use Deno's import map (import_map.json) to alias shared imports cleanly (e.g., 'shared/credential-provider' → ./_shared/credential-provider.ts). Avoid importing npm packages directly where a Deno-native or std library equivalent exists — this minimises cold-start overhead.

Set up the CI deployment step to only deploy functions that have changed (use supabase functions deploy rather than deploying all functions every time).

Testing Requirements

Write a smoke test script (scripts/test-edge-function-local.sh) that starts supabase functions serve, sends a minimal valid request to integration-dispatch, and asserts HTTP 200 with a JSON body. This script is run in CI before deployment. No unit tests are required at scaffold stage — unit tests are added in subsequent tasks when business logic is implemented.

Component

Integration Edge Functions

infrastructure high

Epic Risks (3)

medium impact medium prob technical

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.

high impact low prob technical

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.

high impact medium prob integration

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).

Quick Links

All Tasks Execution Plan