# CLAUDE.md

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

## Project Overview

TYPO3 12.4 distribution for the Awinta website (www.awinta.de), developed and maintained by bgm GmbH. The project hosts multiple sites from a single TYPO3 instance and is deployed via GitLab CI + Deployer.

## Commands

### PHP / Composer

```bash
# Install dependencies
composer install

# Code quality checks (run before committing)
composer run ec                 # EditorConfig validation
composer run typoscript-lint    # TypoScript linting
composer run php-cs-fixer       # PHP code style (dry-run)
composer run yamllint           # YAML linting
composer run phpstan            # Static PHP analysis
composer run rector             # Check for code modernization (dry-run)
```

To auto-fix PHP code style (not dry-run), omit `--dry-run` from the script or run directly:
```bash
./vendor/bin/php-cs-fixer fix --config=Build/Test/php_cs.php -v --using-cache=no
```

### Front-end Assets (Grunt)

```bash
npm install         # Install Node dependencies once
grunt               # Compile SCSS → CSS and bundle Foundation JS (default task)
grunt watch         # Watch SCSS and recompile on change
grunt sass          # SCSS compilation only
grunt sass:atom     # Compile atom-level SCSS components
```

Compiled assets land in `packages/bgm_theme_awinta/Resources/Public/Css/` and `…/Js/`.

### TYPO3 CLI

```bash
./vendor/bin/typo3 cache:flush
./vendor/bin/typo3 database:updateschema
./vendor/bin/typo3 extension:setup
```

## Architecture

### Repository Structure

```
packages/               # Local TYPO3 extensions (path repositories in composer.json)
│   bgm_theme_awinta/   # Main site distribution + theme
│   awinta_contacts/    # Contact locator (postal code → area manager)
config/
│   sites/              # One subdirectory per TYPO3 site (awinta, azh, noventi, …)
│   system/             # settings.php + additional.php (generated on deploy)
public/                 # Web root (TYPO3 document root)
Build/
│   Docker/             # Dockerfile (PHP 8.2 + Node 14 + Grunt) and entrypoint
│   Test/               # Config files for all linters (php_cs.php, phpstan.neon, …)
│   deployer/           # Deployer recipes for production + review deployments
│   Shell/              # DataDeployment.sh, DatabaseCompare.sh
vendor/                 # Composer-managed dependencies
```

### TYPO3 Extension Conventions

Both local extensions follow the standard TYPO3 Extbase layout:

- `Classes/` — PHP, PSR-4 autoloaded under the `Bgm\<ExtensionName>\` namespace
- `Configuration/TCA/`, `Configuration/TypoScript/`, `Configuration/Flexforms/`
- `Resources/Private/` — Fluid templates, partials, SCSS/JS sources
- `Resources/Public/` — Compiled CSS, JS, fonts, images
- `ext_localconf.php` — Extension bootstrapping
- `ext_tables.php` — Backend table registration
- `ext_tables.sql` — Custom database tables

### bgm_theme_awinta — Main Distribution

This is the primary extension and the only place for:
- **SCSS source files** (`Resources/Private/Scss/`): `styles.scss`, `rte.scss`, `azh.scss`, `stage.scss`, plus an `atom/` sub-folder for component-level stylesheets
- **Custom content elements** (`ContentBlocks/ContentElements/`) using the `friendsoftypo3/content-blocks` API
- **Fluid templates and partials** for all page and content layouts
- **TypoScript configuration** loaded via `ext_localconf.php`

The Grunt build reads SCSS from this extension, includes Foundation 6 SCSS from `vendor/zurb/foundation/scss/`, and writes compiled CSS back to `Resources/Public/Css/`.

### Multi-Site Setup

Seven sites are configured under `config/sites/`. Each has its own `config.yaml` with language, domain, and routing settings. All share the same TYPO3 database and extensions.

### Front-end Stack

- **Foundation 6.7.5** (CSS framework, SCSS-based) — only selected JS plugins are bundled (see `Gruntfile.js`)
- **SingularityGS** (grid system), **Breakpoint-SASS** (media queries), **Compass mixins** — all available as SCSS mixins
- **Autoprefixer** (PostCSS) runs after SCSS compilation

### Deployment

Deployments are fully automated via `.gitlab-ci.yml`:

| Branch pattern | Stage | Target |
|---|---|---|
| `BuildDeployment.*` | build-deployment | Builds Docker image |
| `BuildDevelopment.*` | build-development | Syncs prod data → dev |
| `BuildReview.*` | build-review | Syncs prod data → review |
| `main` (manual) | deploy-review | https://review.awinta.de |
| `main` (manual) | deploy-production | https://www.awinta.de |

Deployer recipes live in `Build/deployer/`. The production server is `nov-fe-1`.

### External / Private Packages

Three private extensions are pulled from the bgm GitLab instance via SSH:
- `bgm/bgm-changelog` — changelog backend module
- `bgm/bgm-doorkeeper` — access control
- `bgm/bgm-fileversion` — file versioning