Feature Owner: clydetims (Clyde Ador), Christian Denzon
Module: Dashboards — Analytics & Reporting
Date: October 2 2026
Executive Summary
What is this feature?
11.6 Analytics & Reporting gives Agency Owners/Admins and Creators a single place to see how learners and groups are performing. It has two surfaces over one shared data model: the Agency Analytics dashboard (`/agency/analytics`) with Overview, Hierarchy View, Performance, Engagement and Comparison tabs plus drill-in detail pages; and the Creator Group Analytics page (`/creator/analytics`) with eight metric cards, a parent-group → subgroup → member drill-in, and a comparison tool with parent/subgroup modes. It also adds monthly Most Visited Pages reporting, daily completion snapshots, and a shared quest-scope resolver so assigned-quest and completion numbers match everywhere.
Why does it matter?
Agencies are accountable for cohort learning outcomes. Before this work, admins exported raw CSVs and rebuilt charts by hand, and the creator and agency screens could report different completion numbers. Creators had no cohort view, no comparison and no trend. This feature removes the manual reporting work and makes the numbers trustworthy and consistent.
What's the MVP scope?
Agency analytics dashboard (five tabs, five detail pages, empty/error states).
Creator hierarchy view (creator → parent group → subgroup → member) and eight metric cards.
Add Group / Add Sub Group with correct creator attribution.
Export All, per-creator export, and agency-wide Export Report (CSV).
Group comparison (Parents | Subgroups) with a completion-rate trend chart.
Real completion history via daily snapshots (projection fallback until history exists).
Most Visited Pages (top 5/month) and per-learner visited pages.
Consistent assigned-quest and completion-rate calculation across both surfaces.
1. User Pain Point & Solution
Maria runs an agency with several creators, dozens of cohorts and hundreds of learners. Every month she pulls a CSV, cleans it, and rebuilds the same charts in a spreadsheet, then answers the same questions by hand: Which cohort is behind? Is completion going up or down? What pages do learners open most? Her creators face the same problem at smaller scale and cannot compare their own cohorts.
Pain Points
Emotional: Frustrated and exposed when reporting takes hours and the numbers cannot be trusted because two screens disagree.
Functional: No group-level view, no trend, no comparison, no content-engagement data, and no way to fix a mis-attributed group without support.
Business: Slow reporting and inconsistent completion rates prevent early intervention and make it hard to prove agency impact.
2. User Pain Point & Solution
Diagnose: Identifies which groups and learners are progressing or at risk via metric cards (Avg Completion, At-Risk Groups, Engagement Rate), the hierarchy drill-in, performance/engagement panels, and monthly Most Visited Pages.
Design: Provides structure for planning intervention with a consistent two-level hierarchy (main group → subgroup), in-context group creation, and comparison modes that let an admin choose what to contrast.
Develop: One agency hierarchy API and one creator hierarchy API feed every view. A shared quest-scope resolver merges the two assignment sources, and completion snapshots accrue from real analytics loads.
Deliver: Delivers measurable outputs: KPI cards, comparison charts, completion trends, CSV reports, and page-engagement reporting for stakeholder review.
3. USER FLOWS
Entry Points: Agency Owner/Admin opens Analytics from the agency sidebar (`/agency/analytics`). Creator opens Analytics from creator navigation (`/creator/analytics`). Learners never see analytics; they generate page-visit and progress data while using quests.
Success Criteria: An agency member sees accurate, agency-scoped group and learner performance, can compare groups and export a report, and sees the same quest/completion numbers as the creator view. A creator sees cohort metrics, drills into members and reads a completion trend. Tracking never blocks a learner.
Main Path (Happy Path)
1. Agency Owner/Admin opens `/agency/analytics`.
2. System loads the creator → parent group → subgroup → member hierarchy.
3. Overview shows KPI cards; Hierarchy View shows the expandable structure.
4. Admin expands a creator and parent group to reach subgroups and members.
5. Admin uses Add Group / Add Sub Group to create a cohort under the right creator.
6. Admin reviews Performance and Engagement, then opens a detail page.
7. Admin opens Most Visited Pages and selects a month.
8. Admin clicks Export Report and downloads the CSV.
9. Creator opens `/creator/analytics`; eight metric cards render.
10. Creator expands a group, opens a learner panel, compares groups, and reads the trend.
11. Learner opens a quest; one visit per page path is recorded and appears in reports.
Empty state: Show "No agency data yet", "No pages to display yet", or "No page visits recorded this month" instead of an error.
API failure: Show the error state with Retry on first load; on background refresh keep last good data and show a toast. Page-visit failures are invisible to the learner.
Permission denied: Block non-agency users; hide management buttons for roles that cannot manage and reject forged requests server-side.
Stale data: Abort stale in-flight requests; keep the last good data on a failed refresh.
Decision Points:
IF the user is an agency member THEN allow analytics ELSE deny access.
IF the user is Owner/Admin/Creator THEN show management buttons ELSE hide them.
IF adding a group for another creator THEN require Owner/Admin ELSE attribute to the signed-in creator.
IF a selected group has at least two captured snapshot days THEN show the real trend ELSE show the projection.
IF a quest visit has an owning agency THEN attribute to it; IF no quest context THEN use the learner's agency; IF the quest has no agency THEN skip the visit.
IF an export has no rows THEN warn ELSE download the CSV.
4. Information Architecture
Primary Information
Creator identity (name, email, avatar).
Parent group / subgroup name, description, status.
Member name, email, avatar, added date.
Member completion rate, XP, badges, assigned quests.
Group average completion and member counts.
Page title/path and visit count.
Secondary Information
Created/updated/archived timestamps.
Member last visited time.
Subgroup manager.
Selected month / time range.
Comparison mode (Parents | Subgroups).
Tertiary Information
Snapshot capture date and real-vs-projected flag.
Raw page path behind a page title.
CSV filename and badge names in the export.
Per-group canView / canEdit / canManage flags.
Actions
Primary CTA
• "Export Report"
Secondary Actions
• Add Group
• Add Sub Group
• Expand / collapse creator, parent group, subgroup
• Edit / Archive / Delete group
• Open learner side panel
• Switch tabs
• Change month / time range
• Select comparison groups and toggle Parents | Subgroups
• Retry a failed load
5. Data Requirements
Frontend Needs
• Agency id and membership role.
• Creator profile fields.
• Parent group and subgroup fields (name, description, status, timestamps, manager).
• Member fields (learner id, name, email, avatar, added date, last visited, XP, badges).
• Member quests with progress percentage.
• Group average completion.
• Completion snapshot points (group id, level, value, capture date).
• Top visited pages per month (path, title, visit count).
• Viewer capability flags (canManage, canCreateForAnyCreator).
API Calls Frontend Will Make
• GET `/api/agency/analytics`
• GET `/api/agency/groups/main?limit=100`
• GET `/api/agency/groups/subgroups`
• POST `/api/agency/groups/main`
• PATCH `/api/agency/groups/main/[id]`
• DELETE `/api/agency/groups/main/[id]`
• POST `/api/agency/groups/subgroups`
• GET `/api/agency/analytics/most-visited?month=YYYY-MM`
• GET `/api/agency/analytics/learner-pages?learner_id=&month=&limit=`
• POST `/api/learner/track-visit`
6. Performance Considerations
Database Optimization
One bulk stats RPC (`get_learner_group_stats_bulk`) replaces one call per subgroup.
Id lookups are chunked (batch size 100) to avoid oversized filters.
Page-visit counts are aggregated in SQL so raw rows are never shipped to the app server.
Indexes on agency/date and page_path/date support monthly scans.
Snapshot growth is bounded to roughly one row per group per day.
Snapshot capture runs after the response is sent and is best-effort.
7. Security & Authorization
Who Can Access This Feature?
Administrator: No access to these dashboards.
Reviewer: Read access to analytics where permitted; no group management actions.
Creator: Creator and agency analytics for their agency; group editing for owned or explicitly granted groups; no creating groups for other creators.
Learner: No access to analytics; generates page-visit and progress data only.
Agency Admin: Full analytics, group management and export.
Agency Owner: Full analytics, group management and export; may create groups on behalf of any creator.
8. Error Handling
Current Existing Error Handling
• Invalid request body or params -> validation error; fix input or Retry.
• Missing analytics migrations -> "Main groups are not yet available. Push the database migrations first."
• Unauthenticated request -> 401 Unauthorized; sign in.
• No edit/delete rights -> 403 Forbidden; buttons hidden and forged request rejected.
• Group not found or wrong agency -> 404 "Main group not found"; refresh.
• Duplicate sub group name -> 422 "A sub group with this name already exists"; rename.
• Creator role flags unresolved -> 500 retryable "Unable to resolve group access right now. Please try again."
• Unexpected server/DB error -> 500 "Failed to load analytics"; retry.
• Page-visit skipped or failed -> 200 `{ tracked:false }`; invisible to the learner.
• Empty export -> warning "No learner data to export yet."
9. Testing Checklist
Happy Path
• Agency member opens `/agency/analytics`; all five tabs render.
• Hierarchy expands creator → parent group → subgroup → member.
• Add Group / Add Sub Group create under the correct creator.
• Edit / archive / delete update the group correctly.
• Export Report downloads `agency_analytics_report.csv`.
• Creator page shows all eight metric cards with live values.
• Comparison works in Parents and Subgroups modes.
• Completion chart shows projection then real data after two captured days.
• Most Visited Pages shows the top 5 for the selected month.
• Learner side panel shows visited pages and last visited.
Edge Cases
• Agency with no groups or no learners; group with no members.
• Quest assigned through both sources is counted once.
• Learner in two subgroups does not repeat another subgroup's quest list.
• Reviewer cannot manage groups; forged request returns 403.
• Junk or script-like page paths rejected.
• Preview, shared-link and SCORM modes do not record visits.
• Snapshot table missing -> projection fallback, no error.
Month with no visits shows the empty message.
Duplicate sub group name returns 422.
Page-visit failure does not block navigation.
10. OPEN QUESTIONS
• Should completion snapshots be backfilled from historical enrollment data instead of starting at first deploy?
• Should `page_visits` have a retention or pruning policy, and for how long?
• Should the creator page paginate parent groups beyond `limit=100`?
• Should the exported report honor active tab filters or always export the full dataset?
• Should Most Visited Pages support sorting, more than 5 rows, or a date range?
11. OUT OF SCOPE
• Scheduled or emailed reports (not in MVP; possible v2).
• PDF export (CSV covers reporting; v2).
• Cross-agency comparison (tenant complexity; v2).
• Real-time streaming analytics (load/refetch is sufficient; v2).
• Editing learner progress from analytics (separate learner-management concern; v2).
• Presence and activity-log features (separate module).
12. SUCCESS METRICS
• Admin can review group and learner performance without exporting.
• Admin can export a report in one action.
• Assigned-quest and completion-rate values match between agency and creator views.
• Creator can identify at-risk groups from the metric cards.
• Completion trend shows real history once two days of data exist.
• Admin can identify the top content by visits per month.
• Page-visit tracking never blocks a learner.
18. DEPENDENCIES
This feature depends on
Learner Groups (11.4/11.5) and cohort enrollment (`group_enrollments`).
Quest editor → enrollment → Assign-To-Groups flow.
Quest gamification (`quest_gamifications`) for XP awards.
Supabase Auth and Supabase Postgres.
Recharts (charts) and Zod (validation).
Migrations: `20260806_create_learner_groups.sql`, `20260816_01_create_main_learner_groups.sql`, `20260816_03_learner_group_hierarchy_rpc.sql`, `20260821_learner_group_stats_bulk_rpc.sql`, `20260821_create_group_completion_snapshots.sql`, `20260821_add_learner_xp_rpc.sql`, `20260907_create_page_visits_table.sql`, `20260909_harden_page_visits_paths.sql`.
This feature depends on this
Agency dashboard and reporting.
Creator Hub group management surfaces (shared hierarchy API).
Learner page-visit reporting consumed by agency analytics.
19. TIMELINE & OWNERSHIP
Backend: clydetims (Clyde Ador)
Frontend: clydetims (Clyde Ador)
QA: Internal development testing
Estimated Completion: Merged to develop (PRs #781, #789, #797, #805, #808)
