Backend for Penn Mobile Games Word Hunt

* Backend for Penn Mobile Games Word Hunt.

* Tests for Penn Mobile Games backend.

* Fixes for flake8

* Format code with Black

* Fixes

* Address PR review comments

* Rename test_games.py to demo_games.py to prevent CI test runner from picking it up

* Use any() with generator for invalid word check

Author: bliu8

backend/demo_games.py

@@ -0,0 +1,98 @@
+import json
+import os
+
+import django
+
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "pennmobile.settings")
+django.setup()
+
+from django.contrib.auth import get_user_model  # noqa: E402
+from rest_framework.test import APIClient  # noqa: E402
+
+from games.generator import generate_good_game  # noqa: E402
+from games.models import Game, LeaderboardEntry  # noqa: E402
+
+
+User = get_user_model()
+client = APIClient()
+
+print("\n" + "=" * 50)
+
+# TASK 1 ----------------------------------------------------------------------
+print("--- Testing Task 1: Generate Games & Store in DB ---")
+try:
+    game_board, seed, sols = generate_good_game(
+        min_total_words=50
+    )  # Using a smaller number so it tests quickly
+    print("✅ Game generation script successful! Seed word generated:", seed)
+
+    game = Game.get_today()
+    if game:
+        print(f"✅ Django DB Game model successfully loaded for {game.date}.")
+        print("   Board format:", type(game.board), "->", game.board[0], "...")
+    else:
+        print("❌ No game for today found. Ensure you ran 'python manage.py generate_game'")
+except Exception as e:
+    print("❌ Generation/Model script failed:", str(e))
+
+
+# TASK 2 ----------------------------------------------------------------------
+print("\n--- Testing Task 2: Models for storing game results (User+Day) ---")
+user, _ = User.objects.get_or_create(username="testuser")
+dummy_user, _ = User.objects.get_or_create(username="dummyuser2")
+
+try:
+    entry, created = LeaderboardEntry.objects.get_or_create(
+        game=game, user=dummy_user, defaults={"score": 100, "num_words_found": 5}
+    )
+    print(
+        f"✅ LeaderboardEntry model works for {dummy_user.username}. "
+        f"Associated with Game {game.date}."
+    )
+    print(f"✅ Relational lookup successful: game.scores.count() = {game.scores.count()}")
+
+except Exception as e:
+    print("❌ Leaderboard model creation failed:", str(e))
+
+
+client.force_authenticate(user=user)
+
+# TASK 3 ----------------------------------------------------------------------
+print("\n--- Testing Task 3: Fetch Game Route ---")
+response = client.get("/games/word-hunt/today/", format="json")
+print(f"✅ Route Status Code: {response.status_code}")
+print("✅ JSON Data Payload Extract:")
+print(json.dumps(response.data, indent=2)[:200] + "...\n")
+
+
+# TASK 4 ----------------------------------------------------------------------
+print("--- Testing Task 4: Submit Score Route (valid words) ---")
+valid_words = game.possible_words[:3] if game and game.possible_words else []
+data = {"words": valid_words}
+response = client.post(f"/games/word-hunt/{game.date}/submit/", data, format="json")
+print(f"✅ Route Status Code: {response.status_code}")
+print("✅ Submit Route Response:")
+print(json.dumps(response.data, indent=2) + "\n")
+
+
+# TASK 5 ----------------------------------------------------------------------
+print("--- Testing Task 5: Submit Score Route (invalid words) ---")
+data = {"words": [valid_words[0] if valid_words else "cat", "notarealword123"]}
+response2_user, _ = User.objects.get_or_create(username="testuser2")
+client2 = APIClient()
+client2.force_authenticate(user=response2_user)
+response = client2.post(f"/games/word-hunt/{game.date}/submit/", data, format="json")
+print(f"✅ Route Status Code: {response.status_code}")
+print("✅ Validation Error Response:")
+print(json.dumps(response.data, indent=2) + "\n")
+
+
+# TASK 6 ----------------------------------------------------------------------
+print("--- Testing Task 6: Leaderboard Route ---")
+response = client.get(f"/games/word-hunt/{game.date}/leaderboard/", format="json")
+print(f"✅ Route Status Code: {response.status_code}")
+print("✅ Leaderboard JSON Output (Ranked):")
+print(json.dumps(response.data, indent=2))
+
+print("=" * 50 + "\n")

