Admin Statistics Service
Component Detail
Description
Aggregates KPI metrics across the org hierarchy for dashboard display. Fetches counts of active peer mentors, monthly activities, pending reimbursements, paused mentors, and expiring certifications scoped to the requesting admin's org tree node. Respects row-level security by delegating queries to RLS-enforced Supabase views.
admin-statistics-service
Summaries
The Admin Statistics Service is the analytical backbone of the administrator experience, transforming raw operational data into the KPI metrics that drive governance decisions. By aggregating activity counts, pending reimbursements, paused mentors, and certification risks in real time, it enables leaders to identify problems before they affect participants or grant compliance. Its caching layer ensures dashboards load quickly without overloading the database, protecting system reliability during peak reporting periods. This service directly underpins the organization's ability to self-monitor program health without expensive manual reporting processes.
Admin Statistics Service is a high-complexity backend component due to its role as a shared aggregation layer for multiple admin-facing features. It depends on admin-repository and org-hierarchy-service, both of which must be stable for integration testing. The row-level security delegation to Supabase RLS views adds significant QA surface area — every stat method must be tested against multiple org tree positions to verify correct scoping. The caching layer (short TTL invalidation via invalidateCache(orgId)) introduces cache coherence scenarios that need explicit test coverage.
Performance testing under concurrent admin sessions is critical, as cache misses under load could degrade dashboard responsiveness. Plan for a dedicated performance testing sprint before release.
Admin Statistics Service is a backend service class that wraps admin-repository queries with aggregation logic and a caching layer. Each public method (getDashboardStats, getActiveMentorCount, etc.) should resolve to an org-scoped Supabase view query delegated via admin-repository, ensuring RLS enforcement happens at the database layer rather than in application code. Trend indicators (month-over-month change) require two time-windowed queries per metric — consider a shared time-window utility to avoid duplication. Cache keys should encode orgId and metric type; TTL of 60–300 seconds is appropriate for dashboard freshness.
invalidateCache(orgId) should clear all keys under a given org subtree, not just the exact node, to maintain consistency across hierarchical queries. Use a consistent async interface pattern (Promise-based or Observable) across all stat methods to simplify consumer integration.
Responsibilities
- Aggregate activity, user, and reimbursement counts for a given org scope
- Compute trend indicators (month-over-month change) for each KPI
- Cache results with short TTL to reduce repeated Supabase calls
Interfaces
getDashboardStats(orgId) -> DashboardStats
getActiveMentorCount(orgId) -> int
getMonthlyActivityCount(orgId, month) -> int
getPendingReimbursementCount(orgId) -> int
getPausedMentorCount(orgId) -> int
getExpiringCertificationCount(orgId, daysThreshold) -> int
invalidateCache(orgId)
Relationships
Dependencies (2)
Components this component depends on
Dependents (4)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component