# 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

MJKSZ is a Drupal 10.6.3 site for a Hungarian livestock/sheep breeding association. It is a multilingual site (Hungarian + English) using domain-based language negotiation:
- Hungarian: `macroweb.mjksz.hu` (prod: `mjksz.hu`)
- English: `macroweb.mjksz.com` (prod: `mjksz.com`)

This is a Composer-managed Drupal project based on `macroweb/macroweb-drupal-skeleton`. See the parent `/var/www/html/CLAUDE.md` for shared environment details, aliases, and workflow scripts.

## Common Commands

```bash
# Clear Drupal caches
vendor/bin/drush cr

# Import configuration from filesystem
vendor/bin/drush config:import -y

# Export configuration to filesystem
vendor/bin/drush config:export -y

# Run database updates
vendor/bin/drush updb -y

# Import translations (Hungarian)
vendor/bin/drush locale:import hu translations/hu.po --override=all --type=customized

# Run migrations
vendor/bin/drush migrate:import <migration_id>
vendor/bin/drush migrate:rollback <migration_id>
```

**Note**: The PHP CLI version is 8.4. Drush must be called as `vendor/bin/drush` from the project root (`/var/www/html/mjksz`).

## Configuration Management

Configuration is split by environment using `config_split`:
- `config/sync/` — base configuration (always active)
- `config_demo/` — demo/local environment split (active on dev)
- `config_stag/` — staging split
- `config_prod/` — production split

The active split is set in `web/sites/default/settings.php`. On local/dev, `config_demo` is enabled. When deploying, Capistrano imports the appropriate split via `drush config-split:import config_<stage>`.

## Deployment

Deployment uses Capistrano. The deploy tasks are in `lib/capistrano/tasks/drupal_deploy.rake`. The deploy sequence runs:
1. `composer install`
2. `drush updatedb`
3. `drush config:import` (twice)
4. `drush config-split:import config_<stage>`
5. `drush locale:import` for `hu`

## Architecture

### Directory Structure

```
web/                        # Drupal web root
  modules/custom/           # Site-specific custom modules
  themes/custom/mjksz/      # Custom theme (Classy subtheme, uses SCSS)
  profiles/custom/mds-config-profile/  # Installation profile with shared base modules
config/sync/                # Drupal configuration export
config_demo/                # Config split: demo/local
config_stag/                # Config split: staging
config_prod/                # Config split: production
private_files/              # Private file storage (outside web root)
tmp/                        # Temporary files (outside web root)
translations/               # PO translation files (hu.po)
patches/                    # Local Composer patches
```

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

**Domain entities** (each provides a custom Drupal entity type):
- `breeding_result` — Breeding result entity
- `ram_catalog` — Ram catalog entity
- `colleague` — Colleague entity
- `partner_logo` — Partner logo entity
- `position` — Position entity (with position_type taxonomy)

**Hooks and business logic**:
- `mjksz_custom_hooks` — Main hooks module; alters routes (`user.page`, `entity.user.canonical`), forms, views. Contains: `Controller/UserEditController`, `Controller/MyAdvertismentsController`, `Services/RouteSubscriber`, `Plugin/Block/`, `Plugin/QueueWorker/`, `Plugin/PasswordConstraint/`
- `mjkszaukcio_custom_hooks` — Auction-specific hooks; integrates with `macroweb/auction` package. Provides `Form/MJKSZAukcioSettingsForm` for configuring auction-related role/settings

**User & notifications**:
- `user_changes_notification` — Emails administrators when users update their profile data
- `mjksz_user_block` — Custom block showing user-related data
- `mjksz_home_page` — Custom home page controller

**Migrations** (import from XLSX spreadsheets via `migrate_spreadsheet`):
- `mjksz_user_migrations` — Bulk user import from XLSX
- `mjksz_breeding_result_migration` — Bulk breeding result import from XLSX

**Utilities**:
- `force_password_reset` — Forces password reset for specific users
- `drush_locale_rebuild` — Custom Drush command for locale rebuild

### Installation Profile (`web/profiles/custom/mds-config-profile/`)

The `mds_config` profile is the base Macroweb installation profile. It includes sub-modules:
- `copyright_block` — Footer copyright block
- `macroweb_custom_hooks` — Shared Macroweb hooks
- `macroweb_media` — Media configuration
- `untranslated_redirect` — Redirects users to translated content

### Custom Theme (`web/themes/custom/mjksz/`)

Subtheme of `classy`. Uses SCSS (compiled via `config.rb`). Theme regions: `header_top`, `header`, `primary_menu`, `secondary_menu`, `content`, `sidebar_first`, `sidebar_second`, `footer_top`, `footer`, `highlighted`, `help`, `breadcrumb`.

### Key Contrib Packages

- `macroweb/auction` — Macroweb private auction package (provides `Bid` entity, `MJKSZAuctionHighestBid` controller)
- `macroweb/promobar` — Macroweb promo bar
- `drupal/rules` + `drupal/rules_token` — Business rules automation
- `drupal/webform` — Forms and submissions
- `drupal/search_api` + `drupal/facets` — Search functionality
- `drupal/content_moderation_notifications` — Email notifications on moderation state changes
- `drupal/migrate_spreadsheet` — XLSX migration source

## Patches

Local patches are stored in `patches/`. **Important**: `patches/colorbox-remote-video-support-3021913-49-CUSTOMIZED.patch` is a **customized** version — do NOT replace it with the upstream patch from drupal.org. See the comment in `composer.json` referencing the internal ticket.

When adding a new patch, add it to the `extra.patches` section in `composer.json` and run `composer install`.

## Content Types & Moderation

The site uses Drupal Content Moderation. The `advertisment` node type has moderation state access controlled by role in `mjksz_custom_hooks_form_alter()` — editors and administrators see the moderation widget, others do not.