From a57fc288253c4f17905f1d73cfc7eec90805dd6d Mon Sep 17 00:00:00 2001
From: jisangs <jisangs@gmail.com>
Date: Tue, 17 Mar 2026 16:38:14 +0900
Subject: [PATCH] =?UTF-8?q?=ED=81=B4=EB=A1=9C=EB=93=9C=20=EC=BD=94?=
 =?UTF-8?q?=EB=93=9C=20=EC=B4=88=EA=B8=B0=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5029e26
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,97 @@
+# 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.