History Ops — Tactical Study Command

Complete Platform Explainer

History Ops is a retro, military-themed learning platform that turns social-studies review into a mission. Teachers deploy units of study questions; students drill those questions and "unlock" an arcade-style game tied to each unit. Every action is logged, scored, and analyzed — including automatic alignment to Texas TEKS standards — so teachers get continuous, actionable intelligence on their class.

The platform runs on a single shared architecture: there is one portal for students and one control center for teachers, all behind a CRT-styled, scan-line "operations terminal" interface.

1. How It Works At A Glance

• A teacher creates Units (e.g., "Unit 1: Exploration"). Each unit is tied to a game type and protected by a passcode students enter.
• The teacher uploads a PDF or PowerPoint (or a CSV) and the system auto-generates multiple-choice questions, each tagged with a TEKS standard code if a TEKS source PDF is configured.
• A student enters the unit passcode, studies the questions, and once they answer enough correctly, the game unlocks as a reward.
• The student plays the arcade game; performance (score, difficulty reached, duration) is logged.
• Everything the student does — study accuracy, missed questions, game scores, time on task — feeds into a series of reports that rank students, flag strugglers, correlate strengths/weaknesses to TEKS standards, and generate AI "mission intel" narratives.

2. The Student Portal

The student-facing side is the entry point after login. It shows:

Mission Select

• A grid of active units (units the teacher has switched "on"). Disabled units are hidden from students.
• Each mission card shows the unit name and its associated game. A student taps a unit, enters that unit's passcode, and begins the study phase.
• Units are ordered as the teacher arranges them.

Leaderboard

• A live weekly leaderboard appears alongside the mission grid.
• Students can navigate between weeks to see rankings by score and activity.
• Top performers get visual rank highlights; the full list is scrollable.
• Students see how they stack up against classmates — a motivator — but only see names/scores, not other students' private details.

Student Profile

• Each student has a profile page showing their personal activity history, session-by-session accuracy line chart, and earned unit medals.

3. The Study Session & Game Unlock Flow

When a student enters a unit:

1. Study mode — The student is presented with the unit's multiple-choice questions, one at a time, with immediate correct/incorrect feedback and explanations.
2. Unlock threshold — A teacher-configured setting (correct_answers_to_unlock, default 5) determines how many correct answers are required before the game becomes available.
3. Game mode — Once unlocked, the student launches the unit's arcade game. The game runs for a teacher-configured duration (game_time_seconds, default 180s).
4. Logging — Both study and game sessions create a StudentActivity record capturing:

• questions answered / correct
• the text of every missed question (this is what powers TEKS correlation)
• difficulty reached, score, duration
• whether the session was completed

4. The Game Library

Every unit is paired with one of six retro arcade games. Each game is rendered in the same CRT-green military aesthetic and logs a StudentActivity record on completion.

Each game returns the student to the study screen after it ends, with difficulty increasing for the next attempt.

5. Teacher Mission Control (Dashboard)

The teacher dashboard is the administrative nerve center. It is gated to admin users and organized into tabs:

UNITS Tab (default)

• Unit selector bar — every unit appears as a button. Selecting one reveals its detail panel. Each unit has a small per-student drilldown button and a power toggle to enable/disable it for students.
• Unit detail panel shows:
• The unit name, game type (editable inline dropdown), passcode, and active/inactive status.
• Upload buttons: UPLOAD PDF (auto-generates questions with TEKS tagging), UPLOAD CSV (manual bulk import), and NOTIFY (email students about the new questions).
• Question library list for the selected unit:
• Each question shows its text, all four options, the correct answer, optional explanation, and a TEKS code badge (if tagged).
• Per-question edit and delete actions.
• Bulk controls: select-all checkbox, DELETE SELECTED, and DELETE ALL (both behind a type-to-confirm modal to prevent accidents).
• RETAG WITH TEKS button — retroactively re-tags the unit's questions against the configured TEKS source PDF.
• NEW UNIT modal — create a unit with name, description, game type, and student passcode.

STUDENT ANALYTICS Tab

• Per-student performance metrics: sessions, accuracy, time on task, scores.
• A Struggling Students Alert banner surfaces students below an accuracy threshold, with a one-click "notify" action that pre-fills an intervention email.

CLASS OVERVIEW Tab

• A daily activity chart (sessions + unique students) with selectable time ranges.
• The Master Report (detailed in section 6).

SCHOOLS Tab

• Multi-school overview for organizations running the platform across several teachers/classes (see section 8).

LEADERBOARD Tab

• A printable leaderboard with separate weekly and year-long views and dedicated print controls.

PARTICIPATION Tab

• A weekly participation report: alphabetical roster of students with session counts, duration, accuracy, and grading metrics; CSV-exportable and printable.

Top-Right Actions

• EXPORT — export question libraries and student activity logs to CSV.
• FEEDBACK — submit feedback/support tickets to the platform team.
• SETTINGS — configure global platform settings (see below).
• NOTIFY STUDENTS — broadcast an email to selected students.
• NEW UNIT — quick-create a unit.

Settings Modal

6. Reports & Analytics

Master Report (inside Class Overview)

The flagship printable report. Teachers can scope it by time (This Week / All Time) and by selected units, then print a clean, formatted document containing:

