chocomae/CLAUDE.md

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/):

cd src/util/phaser-input-master
npm install    # install grunt + TypeScript deps
grunt          # build TypeScript → JS

Database setup (initialize schema):

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.