# CLAUDE.md

**IMPORTANT**: This file contains project-specific instructions. Always read the global environment instructions first: `/var/www/html/CLAUDE.md`

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

## Project Overview

This is a Drupal 10 website for Csopaki Református Iskola (Csopak Reformed School), built using Macroweb's Drupal skeleton. The project uses Composer for dependency management, Capistrano for deployment, and follows a configuration-driven workflow.

## Technology Stack

- **CMS**: Drupal 10.6.2
- **PHP Version**: PHP 8.3 (configured in deployment)
- **Deployment**: Capistrano 3.19
- **Dependency Management**: Composer
- **Drush**: 12.5+
- **Theme**: Magazine Lite (based on Classy)
- **Custom Module**: refiskolacsopak_custom_hooks

## Common Commands

### Composer Operations
```bash
# Install/update dependencies
php8.3 composer.phar install
php8.3 composer.phar update

# Using local composer.phar
php composer.phar install
```

### Drush Commands
```bash
# Use drush through vendor/bin
vendor/bin/drush status
vendor/bin/drush cache:rebuild
vendor/bin/drush updatedb -y
vendor/bin/drush config:import -y
vendor/bin/drush config:export -y

# Configuration management
vendor/bin/drush config-split:import config_dev -y
vendor/bin/drush config-split:import config_prod -y

# Locale operations
vendor/bin/drush locale:check
vendor/bin/drush locale:update
vendor/bin/drush locale:import:all translations --override=all --type=customized --yes

# Maintenance mode
vendor/bin/drush state:set system.maintenance_mode TRUE
vendor/bin/drush state:set system.maintenance_mode FALSE

# Database backup
vendor/bin/drush eval 'backup_migrate_perform_backup("default_db", "private_files", []);'
```

### Deployment

Deployments are managed via Capistrano and GitLab CI/CD.

```bash
# Deploy to development (automatic on master branch push)
bundle install
bundle exec cap dev deploy

# Deploy to production (manual trigger on live branch)
bundle exec cap production deploy

# Setup a new site from scratch
bundle exec cap [dev|production] drupal:site:setup
```

**Key Deployment Stages:**
1. Puts site in maintenance mode
2. Runs `composer install`
3. Runs database updates (`drush updatedb`)
4. Imports configuration (`drush config:import`)
5. Imports environment-specific config split
6. Updates translations
7. Clears cache and takes site out of maintenance mode

**Environments:**
- **Development**: https://dev.refiskolacsopak.node8.macroweb.hu/ (auto-deployed from `master`)
- **Production**: https://www.refiskolacsopak.hu/ (manual deploy from `live` branch)

### Git Workflow

- Primary development branch: `master`
- Production branch: `live` (requires manual deployment approval)
- Commits reference Atrium case management: https://atrium.macroweb.hu/

## Code Architecture

### Directory Structure

```
/
├── config/              # Capistrano deployment configuration
│   ├── deploy.rb       # Main deployment config
│   ├── deploy/
│   │   ├── dev.rb      # Development environment
│   │   └── production.rb
│   └── sync/           # Drupal configuration files (tracked in git)
│       ├── default/    # Base configuration
│       ├── dev/        # Dev-specific config split
│       └── prod/       # Production-specific config split
├── lib/
│   └── capistrano/
│       └── tasks/
│           └── drupal_deploy.rake  # Custom Capistrano tasks
├── patches/            # Composer patches for modules
├── private_files/      # Private file storage (not in web root)
├── translations/       # Custom translation files (.po)
├── vendor/             # Composer dependencies (symlinked on deploy)
├── web/                # Document root
│   ├── core/          # Drupal core
│   ├── libraries/     # Third-party libraries (CKEditor plugins, etc.)
│   ├── modules/
│   │   ├── contrib/   # Contributed modules
│   │   └── custom/    # Custom modules
│   │       └── refiskolacsopak_custom_hooks/
│   ├── sites/
│   │   └── default/
│   │       ├── files/           # Public file uploads (symlinked)
│   │       ├── settings.php     # Main settings (symlinked from shared)
│   │       └── settings.local.php
│   └── themes/
│       ├── contrib/   # Contributed themes
│       └── magazine_lite/  # Active theme (custom-configured)
├── composer.json       # Project dependencies
└── Capfile            # Capistrano entry point
```

