ReadMe

About the Project

This is a fork of the WebKenKen project by msakuta. Special thanks to Sid Challa for helping set up the Google Cloud application.

Classical KenKen started as a digital version of a daily Do Now activity done on paper. Our team was manually creating puzzles, converting them to PDFs, printing, cutting, and grading 100+ KenKen puzzles a day. Over the course of a year we graded over 6,000 individual puzzles. After reviewing the data, we decided to build this online version to handle scoring automatically and serve puzzles based on each student's current level.

Project Objectives

• Students log in with their school accounts for verification and tracking
• A score is earned upon completing a puzzle that measures guesses, time, and difficulty
• Student scores are stored in a server-side database identified by student email
• Puzzles are served based on student ability (rank)
• Scores determine a grade relative to puzzle difficulty

Research & Results

The following compares overall 9th grade PSAT growth against students in the course that used KenKen puzzles (ECS):

The same data separated by average daily KenKen puzzle grade:

This data informed our student learning objectives for the 22–23 school year.

How It Works

1. Student signs in using their school-issued Google account via Google Identity Services (OAuth 2.0)
2. The server validates the Google access token using the Google OAuth2 tokeninfo API, then issues a persistent session token
3. The session token is stored in the browser's localStorage so the student stays signed in across page loads and return visits
4. A puzzle is generated with difficulty determined by the student's current rank
5. Upon completion, the score is stored in the server-side database with a timestamp and the student's email
6. Teachers access the Teacher portal to view all stored student scores, filterable and sortable by name or ID

Determining Difficulty

Difficulty is controlled by two variables: grid size and hint count. The grid size is floor(rank) + 2, maxing out at 9×9. Rank is a floating-point number — the integer part sets the grid size, and the fractional part (sub-rank) controls how many cells are pre-filled as hints. Hints decrease as sub-rank rises, so students are gradually challenged to solve more of the puzzle on their own before advancing to the next grid size. The rank is derived from the student's cumulative average score.

Scoring

Unsolved is the number of cells the student had to figure out themselves (total cells minus hint cells). Time is seconds elapsed. The grid size multiplier captures the inherent difficulty of larger puzzles — more number choices per cell and more complex arithmetic — independent of how many cells were pre-filled. Time is weighted 2.5× relative to guess accuracy.

Typical Scores by Rank

Calculating a Grade

Teachers configure three variables: Max Score, Completion Score (%), and No-Submission Score (%). A student's daily qualifying submissions are counted against the required number per day over the assignment period. Grade = count / required × Max Score, floored at the Completion Score if the requirement is met, or at the No-Submission Score if nothing was submitted. A KenKen submission only counts if the score meets or exceeds the student's all-time average.

Rank Structure

Rank is a floating-point number. The integer part determines the grid size; the fractional part (sub-rank) controls hints. A student advances to the next integer rank when their cumulative average score crosses the threshold below.

Rank Level Thresholds

Sub-Rank Hint Breakdown

Within each rank, hints are assigned based on how far through the rank the student is (sub-rank = fractional part of rank). Fewer hints = more cells to solve independently.