# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ChocoMae (초코마에) is a Korean/English typing and mouse practice web application. It features gamified typing exercises (using Phaser 2.6.2), classroom management for teachers (Maestros), and a ranking/record system.

## Tech Stack

- **Frontend:** HTML5, JavaScript (ES5), jQuery 3.3.1, Phaser 2.6.2 game engine, Bootstrap
- **Backend:** PHP 7.x with MySQLi, Python (batch scripts)
- **Database:** MariaDB/MySQL (`chocomae` database)
- **Server:** Apache HTTP Server with SSL on AWS EC2 (Docker container)

## Development Commands

This project has **no Node.js/npm build step** for the main application. It runs directly on Apache + PHP.

**Phaser input plugin** (only if modifying `/src/util/phaser-input-master/`):
```sh
cd src/util/phaser-input-master
npm install    # install grunt + TypeScript deps
grunt          # build TypeScript → JS
```

**Database setup** (initialize schema):
```sh
mysql -u <user> -p chocomae < src/web/sql/make_db.sql
mysql -u <user> -p chocomae < src/web/sql/make_db_license_timer.sql
mysql -u <user> -p chocomae < src/web/sql/insert_app.sql
mysql -u <user> -p chocomae < src/web/sql/insert_active_app.sql
```

**Deployment** — push to `release` branch; the git post-receive hook automatically:
1. Checks out files to `/volume1/docker/chocomae/html/mouse_typing/`
2. Copies `NA_service_db_setting.php` → `service_db_setting.php` and replaces `localhost` with `mysql` (Docker hostname)

## Architecture

### Directory Structure

```
src/
├── game/          # Phaser game modules (client-side JS)
├── web/
│   ├── main/      # Entry point (index.html) + top-level HTML pages
│   ├── module/    # HTML fragments loaded dynamically via jQuery .load()
│   ├── js/        # Frontend JavaScript
│   ├── css/       # Stylesheets
│   ├── server/    # PHP backend endpoints
│   ├── admin/     # Admin panel HTML
│   ├── popup/     # Popup/modal HTML
│   └── sql/       # Database schema and seed files
├── php-cli/       # PHP batch scripts (run via cron)
└── util/          # Third-party utilities (phaser-input plugin source)
resources/         # Static assets: Bootstrap, jQuery, fonts, images
test/              # Manual test HTML/JS files (no automated test runner)
```

### Frontend Architecture

- **Entry point:** `src/web/main/index.html` — loads header/section/footer modules dynamically
- **Module loading:** jQuery `.load()` fetches HTML fragments from `src/web/module/`
- **State:** `sessionStorage` used for `maestroID` and game session data
- **Game engine:** All interactive games live in `src/game/` and use Phaser 2.6.2; each game directory has its own `main.js` with Phaser states (Boot, Load, Game, Result)

### Backend Architecture

PHP endpoints in `src/web/server/` are organized by domain:
- `player/` — CRUD for player accounts
- `record/` — Save/retrieve game results and rankings
- `maestro/` — Teacher classroom management (17 endpoints)
- `admin/` — Admin operations (11 endpoints)
- `license_timer/` — Subscription/license management
- `mail/` — Email sending via PHPMailer + Gmail SMTP
- `lib/` — Shared PHP libraries (`send_reply_json.php`, `db_maestro.php`, etc.)
- `setup/connect_db.php` — Database connection; reads from `service_db_setting.php`

All endpoints return JSON. UTF-8 encoding is set on all responses.

### Database Configuration

- **Development:** Edit `src/web/server/setup/NA_service_db_setting.php` (this is the template; `service_db_setting.php` is git-ignored and generated at deploy time)
- The deploy hook replaces `localhost` → `mysql` for Docker networking

### User Roles

| Role | Description |
|------|-------------|
| Player | End users (free or paid) who play games |
| Maestro | Teachers who manage groups of student players |
| Admin | System administrators with full access |

### Python Batch Scripts

Located in `src/web/server/python/chocomae/` and `src/php-cli/batch/` — handle scheduled tasks like sending expiration warning emails to unpaid/expiring Maestros. These are run via cron on the server.