https://github.com/tqer39/edu-quest
Educational platform for elementary students featuring multiple learning quests (Math, Kanji, Clock) built with Hono SSR on Cloudflare Workers.
https://github.com/tqer39/edu-quest
cloudflare-workers drizzle-orm education elementary-math hono monorepo pnpm ssr terraform wrangler
Last synced: about 1 month ago
JSON representation
Educational platform for elementary students featuring multiple learning quests (Math, Kanji, Clock) built with Hono SSR on Cloudflare Workers.
- Host: GitHub
- URL: https://github.com/tqer39/edu-quest
- Owner: tqer39
- License: mit
- Created: 2025-09-07T10:29:48.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T05:54:46.000Z (about 2 months ago)
- Last Synced: 2026-04-27T07:22:38.159Z (about 2 months ago)
- Topics: cloudflare-workers, drizzle-orm, education, elementary-math, hono, monorepo, pnpm, ssr, terraform, wrangler
- Language: TypeScript
- Homepage:
- Size: 2.28 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: docs/AGENTS.md
Awesome Lists containing this project
README
[🇯🇵 日本語](/docs/README.ja.md)
# EduQuest Document Overview
[](https://codecov.io/gh/tqer39/edu-quest)
[](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-dev.yml)
[](https://github.com/tqer39/edu-quest/actions/workflows/d1-migrations-prod.yml)
[](https://github.com/tqer39/edu-quest/actions/workflows/terraform-dev.yml)
[](https://github.com/tqer39/edu-quest/actions/workflows/terraform-prod.yml)
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
### Testing & Quality
### Cloud & Infrastructure
### Developer Productivity
### 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
```bash
# 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:
```bash
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
```bash
# 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
```bash
# 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:
```bash
# 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)
```bash
# 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)
```bash
# 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:
```text
playwright-report/
└── index.html
playwright/test-results/
└── navigation.spec.ts-/
├── 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.
