Badge Criteria Edge Function
Component Detail
Description
Supabase Edge Function triggered by a database webhook on activity insert/update. Invokes the badge evaluation service to check all badge criteria for the relevant peer mentor and awards any newly satisfied badges. Runs server-side to prevent client-side manipulation.
badge-criteria-edge-function
Summaries
The Badge Criteria Edge Function is the automated engine that ensures every peer mentor receives timely, accurate recognition the moment they earn a badge — with no manual intervention required. By running server-side and responding automatically to activity saves, it eliminates the risk of badges being missed, delayed, or manipulated, which directly supports trust in the recognition program. A credible, instant rewards system is a proven driver of engagement and retention, making this component a core competitive feature that differentiates the platform from simpler tracking tools that rely on manual award processes.
This is a medium-complexity backend component with two critical dependencies: badge-evaluation-service and badge-award-service, both of which must be completed and stable before this edge function can be integrated and tested end-to-end. The Supabase webhook configuration is a deployment prerequisite and must be set up in all environments (dev, staging, production). Testing requires integration-level coverage simulating webhook payloads, including edge cases such as malformed payloads and evaluation service failures. Plan for at least one sprint for implementation plus a dedicated integration testing phase.
Rollback strategy should include webhook disable toggle to prevent runaway evaluation loops during incidents.
Implemented as a Supabase Edge Function (Deno runtime) triggered via a database webhook on the activities table (insert/update events). The handler extracts the peer mentor ID from the webhook payload, delegates evaluation to badge-evaluation-service, and passes awarded badges to badge-award-service for atomic persistence. The respondWithAwardedBadges method returns a structured Response for webhook acknowledgment and audit logging. Critical considerations: idempotency — re-triggered webhooks must not double-award badges; payload schema validation before extraction; structured logging for every evaluation run.
Error responses must return appropriate HTTP status codes to prevent Supabase from retrying indefinitely on non-retriable failures.
Responsibilities
- Respond to Supabase activity save webhook
- Invoke badge evaluation for the affected peer mentor
- Award newly satisfied badges atomically
- Log evaluation results for audit and debugging
Interfaces
handler(Request request) -> Response
extractPeerMentorFromPayload(Map<String, dynamic> payload) -> String
invokeEvaluation(String peerMentorId, String organisationId)
respondWithAwardedBadges(List<EarnedBadge> awarded) -> Response
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (4)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on