Reports and Analytics

Overview

Sunschool provides comprehensive reports and analytics for parents to track learner progress, identify trends, and celebrate achievements. The reports system aggregates data from lessons, quizzes, concepts, and points to provide actionable insights.

Report Types

Progress Report

Overall learning progress and completion metrics

Lessons Report

Detailed lesson history and performance

Achievements Report

All earned achievements and milestones

Reports Page Structure

// From client/src/pages/reports-page.tsx:16
const ReportsPage: React.FC = () => {
  const { user } = useAuth();
  const [selectedLearnerId, setSelectedLearnerId] = useState<number | null>(null);
  const [selectedReportType, setSelectedReportType] = useState<string>('progress');

  // Fetch learners
  const { data: learners } = useQuery({
    queryKey: ["/api/learners", user?.id, user?.role],
    queryFn: () => {
      if (user?.role === 'PARENT') {
        return apiRequest('GET', "/api/learners").then(res => res.data);
      }
      return Promise.resolve([]);
    },
    enabled: user?.role === 'PARENT' && !!user?.id,
  });

  // Fetch report data
  const { data: reportData } = useQuery({
    queryKey: [`/api/reports`, selectedLearnerId, selectedReportType],
    queryFn: () => 
      apiRequest('GET', 
        `/api/reports?learnerId=${selectedLearnerId}&type=${selectedReportType}`
      ).then(res => res.data),
    enabled: !!selectedLearnerId,
  });

  // ... render reports
};

Progress Report

The Progress Report shows high-level metrics and trends:

Key Metrics

Concepts Learned
Lessons Completed
Achievements Count
Progress Rate

Total number of unique concepts the learner has been exposed to across all subjects.

Count of lessons with status === 'DONE'.

Visual Components

// From client/src/pages/reports-page.tsx:165
<View style={styles.statsContainer}>
  <View style={styles.statCard}>
    <Text style={styles.statValue}>{analytics?.conceptsLearned || 0}</Text>
    <Text style={styles.statLabel}>Concepts Learned</Text>
  </View>
  <View style={styles.statCard}>
    <Text style={styles.statValue}>{analytics?.lessonsCompleted || 0}</Text>
    <Text style={styles.statLabel}>Lessons Completed</Text>
  </View>
  <View style={styles.statCard}>
    <Text style={styles.statValue}>{analytics?.achievementsCount || 0}</Text>
    <Text style={styles.statLabel}>Achievements</Text>
  </View>
</View>

<View style={styles.progressContainer}>
  <View style={styles.progressBarContainer}>
    <View 
      style={[
        styles.progressBar, 
        { width: `${analytics?.progressRate || 0}%` }
      ]} 
    />
  </View>
  <Text style={styles.progressText}>
    {Math.round(analytics?.progressRate || 0)}% Complete
  </Text>
</View>

Subject Distribution

Shows how lessons are distributed across subjects:

// From client/src/pages/reports-page.tsx:198
<View style={styles.subjectDistribution}>
  {analytics?.subjectDistribution && 
   Object.keys(analytics.subjectDistribution).length > 0 ? (
    Object.entries(analytics.subjectDistribution).map(([subject, count], index) => (
      <View key={subject} style={styles.subjectItem}>
        <Text style={styles.subjectName}>{subject}</Text>
        <View style={styles.subjectBarContainer}>
          <View 
            style={[
              styles.subjectBar, 
              { 
                width: `${(count / maxCount) * 100}%`,
                backgroundColor: colors.primary 
              }
            ]} 
          />
        </View>
        <Text style={styles.subjectCount}>{count} lessons</Text>
      </View>
    ))
  ) : (
    <Text style={styles.emptyText}>No data available yet</Text>
  )}
</View>

Lessons Report

Detailed view of all completed lessons:

Lesson History Data

interface LessonHistoryItem {
  id: string;
  topic: string;
  subject: string;
  gradeLevel: number;
  score: number;
  status: 'IN_PROGRESS' | 'DONE';
  completedAt?: Date;
  timeSpent?: number; // minutes
}

Filtering and Sorting

By Subject
By Grade Level
By Date Range
By Score

Filter to show only Math, Science, or other specific subjects

Performance Trends

Shows score trends over time:

interface PerformanceTrend {
  date: string;
  averageScore: number;
  lessonCount: number;
}

