# 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 project for the Biatorbagy municipality website (biatorbagy.hu). The project uses Composer for dependency management and follows a standard Drupal recommended project structure with the web root at `web/`.

## Development Commands

### Theme Development
The custom theme is located at `web/themes/custom/biatorbagy` and uses Gulp for asset compilation:

```bash
cd web/themes/custom/biatorbagy
npm install
npm run build        # Build all assets (CSS, JS, images, fonts)
npm run buildStyle   # Build only SCSS
npm run buildJs      # Build only JavaScript
npm run buildImages  # Copy images
npm run watch        # Watch for changes
```

Theme assets are compiled from `src/` to `dist/` directory.

### Drupal/Drush Commands
Always use the vendored Drush binary:

```bash
vendor/bin/drush cr                    # Clear cache
vendor/bin/drush cex -y               # Export configuration
vendor/bin/drush cim -y               # Import configuration
vendor/bin/drush updatedb -y          # Run database updates
vendor/bin/drush uli                  # Generate one-time login link
```

### Composer
```bash
composer install                       # Install dependencies
composer require drupal/[module]       # Add new module
composer update drupal/[module]        # Update specific module
```

### Code Quality
```bash
vendor/bin/phpcs                       # Run PHP_CodeSniffer (checks web/modules/custom and web/themes/custom)
vendor/bin/phpcbf                      # Auto-fix coding standards
```

## Deployment

### Deployment Targets
The project uses **Capistrano** (Ruby-based) for deployment with three environments:

- **demo**: https://biatorbagy.node8.macroweb.hu/ (deploys from `master` branch automatically via GitLab CI)
- **staging**: https://staging.biatorbagy.hu/ (deploys from `live` branch, manual trigger)
- **production**: https://www.biatorbagy.hu/ (deploys from `live` branch, manual trigger)

### Deployment Process
```bash
# Manual deployment via Capistrano
bundle install
bundle exec cap demo deploy
bundle exec cap staging deploy
bundle exec cap production deploy
```

GitLab CI automatically:
1. Builds theme assets (`buildTheme` stage)
2. Deploys code and runs Capistrano tasks

### What Happens During Deployment
The Capistrano deployment (see `lib/capistrano/tasks/drupal_deploy.rake`):
1. Puts site into maintenance mode
2. Installs Composer dependencies
3. Runs database updates (`drush updatedb`)
4. Imports configuration (`drush config:import`)
5. Rebuilds cache
6. Takes site out of maintenance mode

Custom deployment tasks available:
- `drupal:site:offline` / `drupal:site:online` - Toggle maintenance mode
- `drupal:site:backup` - Backup database
- `drupal:cache:clear` - Clear Drupal cache
- `cex` - Export config and download to local
- `dump` - Download database dump and import locally

## Architecture

### Directory Structure
```
/var/www/html/biatorbagy/
├── web/                           # Document root
│   ├── core/                     # Drupal core
│   ├── modules/
│   │   ├── contrib/              # Contributed modules
│   │   └── custom/               # Custom modules (see below)
│   ├── themes/
│   │   ├── contrib/
│   │   └── custom/
│   │       ├── biatorbagy/       # Main public theme (Gulp-based)
│   │       └── biatorbagy_admin/ # Admin theme (Gin-based)
│   └── sites/default/
│       ├── settings.php          # Shared across environments
│       └── files/                # Uploaded files
├── config/
│   ├── sync/                     # Configuration management (version controlled)
│   └── deploy/                   # Capistrano environment configs
├── vendor/                       # Composer dependencies
├── composer.json                 # PHP dependencies
└── patches/                      # Local patches
```

### Custom Modules
Located in `web/modules/custom/`:

- **biatorbagy_base** - Base functionality module, main custom code
- **biatorbagy_helper** - Helper utilities
- **biatorbagy_paragraphs** - Custom paragraph types definitions
  - Sub-module: **paragraphs_block_reference** - Block reference paragraph type
- **biatorbagy_custom_hooks** - Custom hooks implementation
- **old_data_migration** - Legacy data migration scripts

### Configuration Management
- Configuration is stored in `config/sync/` and version controlled
- Export changes: `vendor/bin/drush cex -y`
- Import changes: `vendor/bin/drush cim -y`
- The deployment process automatically imports configuration

### Patches
The project uses `cweagans/composer-patches` for applying patches:
- Patches are defined in `composer.json` under `extra.patches`
- Local patches are stored in the `patches/` directory
- Current patches applied:
  - Drush site-local path detection fix
  - Drupal core RSS enclosure support (#2511878)
  - Drupal core status message theme suggestions (#3456176)
  - Drupal core empty exception handling (#3388941)
  - Pathauto PHP 8.1 compatibility (#3313566)

### Shared Files in Deployment
The following are shared between releases (symlinked):
- `web/sites/default/settings.php`
- `web/sites/default/services.yml`
- `files/` directory
- `web/sites/default/files/` directory

## Key Dependencies

### Drupal Modules (Notable)
- **admin_toolbar** - Enhanced admin toolbar
- **paragraphs** - Content paragraphs system
- **backup_migrate** - Database backups
- **pathauto** - Automatic URL aliases
- **metatag** - SEO meta tags
- **gin** - Admin theme
- **stage_file_proxy** - Proxy files from production to local
- **devel** - Development tools

### Frontend Libraries
- Swiper 9.4.1 (npm-asset)
- SimpleLightbox (npm-asset)

### Build Tools
- Gulp 4 for theme compilation
- Sass for CSS preprocessing
- Autoprefixer for CSS vendor prefixing

## Local Development

### Setting up Stage File Proxy
When working locally with production database:
```bash
vendor/bin/drush en stage_file_proxy
vendor/bin/drush config-set stage_file_proxy.settings origin "https://biatorbagy.hu"
```

This proxies file requests to production instead of downloading all files.

### Git Workflow
- **master** branch: Development/demo environment
- **live** branch: Staging and production environments
- Commit messages reference Atrium ticket system: `Case: https://atrium.macroweb.hu/biatorbagy/node/[ID]`

## Important Notes

### PHP Configuration
Deployment uses custom PHP paths:
- Demo: `/opt/cpanel/ea-php83/root/usr/bin/php` (PHP 8.3)

### File Permissions
The deployment process sets specific permissions:
- Directories: 755
- Files: 644
- `files/` directories: 777
- `files/` files: 666

### Maintenance Mode
Maintenance mode is automatically managed during deployment but can be manually toggled:
```bash
vendor/bin/drush state:set system.maintenance_mode 1  # Enable
vendor/bin/drush state:set system.maintenance_mode 0  # Disable
```

## System Info

- **Drupal Core Version**: 10.6.3
- **Last checked**: 2026-02-26