{"id":32689422,"url":"https://github.com/tqer39/edu-quest","last_synced_at":"2026-05-01T21:05:49.427Z","repository":{"id":315978600,"uuid":"1052064605","full_name":"tqer39/edu-quest","owner":"tqer39","description":"Educational platform for elementary students featuring multiple learning quests (Math, Kanji, Clock) built with Hono SSR on Cloudflare Workers.","archived":false,"fork":false,"pushed_at":"2026-04-27T05:54:46.000Z","size":2392,"stargazers_count":1,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T07:22:38.159Z","etag":null,"topics":["cloudflare-workers","drizzle-orm","education","elementary-math","hono","monorepo","pnpm","ssr","terraform","wrangler"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tqer39.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":"docs/AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-07T10:29:48.000Z","updated_at":"2026-04-18T01:22:50.000Z","dependencies_parsed_at":"2025-12-01T11:02:56.754Z","dependency_job_id":null,"html_url":"https://github.com/tqer39/edu-quest","commit_stats":null,"previous_names":["tqer39/ed-games","tqer39/mathquest"],"tags_count":4,"template":false,"template_full_name":"tqer39/boilerplate-base","purl":"pkg:github/tqer39/edu-quest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqer39%2Fedu-quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqer39%2Fedu-quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqer39%2Fedu-quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqer39%2Fedu-quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tqer39","download_url":"https://codeload.github.com/tqer39/edu-quest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqer39%2Fedu-quest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32512713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":["cloudflare-workers","drizzle-orm","education","elementary-math","hono","monorepo","pnpm","ssr","terraform","wrangler"],"created_at":"2025-11-01T13:01:01.304Z","updated_at":"2026-05-01T21:05:49.419Z","avatar_url":"https://github.com/tqer39.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[🇯🇵 日本語](/docs/README.ja.md)\n\n# EduQuest Document Overview\n\n[![codecov](https://codecov.io/gh/tqer39/edu-quest/graph/badge.svg)](https://codecov.io/gh/tqer39/edu-quest)\n[![D1 Migrations (Dev)](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-dev.yml/badge.svg)](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-dev.yml)\n[![D1 Migrations (Prod)](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-prod.yml/badge.svg)](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-prod.yml)\n[![Terraform (Dev)](https://github.com/tqer39/edu-quest/actions/workflows/terraform-dev.yml/badge.svg)](https://github.com/tqer39/edu-quest/actions/workflows/terraform-dev.yml)\n[![Terraform (Prod)](https://github.com/tqer39/edu-quest/actions/workflows/terraform-prod.yml/badge.svg)](https://github.com/tqer39/edu-quest/actions/workflows/terraform-prod.yml)\n\nEduQuest is a learning platform for elementary school students that provides various educational content through specialized \"Quest\" modules. Built with Hono for SSR on Cloudflare Workers, it features a shared domain logic managed in a monorepo with pnpm workspaces.\n\n## Technology Stack\n\n### Application \u0026 Language\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://hono.dev/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://hono.dev/images/logo.png\" alt=\"Hono logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eHono\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://www.typescriptlang.org/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/typescript/typescript-original.svg\" alt=\"TypeScript logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eTypeScript\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Testing \u0026 Quality\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://vitest.dev/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://vitest.dev/logo.svg\" alt=\"Vitest logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eVitest\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://playwright.dev/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/playwright/playwright-original.svg\" alt=\"Playwright logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003ePlaywright\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://about.codecov.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://avatars.githubusercontent.com/u/8226205?s=200\u0026v=4\" alt=\"Codecov logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eCodecov\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Cloud \u0026 Infrastructure\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://www.cloudflare.com/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/cloudflare/cloudflare-original.svg\" alt=\"Cloudflare logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eCloudflare\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://aws.amazon.com/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/amazonwebservices/amazonwebservices-original-wordmark.svg\" alt=\"AWS logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eAWS\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://cloud.google.com/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/googlecloud/googlecloud-original.svg\" alt=\"Google Cloud logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eGoogle Cloud\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Developer Productivity\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://www.anthropic.com/claude/code\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://claude.ai/images/claude_app_icon.png\" alt=\"Claude Code logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://openai.com/blog/openai-codex\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/0/04/ChatGPT_logo.svg\" alt=\"OpenAI logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eOpenAI\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Infrastructure as Code (IaC) \u0026 Development Tools\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://www.terraform.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/terraform/terraform-original.svg\" alt=\"Terraform logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eTerraform\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://aquasecurity.github.io/tfsec/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://aquasecurity.github.io/tfsec/latest/imgs/logo.png\" alt=\"tfsec logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003etfsec\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://brew.sh/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://brew.sh/assets/img/homebrew.svg\" alt=\"Homebrew logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eHomebrew\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://mise.jdx.dev/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://mise.jdx.dev/logo.svg\" alt=\"mise logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003emise\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://just.systems/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/casey/just/master/icon.png\" alt=\"just logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003ejust\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png\" alt=\"GitHub logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eGitHub\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://prettier.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://prettier.io/icon.png\" alt=\"Prettier logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003ePrettier\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://pre-commit.com/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://pre-commit.com/logo.svg\" alt=\"pre-commit logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003epre-commit\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://editorconfig.org/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://editorconfig.org/logo.png\" alt=\"EditorConfig logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eEditorConfig\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://pnpm.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://pnpm.io/img/pnpm-no-name-with-frame.svg\" alt=\"pnpm logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003epnpm\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://yamllint.readthedocs.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://plugins.jetbrains.com/files/15349/503949/icon/default.svg\" alt=\"yamllint logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eyamllint\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://cspell.org/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://avatars.githubusercontent.com/u/50543896?s=200\u0026v=4\" alt=\"cspell logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003ecspell\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://textlint.github.io/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://avatars.githubusercontent.com/u/15377024?s=280\u0026v=4\" alt=\"textlint logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003etextlint\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://www.toptal.com/developers/gitignore/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://github.com/toptal/gitignore.io/raw/master/Public/img/gitignoreio.svg\" alt=\"gitignore.io logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003egitignore.io\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://biomejs.dev/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg src=\"https://biomejs.dev/_astro/logo-light-transparent.D-4iVN_O.svg\" alt=\"Biome logo\" width=\"60\" height=\"60\" /\u003e\n        \u003cbr /\u003e\u003csub\u003e\u003cb\u003eBiome\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Quest Modules\n\n- **MathQuest** (`/math`): Arithmetic practice with grade-level presets and themed exercises. Users can select calculation types, toggle settings (sound effects, intermediate steps), and practice with a keypad UI.\n- **KokugoQuest** (`/kokugo`): Japanese language learning organized by grade level (Coming Soon)\n- **GameQuest** (`/game`): Brain-training mini games for pattern recognition, spatial reasoning, and memory (includes Sudoku and the Stellar Balance tile puzzle)\n- **ClockQuest** (`/clock`): Time-reading practice with analog and digital clocks (Coming Soon)\n\nThe platform features an EduQuest hub page (`/`) where users can navigate to each Quest module. Question generation and grading are handled by `@edu-quest/domain` and are reused by the API layer (`/apis/quiz`).\n\n## Quick Start\n\n### Prerequisites\n\nThe repository uses the following tools:\n\n- **Homebrew**: Manages system-level development tools for macOS/Linux.\n- **mise**: Manages versions of the execution environment, such as Node.js, pnpm, and Wrangler.\n- **just**: A task runner for bundling setup and linting commands.\n- **pnpm**: Manages the JavaScript/TypeScript workspace.\n\n### Setup\n\n**Important**: Before running `make bootstrap`, you need to complete the following steps:\n\n#### 1. Set up Cloudflare credentials\n\n```bash\n# Add Cloudflare credentials (required before make bootstrap)\ncf-vault add edu-quest\ncf-vault list\n```\n\n#### 2. Initialize Terraform Bootstrap\n\nSet up Cloudflare resources (D1, KV, Turnstile, etc.) for the development environment:\n\n```bash\njust tf -chdir=dev/bootstrap init -reconfigure\njust tf -chdir=dev/bootstrap validate\njust tf -chdir=dev/bootstrap plan\njust tf -chdir=dev/bootstrap apply -auto-approve\n```\n\n#### 3. Proceed with the standard setup\n\n```bash\n# 1. Install Homebrew (macOS/Linux)\nmake bootstrap\n\n# 2. Set up dependent tools and npm packages together\n# This also installs Playwright browsers automatically\njust setup\n```\n\nIf you already have Homebrew, run `brew bundle install` before `just setup`.\n\n**Note:** The `just setup` command automatically installs:\n\n- mise tools (Node.js, pnpm, etc.)\n- pnpm (if not already installed)\n- All npm dependencies\n- Playwright browsers for E2E testing\n\n### Frequently Used Commands\n\n```bash\n# List all available just tasks\njust help\n\n# Run code quality checks (biome, cspell, vitest, etc.)\njust lint\n\n# Apply automatic formatting\njust fix\n\n# Clear the pre-commit cache\njust clean\n\n# Update runtimes and CLIs\njust update-brew\njust update\njust update-hooks\n\n# Check mise status\njust status\n\n# Run E2E tests with Playwright (headless)\njust e2e\n\n# Open Playwright test runner (UI mode)\njust e2e-open\n```\n\n## Testing\n\n### Unit Tests\n\nThe project uses Vitest for unit testing:\n\n```bash\n# Run all unit tests\npnpm test\n\n# Run unit tests in watch mode\npnpm test:watch\n\n# Generate coverage report\npnpm test:coverage\n```\n\n### E2E Tests\n\nThe project uses Playwright for end-to-end testing to verify screen transitions and user flows.\n\n#### Running E2E Tests\n\n##### Option 1: Manual (recommended for development)\n\n```bash\n# 1. Start the Cloudflare Workers dev server in a separate terminal\npnpm dev:edge\n# This starts the server on http://localhost:8788\n\n# 2. Run E2E tests in headless mode\njust e2e\n\n# OR open Playwright test runner (UI mode)\njust e2e-open\n```\n\n##### Option 2: Automatic (for CI or quick testing)\n\n```bash\n# Automatically start dev server and run E2E tests\njust e2e-ci\n```\n\nThis command will:\n\n1. Start the Cloudflare Workers dev server in the background\n2. Wait for the server to be ready (max 30 seconds)\n3. Run all E2E tests\n4. Automatically shut down the server when done\n\n**Important Notes:**\n\n- **E2E tests MUST run against `@edu-quest/edge` (Cloudflare Workers), NOT `@edu-quest/web`**\n- `@edu-quest/web` is a placeholder Node.js server without actual application routes\n- All application routes (/, /math, /math/start, /math/play, etc.) exist only in `@edu-quest/edge`\n- The `just e2e` and `just e2e-open` commands check if the server is running on `http://localhost:8788`\n- **Always use `pnpm dev:edge` to start the server for E2E testing**\n\n**E2E Test Coverage:**\n\n- Navigation flows between pages (Home → MathQuest → Start → Play → Results)\n- ClockQuest navigation\n- Backward navigation (browser back button)\n- Legacy URL redirects (`/start` → `/math/start`, `/play` → `/math/play`)\n\n#### CI/CD Integration\n\nE2E tests run automatically in GitHub Actions on:\n\n- Push to `main` branch\n- Pull request creation/updates\n\nThe CI workflow (`.github/workflows/e2e.yml`) performs the following:\n\n1. Installs `just` command runner\n2. Sets up mise (Node.js, pnpm, etc.)\n3. Installs pnpm dependencies\n4. Installs Playwright browsers\n5. Builds required packages (`@edu-quest/domain`, `@edu-quest/app`)\n6. Runs `just e2e-ci` (automatic server management)\n7. Uploads Playwright reports, traces, and media on failure\n\n#### Viewing Test Failure Screenshots\n\nWhen E2E tests fail in CI:\n\n1. Go to the failed workflow run in GitHub Actions\n2. Scroll to the bottom of the page\n3. Download the `playwright-report` artifact (if available)\n4. Download the `playwright-test-results` artifact for traces and media\n5. Review the HTML report, screenshots, and videos to diagnose the issue\n\nScreenshot files are organized by test file and test name:\n\n```text\nplaywright-report/\n└── index.html\n\nplaywright/test-results/\n└── navigation.spec.ts-\u003chash\u003e/\n    ├── trace.zip\n    ├── video.webm\n    └── screenshot.png\n```\n\n## Repository Structure\n\n- `apps/edge`: The Hono SSR app that runs on Cloudflare Workers. It contains the start/play screens in `routes/pages` and the question generation/grading API in `routes/apis/quiz.ts`.\n- `apps/api` / `apps/web`: A Node server and web front-end for local development. Used for validation without Workers.\n- `packages/domain`: The logic for question generation and grading. It also defines multi-step problems for different grade levels (e.g., addition then subtraction).\n- `packages/app`: Manages quiz progression (question order, correct answer count, etc.) using the domain logic.\n- `docs/`: Design and operational documents.\n- `infra/`: Terraform and D1 migrations.\n- `games/math-quiz`: The old browser-based game (static HTML/JS).\n- `games/clock-quest`: A prototype ClockQuest trainer with analog \u0026 digital clocks (static HTML/JS).\n\n## Related Documents\n\n- `AGENTS.md`: Overall design and module dependencies.\n- `docs/local-dev.md`: Procedures for setting up a local validation environment.\n- `docs/edu-quest-architecture.md`: Detailed architecture design.\n- `docs/math-quiz.md`: Specifications for the old standalone mini-game.\n- `docs/parallel-development.md`: Guide for parallel feature development using git worktree.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftqer39%2Fedu-quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftqer39%2Fedu-quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftqer39%2Fedu-quest/lists"}