Code Quest

code_quest is a play-first coding curriculum for kids with short story missions, creative Python builds, tap-based command games, and a homeschool-friendly weekly rhythm.

What it does

• Creates a grade-aware learner profile for each child with interests, experience, and accessibility preferences.
• Protects each family with a parent account and isolated private household.
• Lets another parent redeem an expiring crew pass for a nickname-only friend profile.
• Starts every learner with the same Python Core Quest fundamentals.
• Then branches into age-appropriate creator tracks:
  • Spark Track (ages 6-7)
  • Explorer Track (ages 8-11)
  • Game Creator Track (ages 12-14)
  • Architect Track (ages 15+)
• Includes modules with:
  • concept lesson cards
  • quick-choice checkpoints
  • creative build missions with friendly goal checks
  • sequential lesson/module locking and unlock progression
• Includes gamification:
  • XP, levels, coins, streaks
  • earned achievement badges
  • a no-real-money coin shop for learner-selected studio themes
  • interactive Code Runner side-quest mission game
• Includes a tap-first Sprite Studio with animated feedback, generated Python, private autosave, remixing, and version history.
• Includes homeschool planning:
  • auto-generated weekday curriculum with short guided, unplugged, creative, and game-day activities
  • manual task creation with reminder times
  • planner completion rewards
  • specific lesson assignments with due dates and required/optional priority
  • parent feedback, concept mastery, and downloadable CSV records
• Includes parent analytics:
  • weekly family dashboard
  • crew celebrations and daily activity pulse
  • child-by-child report cards and upcoming reminders
• Includes one-click demo simulation:
  • generate realistic weekly activity for quick evaluation
• Tracks per-child progress (XP, completed lessons, passed challenges).
• Allows editing learner profile data and per-child reduced-motion, contrast, text-size, easy-read, and read-aloud settings.
• Runs code safely in a restricted Python sandbox.
• Saves learner builds privately and requires parent approval before they appear in the crew gallery.
• Includes an installable PWA shell with offline static assets; private API data is never cached.
• Supports separate owner, parent, and co-teacher logins plus household timezone and learning-day settings.

See docs/ux-audit.md for the full screenshot audit, research synthesis, implemented design decisions, and platform recommendation.

See docs/security-and-sharing.md for household isolation, friend-pass behavior, project privacy, PWA caching, and production deployment notes.

Run locally

Fastest: run with uv

From the repository root:

uv python pin 3.14
uv venv --python 3.14
uv sync
uv run python main.py

Note: if your python command points to Python 2.x, always use uv run python ... for this project.

Then open:

• http://127.0.0.1:8015

Optional flags:

uv run python main.py --host 0.0.0.0 --port 8015 --db-file data/code_quest.db

Stop it with Ctrl+C. The SQLite database remains in data/code_quest.db.

Household server: run with Docker

Docker is optional, but it is the better choice for an always-on family computer, NAS, or home server because the Python runtime and restart policy are self-contained.

docker compose up --build -d
docker compose ps

Open http://localhost:8015. Follow logs or stop the app with:

docker compose logs -f code-quest
docker compose down

Learner data lives in the named volume code-quest-data, so docker compose down does not erase it. Back it up with:

docker run --rm -v code_quest_code-quest-data:/data -v "$PWD:/backup" alpine \
  tar czf /backup/code-quest-backup.tgz -C /data .

Do not use docker compose down -v unless you intentionally want to delete the database.

Which packaging should you choose?

• Use the uv command while developing or trying Code Quest on one computer.
• Use Docker Compose for a shared, always-on home installation.
• Install the PWA from the browser on each kid's device for an app-like launcher.
• Do not use Electron yet. It would duplicate the desktop runtime while excluding iPads and making Chromebook/friend access harder; consider it only if a future version needs bundled native hardware or a fully offline Python runtime.

Demo quick start

1. Create the first private parent crew.
2. Create kids (or click Create demo crew).
3. Open Parent Dashboard tab.
4. Click Preview a completed week to generate realistic report data instantly.
5. Assign a lesson, leave mastery feedback, or export homeschool records.
6. Open Crew Settings to set kid mode, invite a friend, add a co-teacher, or review saved builds.
7. Switch back to Learner Studio to use Sprite Studio, the arcade, rewards, and planner tasks.

Data storage

Progress is persisted in SQLite:

• data/code_quest.db

Docker stores the same database at /data/code_quest.db inside the named volume.

Verify changes

uv run pytest -q
node --check src/code_quest/ui/static/app.js

Engineering structure

• src/code_quest/domain: curriculum, models, and challenge evaluator.
• src/code_quest/application: learning orchestration services.
• src/code_quest/infrastructure: SQLite persistence and HTTP server.
• src/code_quest/ui/static: front-end assets.