backend/games/admin.py

@@ -0,0 +1,7 @@
+from django.contrib import admin
+
+from games.models import Game, LeaderboardEntry
+
+
+admin.site.register(Game)
+admin.site.register(LeaderboardEntry)

backend/games/generator.py

@@ -0,0 +1,103 @@
+import random
+import zipfile
+from pathlib import Path
+
+
+BASE_DIR = Path(__file__).resolve().parent
+zip_file_path = BASE_DIR / "words.txt.zip"
+extract_directory = BASE_DIR
+
+if not zip_file_path.exists():
+    raise FileNotFoundError(f"words.txt.zip not found at {zip_file_path}")
+
+MAX_LEN = 8
+MIN_TOTAL_WORDS = 175
+
+WORD_SET = set()
+PREFIX_SET = set()
+SIX_LETTER_WORDS = []
+
+with zipfile.ZipFile(zip_file_path, "r") as zip_ref:
+    try:
+        with zip_ref.open("words.txt") as file:
+            for line in file:
+                if line.strip():
+                    w = line.decode("utf-8").strip().lower()
+                    if not w.isalpha():
+                        continue
+                    if len(w) == 6:
+                        SIX_LETTER_WORDS.append(w)
+                    if len(w) <= MAX_LEN:
+                        WORD_SET.add(w)
+                        for i in range(1, len(w) + 1):
+                            PREFIX_SET.add(w[:i])
+    except KeyError as ex:
+        raise FileNotFoundError(f"words.txt is not in {zip_file_path}") from ex
+
+
+def neighbors(n, x, y):
+    for dx in (-1, 0, 1):
+        for dy in (-1, 0, 1):
+            if dx == 0 and dy == 0:
+                continue
+            xx, yy = x + dx, y + dy
+            if 0 <= xx <= n and 0 <= yy <= n:
+                yield xx, yy
+
+
+def generate_game():
+    letters = list("abcdefghijklmnopqrstuvwxyz")
+    game = [[""] * 5 for _ in range(5)]
+    n = 4
+
+    seed_word = random.choice(SIX_LETTER_WORDS)
+    curr_x, curr_y = random.randint(0, n), random.randint(0, n)
+
+    for c in seed_word:
+        game[curr_y][curr_x] = c
+        options = [(xx, yy) for (xx, yy) in neighbors(n, curr_x, curr_y) if game[yy][xx] == ""]
+        if not options:
+            return generate_game()
+        curr_x, curr_y = random.choice(options)
+
+    for y in range(5):
+        for x in range(5):
+            if game[y][x] == "":
+                game[y][x] = random.choice(letters)
+
+    return game, seed_word
+
+
+def solve_game(game, min_len=3, max_len=MAX_LEN):
+    n = len(game)
+    dirs = [(-1, -1), (-1, 0), (-1, 1), (0, -1), (0, 1), (1, -1), (1, 0), (1, 1)]
+
+    found = set()
+
+    for r in range(n):
+        for c in range(n):
+            stack = [(r, c, "", frozenset())]
+            while stack:
+                cr, cc, s, vis = stack.pop()
+                s = s + game[cr][cc]
+                if s not in PREFIX_SET:
+                    continue
+                if len(s) >= min_len and s in WORD_SET:
+                    found.add(s)
+                if len(s) == max_len:
+                    continue
+                vis = vis | {(cr, cc)}
+                for dr, dc in dirs:
+                    rr, nc = cr + dr, cc + dc
+                    if 0 <= rr < n and 0 <= nc < n and (rr, nc) not in vis:
+                        stack.append((rr, nc, s, vis))
+
+    return sorted(found, key=lambda w: (-len(w), w))
+
+
+def generate_good_game(min_total_words=MIN_TOTAL_WORDS):
+    while True:
+        game, seed = generate_game()
+        sols = solve_game(game)
+        if len(sols) >= min_total_words:
+            return game, seed, sols

