Badge Repository
Component Detail
Description
Data access layer for earned badge records in Supabase. Stores earned badges with earned_at timestamps and provides query methods for profile display and coordinator visibility. Enforces uniqueness constraint to prevent duplicate awards.
badge-repository
Summaries
The Badge Repository is the system of record for all earned badges, ensuring that every achievement is durably stored and retrievable across profile displays and coordinator dashboards. Its uniqueness enforcement prevents duplicate awards, protecting the integrity and credibility of the recognition programme. A well-designed data layer here directly supports audit and reporting requirements, which are increasingly important for organisations that need to demonstrate programme impact to funders or leadership. Reliable persistence of earned badges is a foundational requirement — without it, the entire recognition system cannot operate, making this a low-risk, high-importance component.
This is a low-complexity, foundational component that should be delivered early in the feature build-out as nearly all badge-related features depend on it. It has no external service dependencies beyond Supabase, making it straightforward to implement and test in isolation. Testing should verify the uniqueness constraint (attempting duplicate inserts), timestamp accuracy, and the efficiency of org-scoped and mentor-scoped queries. The findRecentlyEarned method requires clear specification of the Duration parameter's expected range.
Dual execution context (backend and mobile) means the repository implementation must be validated in both environments, particularly around Supabase client initialisation differences.
This repository maps directly to the earned_badges table in Supabase, providing typed CRUD and query methods. The existsForPeerMentor check is critical and should be called before any insert to enforce the uniqueness constraint at the application layer — even if the database enforces it, catching it early produces cleaner error handling. findRecentlyEarned uses a Duration window and should translate this to a timestamp range filter pushed down to Supabase for efficiency. Both findByPeerMentor and findByOrganisation should use indexed foreign key columns.
In mobile context, the Supabase Flutter client is used; in backend context, a server-side Supabase client. Ensure row-level security policies align with these dual access patterns.
Responsibilities
- Insert earned badge records with timestamps
- Query earned badges by peer mentor and organisation
- Enforce uniqueness of badge per peer mentor
- Support coordinator queries for team badge overview
Interfaces
insert(EarnedBadge badge) -> EarnedBadge
findByPeerMentor(String peerMentorId) -> List<EarnedBadge>
findByOrganisation(String organisationId) -> List<EarnedBadge>
existsForPeerMentor(String badgeDefinitionId, String peerMentorId) -> bool
delete(String earnedBadgeId)
findRecentlyEarned(String peerMentorId, Duration window) -> List<EarnedBadge>
Relationships
Dependents (5)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component