{"id":50444341,"url":"https://github.com/garnertb/geo-quest","last_synced_at":"2026-05-31T20:32:11.355Z","repository":{"id":361184758,"uuid":"1253444787","full_name":"garnertb/geo-quest","owner":"garnertb","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-29T14:33:26.000Z","size":2926,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T15:11:19.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://geo-quest-flax.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/garnertb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-29T13:19:55.000Z","updated_at":"2026-05-29T14:33:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/garnertb/geo-quest","commit_stats":null,"previous_names":["garnertb/geo-quest"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/garnertb/geo-quest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garnertb%2Fgeo-quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garnertb%2Fgeo-quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garnertb%2Fgeo-quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garnertb%2Fgeo-quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/garnertb","download_url":"https://codeload.github.com/garnertb/geo-quest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garnertb%2Fgeo-quest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33748607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T20:32:09.127Z","updated_at":"2026-05-31T20:32:11.344Z","avatar_url":"https://github.com/garnertb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geo Quest\n\nA fast, visual geography learning game for kids ages 7–16.\n\nBuilt with **Next.js 16 (App Router, static export)**, **React 19**, **TypeScript**, **Tailwind v4**, **Zustand**, **Framer Motion**, and **Tauri 2**.\n\n## Run\n\n### Web\n```bash\nnpm install\nnpm run dev          # http://localhost:3000\nnpm run build        # produces ./out (static export)\nnpm run lint\n```\n\n### Desktop (Tauri 2)\n```bash\nnpm run tauri:dev    # launches native window pointed at the Next dev server\nnpm run tauri:build  # produces a native installer (macOS/Windows/Linux)\n```\nRequires Rust toolchain (`cargo`). The web build always works without it.\n\n## Architecture\n\n```\nsrc/\n  app/                Next.js App Router pages (/, /topics, /play, /summary, /mastery)\n  components/\n    ui/               Buttons, cards, progress (shadcn-style primitives)\n    maps/             USTileMap, ContinentMap (SVG)\n  content/seed.ts     Static content packs: continents, US states, US capitals\n  engine/\n    learning/sr.ts    SM-2-lite spaced-repetition + mastery tracking (pure)\n    session/builder.ts Question generation, session planner, scoring\n  store/game.ts       Zustand store + localStorage persistence\n  types/domain.ts     Shared TS types (ContentPack, GeoItem, Question, …)\n  lib/                Utilities (cn, shuffle, useHydrated)\nsrc-tauri/            Rust Tauri 2 shell\n```\n\n### Learning engine\n- Each `(item, questionType)` pair has its own `LearningState`: mastery 0–1, ease factor, current streak, next-review timestamp, recent attempts.\n- `applyAnswer` updates state using an SM-2-lite rule: correct answers extend the interval by `ease`, wrong answers reset the interval and resurface the item within minutes.\n- `bucketStates` partitions items into **due / weak / new / strong** for session planning.\n- Sessions pull **60% due, 25% weak, 15% new**, falling back to fill if a bucket is short.\n\n### Content packs\n- A `ContentPack` declares `topic`, `items`, and `supportedQuestionTypes`.\n- Items reference visual assets by id (`shape`, `tile`). The map components own the actual rendering, so packs can be added later without touching the learning engine.\n- The MVP uses a stylized US tile-map and simplified continent silhouettes. Swap in GeoJSON-backed components later by replacing `USTileMap` / `ContinentMap`.\n\n### Persistence\n- `localStorage` via `zustand/middleware/persist`. Works in both the web app and Tauri webview.\n- Single local profile in MVP; the store is shaped to allow multiple profiles later.\n\n### Game loop\n1. **Home** — first-time players start with **Start your quest** (map pick + 5-question focused quest), then transition to **Today’s Quest** and dynamic recommendations.\n2. **Daily Quest** (`/play`) — 10 mixed-topic questions with a non-required speed bonus, combo multiplier, animated correct/wrong feedback, and a teaching map for misses.\n3. **Summary** — stars (based on accuracy), XP, best combo, improved items, items to review.\n4. **Topic picker** — jump directly into continents / states / capitals.\n5. **Mastery map** — visual progress: mastered states light up green, weak ones tint red.\n\n## MVP scope\n✅ Home · Topics · Play (10-question Daily Quest) · Summary · Mastery\n✅ Speed bonus, combo, XP, streak, daily goal, star rating\n✅ Correct/wrong animations and teaching feedback on misses\n✅ Reusable learning engine (SR + mastery)\n✅ Content-pack data model with seed content\n✅ Local-first persistence\n✅ Tauri 2 desktop wrapper\n🚫 Achievements (intentionally out of scope)\n\n## Design decisions\n- **Tile-map for US states.** Instantly recognizable, scales perfectly, and lets us highlight any state precisely. Real GeoJSON outlines can be dropped into the `USTileMap` component later.\n- **No mascot.** Polish carries the game feel: large cards, smooth transitions, satisfying button physics, animated stars.\n- **Speed bonus, not speed gate.** Younger players are never punished by the timer.\n- **Distractor groups by region.** Wrong-answer choices tend to be regional neighbors, making questions challenging without random difficulty.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarnertb%2Fgeo-quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgarnertb%2Fgeo-quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarnertb%2Fgeo-quest/lists"}