### Configuration Management

This site uses **Configuration Split** for environment-specific settings:
- Base config: `config/sync/default/`
- Dev config: `config/sync/dev/` (split: `config_dev`)
- Production config: `config/sync/prod/` (split: `config_prod`)

**Workflow:**
1. Export configuration: `vendor/bin/drush config:export -y`
2. Commit changes to git
3. Import on target: `vendor/bin/drush config:import -y`
4. Apply environment split: `vendor/bin/drush config-split:import config_[dev|prod] -y`

### Custom Module: refiskolacsopak_custom_hooks

Located at `web/modules/custom/refiskolacsopak_custom_hooks/`, this module contains site-specific customizations and hooks.

### Theme: Magazine Lite

The Magazine Lite theme is extensively customized:
- Base theme: Classy
- Custom stylesheets defined in `iskola-style` library
- CKEditor 5 content styles: `iskola/css/content-layout.css`
- Multiple regions (70+ regions for flexible layout)

### Applied Patches

Patches are managed via `cweagans/composer-patches`:
- **Drush**: Site-local path detection fix
- **entity_embed**: Invalid display settings logging reduction, array-to-string conversion fix
- **htmlawed**: CKEditor 5 compatibility

## Key Drupal Modules

Notable contrib modules in use:
- **admin_toolbar**: Enhanced admin menu
- **backup_migrate**: Database/file backups
- **paragraphs**: Content components
- **linkit**, **entity_embed**, **entity_browser**: Content editing enhancements
- **pathauto**, **redirect**, **metatag**: SEO
- **config_split**: Environment-specific configuration
- **google_analytics**: Analytics tracking
- **eu_cookie_compliance**: GDPR compliance
- **search_api**: Advanced search
- **xmlsitemap**: XML sitemap generation

## Development Notes

### Local Development Setup

1. Clone repository
2. Install dependencies: `composer install`
3. Configure `web/sites/default/settings.local.php` with database credentials
4. Import configuration: `vendor/bin/drush config:import -y`
5. Import dev config split: `vendor/bin/drush config-split:import config_dev -y`
6. Clear cache: `vendor/bin/drush cache:rebuild`

### Making Configuration Changes

1. Make changes in Drupal admin UI
2. Export config: `vendor/bin/drush config:export -y`
3. Review changes with `git diff config/`
4. Commit configuration files
5. Deploy (config import happens automatically during deployment)

### Translation Workflow

Custom translations are stored in `translations/` directory:
- Import: `vendor/bin/drush locale:import:all translations --override=all --type=customized --yes`
- This runs automatically during deployment

### File System

- **Public files**: `web/sites/default/files/` (symlinked from shared)
- **Private files**: `private_files/` at project root (symlinked from shared)
- **Temporary files**: `/tmp/` or as configured in settings.php

### Capistrano Deployment Details

Linked files/directories (persist across deployments):
- `web/sites/default/settings.php`
- `web/sites/default/settings.local.php`
- `web/.htaccess`
- `web/sites/default/files/`
- `vendor/`
- `private_files/`

### PHP Configuration

Deployment uses custom PHP paths:
- Dev/Prod: `/opt/cpanel/ea-php83/root/usr/bin/php`
- Memory limit: unlimited during drush operations
- Display errors: enabled for drush

## Testing and Code Quality

Development dependencies include:
- `drupal/core-dev`: Development tools
- `drupal/devel`: Development module

Note: No automated test suite or linting is currently configured in the CI/CD pipeline.

## Important Caveats

- Always test configuration imports on development before deploying to production
- Database backups can be triggered via Drush but are currently commented out in automatic deployment
- The site uses custom .htaccess rules (not scaffolded from Drupal core)
- Composer patches are critical for proper module functionality - do not remove without testing

## System Info

- **Drupal Core Version**: 10.6.2
- **Last checked**: 2026-01-27