SSC-17: Analytics & Progress Tracking Dashboard

[Sakeeb91]

Analytics & Progress Tracking Dashboard

Linear Issue: SSC-17
Priority: Medium
Feature Type: Premium Feature (PREMIUM+ subscription required)

Overview

Build a comprehensive analytics dashboard that shows students their learning progress, strengths, weaknesses, and study patterns. This replaces the current mock data implementation with real analytics powered by backend API endpoints.

Current State

• Frontend: Analytics page exists at apps/web/src/app/(dashboard)/analytics/page.tsx with mock data
• Database: StudySession, QuizAttempt, Flashcard, and AnalyticsEvent models already exist
• Feature Gating: Analytics is gated to PREMIUM+ tiers in config/pricing.ts

Implementation Plan

📄 Full implementation plan: docs/SSC-17-IMPLEMENTATION-PLAN.md

---

Phase 1: Database Schema Updates (Commits 1-3)

Commit 1: Add study streak tracking to User model

```prisma
model User {
// ... existing fields
currentStreak Int @default(0)
longestStreak Int @default(0)
lastStudyDate DateTime?
totalStudyTime Int @default(0) // Total minutes studied
}
```

Commit 2: Create UserAchievement model

```prisma
model UserAchievement {
id String @id @default(cuid())
userId String
achievementType AchievementType
achievementName String
unlockedAt DateTime @default(now())
metadata Json?

user User @relation(fields: [userId], references: [id], onDelete: Cascade)

@@unique([userId, achievementType, achievementName])
@@index([userId])
}

enum AchievementType {
STREAK // 7-day, 14-day, 30-day, 100-day
MASTERY // 100 cards, 500 cards mastered
QUIZ_SCORE // Perfect quiz, 90%+ accuracy
STUDY_TIME // 10 hours, 100 hours studied
CONSISTENCY // Early bird, night owl
MILESTONE // First quiz, first flashcard set
}
```

Commit 3: Add topic/tag analytics to StudySession

```prisma
model StudySession {
// ... existing fields
tags String[]
topicAccuracy Json? // { "topic1": 0.85, "topic2": 0.72 }
}
```

---

API Endpoints

Method	Endpoint	Description
GET	`/api/analytics/overview`	Overview stats with trends
GET	`/api/analytics/study-time`	Study time chart data
GET	`/api/analytics/topics`	Topic mastery breakdown
GET	`/api/analytics/weak-areas`	Areas needing improvement
GET	`/api/analytics/quizzes`	Quiz performance data
GET	`/api/analytics/flashcards`	Flashcard retention data
GET	`/api/analytics/activity`	Activity heatmap data
GET	`/api/analytics/predictions`	Exam readiness predictions
GET	`/api/analytics/achievements`	User achievements
POST	`/api/analytics/export`	Export progress report

All endpoints require PREMIUM+ subscription.

---

Checklist

Database

• Add streak fields to User model
• Create UserAchievement model
• Add AchievementType enum
• Add tags and topicAccuracy to StudySession
• Run migrations

Backend - Analytics Service

• Create `analytics.service.ts`
• Implement `getOverviewStats()`
• Implement `getStudyTimeByDay()`
• Implement `updateStreak()`
• Implement `getTopicMastery()`
• Implement `getWeakAreas()`
• Implement `getQuizPerformance()`
• Implement `getFlashcardRetention()`
• Implement `predictExamReadiness()`

Backend - Achievement Service

• Create `achievement.service.ts`
• Define all achievements
• Implement unlock logic
• Implement progress tracking

Backend - API

• Create `analytics.controller.ts`
• Create `analytics.routes.ts`
• Add subscription middleware
• Wire up all endpoints

Frontend

• Install Recharts
• Create analytics API client
• Create analytics context
• Rewrite analytics page with real data
• Add achievements section
• Add export functionality

---

Success Criteria

• Analytics page shows real user data
• Time range filtering works (week/month/quarter/year)
• Study streak updates automatically
• Achievements unlock at correct thresholds
• Topic mastery calculation is accurate
• PDF and Excel exports work
• Page loads in <2 seconds
• Mobile-responsive
• Properly gated for PREMIUM+ users