// Calculate 7-day moving average
const calculateMovingAverage = (lessons: Lesson[], windowSize: number = 7) => {
  const sorted = lessons
    .filter(l => l.status === 'DONE' && l.score !== null)
    .sort((a, b) => new Date(a.completedAt).getTime() - new Date(b.completedAt).getTime());
  
  const trends: PerformanceTrend[] = [];
  
  for (let i = windowSize - 1; i < sorted.length; i++) {
    const window = sorted.slice(i - windowSize + 1, i + 1);
    const avgScore = window.reduce((sum, l) => sum + l.score, 0) / window.length;
    
    trends.push({
      date: sorted[i].completedAt,
      averageScore: Math.round(avgScore),
      lessonCount: window.length
    });
  }
  
  return trends;
};

Achievements Report

Displays all earned achievements with dates and details:

Achievement Display

// Render achievements with badges
achievements.map(achievement => (
  <View key={achievement.type} style={styles.achievementCard}>
    <AchievementBadge 
      achievement={achievement.payload}
      size="medium"
    />
    <View style={styles.achievementDetails}>
      <Text style={styles.achievementTitle}>{achievement.payload.title}</Text>
      <Text style={styles.achievementDescription}>
        {achievement.payload.description}
      </Text>
      <Text style={styles.achievementDate}>
        Earned on {formatDate(achievement.earnedAt)}
      </Text>
    </View>
  </View>
))

Achievement Categories

Milestones

First Steps, Learning Explorer (lesson count milestones)

Excellence

Perfect Score achievements

Mastery

Subject mastery achievements (future)

Consistency

Streak achievements (future)

Export Capabilities

Download Full Report

// From client/src/pages/reports-page.tsx:70
const handleDownloadReport = () => {
  if (!selectedLearnerId) return;
  window.open(`/api/export?learnerId=${selectedLearnerId}`, '_blank');
};

Export Formats

PDF
CSV
JSON

Formatted PDF report with charts and tables

Cover page with learner info
Summary statistics
Subject breakdowns
Detailed lesson history
Achievement gallery

Performance Metrics Visualization

Concept Mastery Heatmap

Visual grid showing mastery levels:

interface MasteryHeatmapData {
  concept: string;
  subject: string;
  masteryLevel: number; // 0-100
  lastTested: Date;
}

// Color coding
const getMasteryColor = (level: number) => {
  if (level >= 85) return '#4CAF50';  // Green - Advanced
  if (level >= 70) return '#2196F3';  // Blue - Proficient
  if (level >= 40) return '#FFC107';  // Yellow - Developing
  return '#F44336';                    // Red - Struggling
};

Subject Progress Chart

Shows mastery percentage by subject:

const subjectProgress = {
  'Math': 78,
  'Science': 85,
  'Reading': 72,
  'Social Studies': 65
};

// Render as horizontal bar chart
Object.entries(subjectProgress).map(([subject, mastery]) => (
  <View key={subject} style={styles.progressRow}>
    <Text style={styles.subjectLabel}>{subject}</Text>
    <View style={styles.progressBarOuter}>
      <View 
        style={[
          styles.progressBarInner,
          { 
            width: `${mastery}%`,
            backgroundColor: getMasteryColor(mastery)
          }
        ]}
      />
    </View>
    <Text style={styles.masteryPercent}>{mastery}%</Text>
  </View>
))

Analytics API Endpoints

Get Report Data

GET /api/reports?learnerId={id}&type={reportType}

Response:
{
  "profile": {
    "id": 42,
    "name": "Alice",
    "gradeLevel": 5
  },
  "analytics": {
    "conceptsLearned": 45,
    "lessonsCompleted": 28,
    "achievementsCount": 5,
    "progressRate": 76,
    "subjectDistribution": {
      "Math": 12,
      "Science": 8,
      "Reading": 6,
      "Social Studies": 2
    },
    "averageScore": 82,
    "totalTimeSpent": 420  // minutes
  },
  "lessons": [...],
  "achievements": [...]
}

Export Data

GET /api/export?learnerId={id}&format={format}

Formats: 'pdf' | 'csv' | 'json'

Returns: File download with appropriate Content-Type headers

Customization Options

Parents can customize their reports:

Date Range Selection

Choose to view data from:

