🇯🇵 日本語

EduQuest Document Overview

EduQuest 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.

Technology Stack

Application & Language

Hono	TypeScript

Testing & Quality

Vitest

Playwright

Codecov

Cloud & Infrastructure

Cloudflare

AWS

Google Cloud

Developer Productivity

Claude Code

OpenAI

Infrastructure as Code (IaC) & Development Tools

Terraform	tfsec	Homebrew	mise
just	GitHub	Prettier	pre-commit
EditorConfig	pnpm	yamllint
cspell	textlint	gitignore.io	Biome

Quest Modules

• 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.
• KokugoQuest (/kokugo): Japanese language learning organized by grade level (Coming Soon)
• GameQuest (/game): Brain-training mini games for pattern recognition, spatial reasoning, and memory (includes Sudoku and the Stellar Balance tile puzzle)
• ClockQuest (/clock): Time-reading practice with analog and digital clocks (Coming Soon)

The 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).

Quick Start

Prerequisites

The repository uses the following tools:

• Homebrew: Manages system-level development tools for macOS/Linux.
• mise: Manages versions of the execution environment, such as Node.js, pnpm, and Wrangler.
• just: A task runner for bundling setup and linting commands.
• pnpm: Manages the JavaScript/TypeScript workspace.

Setup

Important: Before running make bootstrap, you need to complete the following steps:

1. Set up Cloudflare credentials

# Add Cloudflare credentials (required before make bootstrap)
cf-vault add edu-quest
cf-vault list

2. Initialize Terraform Bootstrap

Set up Cloudflare resources (D1, KV, Turnstile, etc.) for the development environment:

just tf -chdir=dev/bootstrap init -reconfigure
just tf -chdir=dev/bootstrap validate
just tf -chdir=dev/bootstrap plan
just tf -chdir=dev/bootstrap apply -auto-approve

3. Proceed with the standard setup

# 1. Install Homebrew (macOS/Linux)
make bootstrap

# 2. Set up dependent tools and npm packages together
# This also installs Playwright browsers automatically
just setup

If you already have Homebrew, run brew bundle install before just setup.

Note: The just setup command automatically installs:

• mise tools (Node.js, pnpm, etc.)
• pnpm (if not already installed)
• All npm dependencies
• Playwright browsers for E2E testing

Frequently Used Commands

# List all available just tasks
just help

# Run code quality checks (biome, cspell, vitest, etc.)
just lint

# Apply automatic formatting
just fix

# Clear the pre-commit cache
just clean

# Update runtimes and CLIs
just update-brew
just update
just update-hooks

# Check mise status
just status

# Run E2E tests with Playwright (headless)
just e2e

# Open Playwright test runner (UI mode)
just e2e-open

Testing

Unit Tests

The project uses Vitest for unit testing:

# Run all unit tests
pnpm test

# Run unit tests in watch mode
pnpm test:watch

# Generate coverage report
pnpm test:coverage

E2E Tests

The project uses Playwright for end-to-end testing to verify screen transitions and user flows.

Running E2E Tests

Option 1: Manual (recommended for development)

# 1. Start the Cloudflare Workers dev server in a separate terminal
pnpm dev:edge
# This starts the server on http://localhost:8788

# 2. Run E2E tests in headless mode
just e2e

# OR open Playwright test runner (UI mode)
just e2e-open

Option 2: Automatic (for CI or quick testing)

# Automatically start dev server and run E2E tests
just e2e-ci

This command will:

1. Start the Cloudflare Workers dev server in the background
2. Wait for the server to be ready (max 30 seconds)
3. Run all E2E tests
4. Automatically shut down the server when done

Important Notes:

• E2E tests MUST run against @edu-quest/edge (Cloudflare Workers), NOT @edu-quest/web
• @edu-quest/web is a placeholder Node.js server without actual application routes
• All application routes (/, /math, /math/start, /math/play, etc.) exist only in @edu-quest/edge
• The just e2e and just e2e-open commands check if the server is running on http://localhost:8788
• Always use pnpm dev:edge to start the server for E2E testing

E2E Test Coverage:

• Navigation flows between pages (Home → MathQuest → Start → Play → Results)
• ClockQuest navigation
• Backward navigation (browser back button)
• Legacy URL redirects (/start → /math/start, /play → /math/play)

CI/CD Integration

E2E tests run automatically in GitHub Actions on:

• Push to main branch
• Pull request creation/updates

The CI workflow (.github/workflows/e2e.yml) performs the following:

1. Installs just command runner
2. Sets up mise (Node.js, pnpm, etc.)
3. Installs pnpm dependencies
4. Installs Playwright browsers
5. Builds required packages (@edu-quest/domain, @edu-quest/app)
6. Runs just e2e-ci (automatic server management)
7. Uploads Playwright reports, traces, and media on failure

Viewing Test Failure Screenshots

When E2E tests fail in CI:

1. Go to the failed workflow run in GitHub Actions
2. Scroll to the bottom of the page
3. Download the playwright-report artifact (if available)
4. Download the playwright-test-results artifact for traces and media
5. Review the HTML report, screenshots, and videos to diagnose the issue

Screenshot files are organized by test file and test name:

playwright-report/
└── index.html

playwright/test-results/
└── navigation.spec.ts-<hash>/
    ├── trace.zip
    ├── video.webm
    └── screenshot.png

Repository Structure

• 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.
• apps/api / apps/web: A Node server and web front-end for local development. Used for validation without Workers.
• packages/domain: The logic for question generation and grading. It also defines multi-step problems for different grade levels (e.g., addition then subtraction).
• packages/app: Manages quiz progression (question order, correct answer count, etc.) using the domain logic.
• docs/: Design and operational documents.
• infra/: Terraform and D1 migrations.
• games/math-quiz: The old browser-based game (static HTML/JS).
• games/clock-quest: A prototype ClockQuest trainer with analog & digital clocks (static HTML/JS).

Related Documents

• AGENTS.md: Overall design and module dependencies.
• docs/local-dev.md: Procedures for setting up a local validation environment.
• docs/edu-quest-architecture.md: Detailed architecture design.
• docs/math-quiz.md: Specifications for the old standalone mini-game.
• docs/parallel-development.md: Guide for parallel feature development using git worktree.