# CLAUDE.md

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

## Project Overview

**COMPAS** is a computer skill certificate examination brand based in Thailand, targeting Thai users. The site provides information about COMPAS exams and will eventually handle registration and result reporting. Current focus is on presenting basic exam information.

Current exams: **COMPAS-A1**, **COMPAS-PY1** (more will be added over time).

### Technical Stack

This is a Drupal 11 site built from `drupal/recommended-project`. It uses DDEV for local development with MariaDB 10.11 and PHP 8.3. The DDEV project name is `isl2-dev-site` with additional hostnames: `isl2`, `compas`, `www`.
It is a multi-site Drupal installation. The site we are working on is the "compas" site, reachable at https://compas.ddev.site:8443 for local development. The primary audience is Thai, so content and UI should be appropriate for Thai readers.

## Version Control

This project uses **Mercurial (hg)**, not Git.

```bash
hg status                             # Show changed files
hg diff                               # Show uncommitted changes
hg commit -m "message"                # Commit
hg log -l 5                           # Recent commits
hg push                               # Push to remote
```

## Common Commands

All commands run inside the DDEV container unless noted otherwise.

```bash
# Start/stop the environment
ddev start
ddev stop

# Drush (Drupal CLI)
ddev drush cr                          # Clear/rebuild cache
ddev drush cex                         # Export config
ddev drush cim                         # Import config
ddev drush updb                        # Run database updates

# Run automation scripts (from project root)
ddev drush --uri=compas.ddev.site scr scripts/<filename>.php

# Composer
ddev composer install
ddev composer require drupal/<module>

# Database
ddev import-db --file=compas.sql.gz    # Import database snapshot
ddev export-db --gzip --file=backup.sql.gz

# SSH into container
ddev ssh
```

## Architecture

### Directory Structure

- `web/` — Drupal docroot
- `config/compas/` — Configuration sync directory (exported YAML config)
- `scripts/` — PHP automation scripts run via `ddev drush scr` (exam fields, views, test data)
- `recipes/` — Drupal recipes
- `.ddev/` — DDEV configuration (nginx, PHP, DB settings)

### Custom Modules (`web/modules/custom/`)

- **dae_content_migration** — CSV-based migration from a legacy D8 site (blog entries, pages). Uses `migrate_plus` with CSV source data in `data/`.
- **isl2_content_migration** — CSV-based migration for ISL2 content. Same pattern as above.

Both migration modules use `migrate_plus` and `migrate_source_csv` contrib modules.

### Key Contrib Modules

- `migrate_plus`, `migrate_source_csv`, `migrate_tools` — Content migration framework
- `devel` — Development/debugging tools
- `svg_image` — SVG file support
- `markdown_easy` — Markdown text format
- `fontyourface` — Font management

### Theme

The active theme is `compas` (custom sub-theme). The `basecore` contrib theme is the base theme. Multiple other contrib themes are installed (bootstrap_barrio, corporateclean, dxpr_theme, mili, tara, vani, zeropoint).

### Database

MariaDB 10.11. The DDEV post-start hook creates a secondary `isl2` database. Database snapshots are stored as `.sql.gz` files in the project root (`compas.sql.gz`, `isl2.sql.gz`, `web.sql.gz`).

### Content Architecture

- **Exam Type** taxonomy vocabulary (`exam_type`) — categories like COMPAS-A1, COMPAS-PY1. Has an image field.
- **Exam** content type — individual exam instances with fields: `field_exam_type` (reference to exam_type term), `field_exam_date`, `field_registration_start`, `field_registration_end`, `field_exam_fee`, `field_registration_link`, `field_exam_image`, `body`.
- **Page** content type — used for exam type landing pages (e.g., `/service/compas-py1`). Has `field_exam_type` to link the page to its exam type.

### Views

- **Services** (`/service`) — lists all exam types from taxonomy, with links to their page nodes.
- **Exam Listing** (block displays) — two blocks embedded on exam type pages: "Upcoming Exams" (`field_exam_date >= now`) and "Past Exams" (`field_exam_date < now`). Contextual filter auto-reads the exam type from the current node.

### Deployment

`DEPLOYMENT.md` in the project root tracks manual content changes needed after `drush cim` on production. When making content changes during development (e.g., setting field values on nodes), add a corresponding entry to this file.

### Scripts

The `scripts/` directory contains PHP automation scripts run via `ddev drush --uri=compas.ddev.site scr scripts/<filename>.php`. These handle programmatic setup of content types, fields, views, and test data. See `scripts/README.md` for the full list.