Last 7 days
Last 30 days
Last 3 months
All time
Custom date range

Metric Selection

Toggle which metrics to display:

Overall progress
Subject breakdowns
Concept mastery
Time spent
Points earned
Achievements

Visualization Type

Choose chart types:

Bar charts
Line charts
Pie charts
Heatmaps
Tables

Comparison Mode

Compare multiple learners:

Side-by-side metrics
Relative performance
Shared subjects

Insights and Recommendations

Reports include automated insights:

Strengths
Areas for Growth
Engagement Patterns
Next Steps

Strong Performance Detected:“Alice shows exceptional mastery in Science concepts (85% average). Consider introducing more advanced topics in Earth Science and Biology.”

Scheduled Reports

Parents can schedule automatic report delivery:

interface ScheduledReport {
  learnerId: number;
  frequency: 'daily' | 'weekly' | 'monthly';
  dayOfWeek?: number; // 0-6 for weekly
  dayOfMonth?: number; // 1-31 for monthly
  time: string; // HH:MM format
  email: string;
  format: 'pdf' | 'summary'; // PDF attachment or email summary
}

// Example: Weekly email every Monday at 9 AM
{
  learnerId: 42,
  frequency: 'weekly',
  dayOfWeek: 1,
  time: '09:00',
  email: 'parent@example.com',
  format: 'summary'
}

Mobile-Optimized Views

Reports are responsive and mobile-friendly:

Card Layout

Stats displayed as cards that stack vertically on mobile

Swipeable Charts

Horizontal scrolling for charts on small screens

Collapsible Sections

Accordion-style sections to reduce scrolling

Touch-Friendly

Large tap targets for filters and controls

Best Practices for Parents

Review Weekly

Check reports at least once per week to stay informed about progress and catch issues early.

Look for Trends

Don’t focus on individual scores. Look for patterns over time—improving, declining, or stable.

Celebrate Progress

Use the achievements report to recognize and celebrate milestones with your learner.

Act on Insights

When reports show struggling areas, take action—assign targeted practice or adjust difficulty.

Privacy and Data Security

Reports contain personal educational data and should be treated as confidential.

Reports are only accessible to the parent account
Learners cannot access other learners’ reports
Export files are not cached server-side
All API requests require authentication

Future Enhancements

Predictive Analytics

ML models to predict future performance and suggest interventions

Benchmark Comparisons

Compare against grade-level averages (anonymized data)

Goal Tracking

Set custom learning goals and track progress toward them

Interactive Dashboards

Drill-down capabilities to explore data at granular levels

Mastery System

Concept mastery calculations powering analytics

Concept Tracking

Per-concept performance data

Points System

Points earning patterns and history

​Overview

​Report Types

Progress Report

Lessons Report

Achievements Report

​Reports Page Structure

​Progress Report

​Key Metrics

​Visual Components

​Subject Distribution

​Lessons Report

​Lesson History Data

​Filtering and Sorting

​Performance Trends

​Achievements Report

​Achievement Display

​Achievement Categories

Milestones

Excellence

Mastery

Consistency

​Export Capabilities

​Download Full Report

​Export Formats

​Performance Metrics Visualization

​Concept Mastery Heatmap

​Subject Progress Chart

​Analytics API Endpoints

​Get Report Data

​Export Data

​Customization Options

​Insights and Recommendations

​Scheduled Reports

​Mobile-Optimized Views

Card Layout

Swipeable Charts

Collapsible Sections

Touch-Friendly

​Best Practices for Parents

​Privacy and Data Security

​Future Enhancements

Predictive Analytics

Benchmark Comparisons

Goal Tracking

Interactive Dashboards

​Related Features

Mastery System

Concept Tracking

Points System

Overview

Report Types

Reports Page Structure

Progress Report

Key Metrics

Visual Components

Subject Distribution

Lessons Report

Lesson History Data

Filtering and Sorting

Performance Trends

Achievements Report

Achievement Display

Achievement Categories

Export Capabilities

Download Full Report

Export Formats

Performance Metrics Visualization

Concept Mastery Heatmap

Subject Progress Chart

Analytics API Endpoints

Get Report Data

Export Data

Customization Options

Insights and Recommendations

Scheduled Reports

Mobile-Optimized Views

Best Practices for Parents

Privacy and Data Security

Future Enhancements

Related Features