• Students by Performance Indicator — a pie chart grouping students into Excellent / Good / Okay / Needs Improvement / Low, with a color-coded breakdown bar showing counts and percentages.
• Questions Answered by Indicator — a second pie chart showing where the volume of student work concentrates.
• Student Rankings table — sorted by accuracy, with columns for accuracy %, performance indicator badge, trend (improving / declining vs. their own earlier sessions), total time on task, and time-per-unit breakdown.
• Top 3 Strengths — the units with the highest class accuracy.
• Top 3 Weaknesses — the units with the lowest class accuracy, plus the most-missed questions across the class.
• TEKS Standards Analysis (see section 7) — top struggled and mastered TEKS standards.

Student Analytics

• Drill-down per student: per-unit accuracy, session counts, high scores, engagement duration.
• Surfaces struggling students for proactive intervention.

Class Overview Chart

• Daily composed chart of session volume and average-accuracy trend line over a selectable window, with summary stat cards (total sessions, average accuracy, performance trend).

Printable Leaderboard

• Toggle between weekly and year-long views; rank-ordered with top-3 highlighting; print-optimized layout for posting in a classroom.

Weekly Participation Report

• An alphabetical roster (Last, First) showing each student's sessions, total time, and accuracy for the selected week; CSV export and print buttons. Great for attendance/grading cross-reference.

Unit Drilldown

• A modal showing per-student performance for a single unit: questions answered, accuracy %, high score, and a visual progress bar — quickly identifying who's engaged and who's struggling on a specific unit.

Mission Intel Report (per-student, AI-generated)

• After each study session, an AI "intel report" is generated for the student. It:
• Analyzes their performance stats and the specific questions they missed.
• Cross-references each missed question's text against the question library to retrieve its TEKS code, then injects those TEKS codes into the AI prompt.
• Produces a narrative with: performance summary, weak areas (TEKS-tagged), concepts to review, and tactical improvement tips.
• Reports are cached on the activity record so they render instantly on revisit.

Student Profile Page

• A per-student page showing their activity history, a session accuracy line chart, and unit medals earned.

7. TEKS Alignment System

TEKS (Texas Essential Knowledge and Skills) alignment is the platform's differentiator. Here's the full loop:

1. Source setup — The teacher uploads a TEKS standards PDF in Settings. It's stored as the teks_pdf_url app setting.
2. Auto-tagging at generation — When questions are extracted from a unit PDF/PPT (extractQuestions function), the TEKS source is passed along. The AI maps each generated question to the most relevant TEKS standard and writes both a teks_code (e.g., 8.1A) and teks_description onto the question.
3. Retroactive retagging — The retagQuestions function can re-process existing questions (all of them, or one unit) to add/update TEKS tags after a source PDF is first configured.
4. Weakness to TEKS correlation — In the Master Report, every missed-question text is matched back to the question library to find its TEKS code. The report then shows:

• Most Struggled Standards — TEKS codes ranked by total misses, with student counts and descriptions (top 10).
• Standards With No Recorded Misses — TEKS codes the class has effectively mastered (top 10).

1. Per-student TEKS intel — Mission Intel Reports inject the student's missed-question TEKS codes into the AI prompt, so each student's feedback names the exact standards they need to revisit.

This closed loop means a teacher can answer "which TEKS standard is my class struggling with?" directly from the Master Report, and a student gets a personalized, standards-referenced study plan after every session.

8. External Teachers & Multi-School Support

The platform supports an administrator overseeing multiple schools/teachers:

• Teacher records store a teacher's full name, school name, email, a unique class code, and a linked user ID.
• Students join a specific teacher's class via the class code; their activity is stamped with that teacher's ID.
• The Schools Overview tab gives the admin a ranked dashboard of all schools: per-teacher student counts, session totals, and engagement metrics, with a drill-down into any single teacher's class showing their students' performance.
• Settings are scoped — global/admin settings apply platform-wide; teacher-scoped settings (via teacher_id) allow per-class configuration where needed.

9. Notifications, Email & Export

• Email notifications — Teachers can email registered students directly from the dashboard (single student, selected group, or whole class), with pre-filled intervention or "new questions available" templates. Email is sent via the platform's email integration (and a connected Gmail connector for outbound).
• Weekly class reports — The weeklyClassReport function compiles and emails a weekly summary to the configured teacher email.
• Feedback — The Feedback modal lets a teacher submit support queries to the platform team via the sendTeacherFeedback function.
• Data export — Question libraries and student activity logs can be exported to CSV from the Export modal for use in gradebooks or external analysis.

10. Backend Functions & Automations

These functions back the dashboard buttons of the same names.

11. Accounts, Security & Data Model

Accounts

• Standard authentication (email/password + Google OAuth, OTP verification, password reset).
• Two roles: admin (full Mission Control access) and user (students).
• Only admins can list/update/delete other users; students can't access the teacher dashboard.

Core Data Entities

Privacy & Safety

• Student activity is tied to student name/email and the owning teacher; the multi-school scoping keeps one teacher's class data isolated from another's.
• No large files are stored in entity fields — uploaded documents live as file URLs.
• Destructive bulk actions (delete all/selected questions) require a typed confirmation to prevent accidental data loss.

*History Ops — Tactical Study Command. Turn review into a mission; turn mastery into intelligence.*