src/app/scm/
├── podsie/           # Velocity tracking, progress, weekly reports
│   ├── velocity/     # Class velocity tracker
│   ├── progress/     # Student progress tracking
│   ├── weekly/       # Weekly summary reports
│   ├── pace/         # Pacing analysis
│   └── hooks/        # Shared podsie hooks
├── roadmaps/         # Skills mastery and curriculum
│   ├── history/      # Assessment history
│   ├── progress/     # Roadmap completions
│   ├── mastery-grid/ # Student mastery visualization
│   ├── skills/       # Skill browser
│   ├── units/        # Unit browser
│   └── hooks/        # Shared roadmaps hooks
└── ...

import { ... } from "@/hooks/scm";

// Get all section configs with colors
const { sectionOptions, sectionColors, loading } = useSectionOptions();

// Get unique sections from students
const { sections, loading } = useSections();

// Get days off for a school year
const { daysOff, loading } = useDaysOff(schoolYear);

// Get current units for all sections
const { currentUnits, loading } = useCurrentUnits(schoolYear);

// Get velocity data for selected sections
const { velocityData, detailData, unitScheduleData, loadingSectionIds } =
  useVelocityData(selectedSections, sectionOptions, schoolYear, includeNotTracked);

// Get weekly velocity aggregates
const { sectionData, loading, error } =
  useWeeklyVelocity(sections, startDate, endDate);

// Get all roadmap units
const { units, loading, error } = useRoadmapUnits();

// Get roadmap completion data for sections
const { roadmapData, loadingSectionIds } = useRoadmapData(selectedSections);

// Get all skills (for filter dropdowns)
const { allSkills, loading } = useAllSkills();

// Get filtered skills by grade/unit
const { skills, loading, error } = useFilteredSkills(selectedGrade, selectedUnit);

// Get student assessment data
const { data, loading, error } = useAssessmentData();

// Get Zearn completion data (with refetch for imports)
const { data, loading, error, refetch } = useZearnCompletions();

// Get Podsie completion data
const { data, loading, error } = usePodsieCompletions();

// Get students grouped by section
const { studentsBySection, loading } = useStudentsBySection();

"use client";

import { useState, useMemo, useEffect } from "react";
import { useSectionOptions, useRoadmapUnits } from "@/hooks/scm";

export default function MyPage() {
  const [selectedGrade, setSelectedGrade] = useState("");

  // Data fetching with React Query hooks
  const { sectionOptions, loading } = useSectionOptions();
  const { units } = useRoadmapUnits();

  // Derived data with useMemo
  const filteredUnits = useMemo(() => {
    if (!selectedGrade) return [];
    return units.filter(u => u.grade === selectedGrade);
  }, [selectedGrade, units]);

  // Side effects with useEffect
  useEffect(() => {
    // Clear selection when filter changes
  }, [selectedGrade]);

  // ... render
}

import { useQuery } from "@tanstack/react-query";

export const myDataKeys = {
  all: ["my-data"] as const,
  byId: (id: string) => [...myDataKeys.all, id] as const,
};

export function useMyData(id: string) {
  const { data, isLoading, error } = useQuery({
    queryKey: myDataKeys.byId(id),
    queryFn: async () => {
      const result = await fetchMyData(id);
      if (!result.success) {
        throw new Error(result.error);
      }
      return result.data;
    },
    staleTime: 60_000, // Cache for 1 minute
    enabled: !!id, // Only fetch when id exists
  });

  return {
    data: data || [],
    loading: isLoading,
    error: error?.message || null,
  };
}

import {
  SectionVisualizationLayout,
  SectionAccordion,
  type SectionOption,
  type AccordionItemConfig,
} from "@/components/composed/section-visualization";

src/app/actions/scm/
├── students.ts           # CRUD for students collection
├── student-data.ts       # Student dashboard data aggregation
├── section-config.ts     # Section configuration management
├── velocity/velocity.ts  # Velocity calculations
├── podsie-sync/          # Podsie API integration
├── podsie-completion.ts  # Podsie completion queries
├── roadmaps-units.ts     # Roadmap units CRUD
├── roadmaps-skills.ts    # Roadmap skills CRUD
├── roadmaps-lessons.ts   # Scope and sequence lessons
├── scope-and-sequence.ts # Curriculum sequence data
├── zearn-import.ts       # Zearn data import
└── analytics.ts          # Analytics aggregations

import { StudentZodSchema, type Student } from "@zod-schema/scm/student/student";

// Student document structure
interface Student {
  studentID: number;           // Unique identifier
  firstName: string;
  lastName: string;
  school: "IS313" | "PS19" | "X644";
  section: string;             // Class section (e.g., "802")
  gradeLevel?: string;
  email: string;
  active: boolean;

  // Progress tracking
  masteredSkills: string[];              // Skill numbers mastered
  skillPerformances: SkillPerformance[]; // Assessment attempts
  zearnLessons: ZearnLessonCompletion[]; // Zearn completions
  podsieProgress: PodsieProgress[];      // Podsie assignment progress
  classActivities: StudentActivity[];    // Logged activities
}

import { SectionConfigZodSchema, type SectionConfig } from "@zod-schema/scm/podsie/section-config";

// Section configuration for a class
interface SectionConfig {
  school: string;
  classSection: string;        // e.g., "802"
  teacher?: string;
  gradeLevel: string;
  scopeSequenceTag?: string;   // e.g., "Grade 8"
  groupId?: string;            // Podsie group ID
  specialPopulations: string[];
  bellSchedule?: BellSchedule;

  // Assignment configurations linking to scope-and-sequence
  assignmentContent: AssignmentContent[];

  // Smartboard YouTube links
  youtubeLinks: YoutubeLink[];
  activeYoutubeUrl?: string;
}

// Roadmap Units - skill groupings by unit
import { RoadmapUnitZodSchema, type RoadmapUnit } from "@zod-schema/scm/roadmaps/roadmap-unit";

interface RoadmapUnit {
  grade: string;               // e.g., "Illustrative Math NY - 7th Grade"
  unitTitle: string;           // e.g., "01 - Area and Surface Area"
  unitNumber?: number;
  targetSkills: string[];      // Primary skill numbers
  additionalSupportSkills: string[];
  extensionSkills: string[];
}

// Roadmap Skills - individual skill definitions
import { RoadmapSkillZodSchema, type RoadmapSkill } from "@zod-schema/scm/roadmaps/roadmap-skill";

// Scope and Sequence - curriculum lesson sequence
import { ScopeAndSequenceZodSchema, type ScopeAndSequence } from "@zod-schema/scm/scope-and-sequence/scope-and-sequence";

// Podsie completion tracking
import { PodsieCompletionZodSchema } from "@zod-schema/scm/podsie/podsie-completion";

// Learning content (worked examples, etc.)
import { LearningContentZodSchema } from "@zod-schema/scm/podsie/learning-content";

// Question mappings
import { PodsieQuestionMapZodSchema } from "@zod-schema/scm/podsie/podsie-question-map";

// From @/components/composed/section-visualization
interface SectionOption {
  id: string;
  school: string;
  classSection: string;
  teacher?: string;
  gradeLevel?: string;
  displayName: string;
  scopeSequenceTag?: string;
  specialPopulations?: string[];
}

// From hooks
interface SectionWeeklyData {
  section: string;
  school: string;
  totalMasteryChecks: number;
  totalStudents: number;
  masteryChecksPerStudent: number;
  attendance: {
    present: number;
    late: number;
    absent: number;
    total: number;
  };
}