backend/games/management/commands/generate_game.py

@@ -0,0 +1,30 @@
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+
+from games.generator import generate_good_game
+from games.models import Game
+
+
+class Command(BaseCommand):
+    help = "Generate and save 100 future Word Hunt games"
+
+    def handle(self, *args, **kwargs):
+        for i in range(100):
+            future_date = timezone.localdate() + timezone.timedelta(days=i)
+            game, seed, sols = generate_good_game()
+
+            word_freqs = {3: 0, 4: 0, 5: 0, 6: 0, 7: 0, 8: 0}
+            for w in sols:
+                word_freqs[len(w)] += 1
+
+            Game.objects.update_or_create(
+                date=future_date,
+                defaults={
+                    "board": game,
+                    "possible_words": sols,
+                    "seed": seed,
+                    "word_length_freq": word_freqs,
+                },
+            )
+
+            self.stdout.write(f"Game for {future_date} generated successfully")

backend/games/migrations/0001_initial.py

@@ -0,0 +1,65 @@
+# Generated by Django 5.0.2 on 2026-02-27 23:06
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Game",
+            fields=[
+                ("date", models.DateField(primary_key=True, serialize=False)),
+                ("board", models.JSONField()),
+                ("possible_words", models.JSONField()),
+                ("seed", models.CharField(max_length=32)),
+            ],
+        ),
+        migrations.CreateModel(
+            name="LeaderboardEntry",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                ("score", models.PositiveIntegerField(db_index=True)),
+                ("words_found", models.PositiveIntegerField()),
+                ("submitted_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "game",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="scores",
+                        to="games.game",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="word_hunt_scores",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-score", "words_found", "submitted_at"],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="leaderboardentry",
+            constraint=models.UniqueConstraint(
+                fields=("game", "user"), name="unique_entry_per_user_per_game"
+            ),
+        ),
+    ]

backend/games/migrations/0002_game_freqs.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.0.2 on 2026-03-01 18:41
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("games", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="game",
+            name="freqs",
+            field=models.JSONField(default=dict),
+        ),
+    ]

backend/games/migrations/0003_alter_leaderboardentry_options_and_more.py

@@ -0,0 +1,27 @@
+# Generated by Django 5.0.2 on 2026-03-30 02:51
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("games", "0002_game_freqs"),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name="leaderboardentry",
+            options={"ordering": ["-score"]},
+        ),
+        migrations.RenameField(
+            model_name="game",
+            old_name="freqs",
+            new_name="word_length_freq",
+        ),
+        migrations.RenameField(
+            model_name="leaderboardentry",
+            old_name="words_found",
+            new_name="num_words_found",
+        ),
+    ]

backend/games/migrations/__init__.py

@@ -0,0 +1,37 @@
+from django.contrib.auth import get_user_model
+from django.db import models
+from django.utils import timezone
+
+
+User = get_user_model()
+
+
+class Game(models.Model):
+    date = models.DateField(primary_key=True)
+    board = models.JSONField()
+    possible_words = models.JSONField()
+    seed = models.CharField(max_length=32)
+    word_length_freq = models.JSONField(default=dict)
+
+    def __str__(self):
+        return str(self.date)
+
+    @classmethod
+    def get_today(cls):
+        return cls.objects.filter(date=timezone.localdate()).first()
+
+
+class LeaderboardEntry(models.Model):
+    game = models.ForeignKey(Game, on_delete=models.CASCADE, related_name="scores")
+    user = models.ForeignKey(User, on_delete=models.CASCADE, related_name="word_hunt_scores")
+
+    score = models.PositiveIntegerField(db_index=True)
+    num_words_found = models.PositiveIntegerField()
+
+    submitted_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(fields=["game", "user"], name="unique_entry_per_user_per_game")
+        ]
+        ordering = ["-score"]