# Atelier Steel Art - Project Context

## Project Overview
"Atelier Steel Art" is a Laravel 12 web application built for a steel craftsmanship business. It serves as both a public showcase for their work (pergolas, stairs, guardrails, etc.) and an administrative platform for managing content.

### Key Features
- **Public Showcase:** Pages for various types of steel realisations, a photo gallery, and a news (actualities) section.
- **Admin Dashboard:** Protected area for managing gallery items, news articles, and administrator profiles.
- **Contact System:** Integrated contact form with automated email notifications.
- **Rich UI:** Interactive elements powered by Alpine.js and smooth animations using GSAP.

## Technical Stack
- **Backend:** PHP 8.2+ & Laravel 12
- **Frontend:** Vite, Tailwind CSS 4, Alpine.js, GSAP (animations)
- **Authentication:** Laravel Fortify
- **Database:** PostgreSQL (implied by typical Laravel usage) or SQLite (for local development)
- **Emailing:** Mailjet API via custom service implementation
- **Testing:** Pest PHP
- **Linting:** Laravel Pint
- **Optimization:** Laravel Boost

## Architecture & Design Patterns
- **Service Layer:** Email logic is decoupled using `EmailSenderInterface` and implemented via `MailjetEmailService`.
- **Controllers:** Organized into public (`ActualityController`, `GalleryController`, etc.) and administrative (`AdminDashboardController`, `AdminActualityController`).
- **Frontend Modules:** UI logic is modularized in `resources/js/AlpineModule` and specific JS files for animations and uploaders.
- **Routing:** Split into standard `web.php`, `auth.php` for authentication, and `admin.php` for the dashboard (protected by `auth` middleware).

## Building and Running

### Prerequisites
- PHP 8.2+
- Composer
- Node.js & npm

### Initial Setup
```bash
composer run setup
```
*This command installs dependencies, sets up the environment, generates keys, runs migrations, and builds assets.*

### Development Environment
```bash
composer run dev
```
*This starts the Laravel development server, the queue listener, and the Vite development server concurrently.*

### Building Assets
```bash
npm run build
```

## Testing and Quality
- **Running Tests:** `composer run test` (executes Pest tests).
- **Code Style:** Uses Laravel Pint for automated PHP code styling.

### Code Quality Tooling (PHP equivalents of PMD / Checkstyle)
The static-analysis stack mirrors the Java ecosystem the team is used to:

| Outil | Rôle | Équivalent Java | Config |
| :-- | :-- | :-- | :-- |
| **Laravel Pint** | Formatage / style | Checkstyle (auto-fix) | `pint.json` (preset `laravel`) |
| **Larastan / PHPStan** (level 5) | Analyse statique (bugs, types, modèles Eloquent) | SpotBugs / PMD bug rules | `phpstan.neon` |
| **PHPMD** | Complexité, code mort, design, nommage | PMD | `phpmd.xml` |

**Commandes (`composer ...`) :**
- `composer quality` — chaîne complète : `pint:test` → `analyse` → `phpmd` (gate qualité).
- `composer pint` — corrige le style ; `composer pint:test` — vérifie sans modifier.
- `composer analyse` — PHPStan/Larastan ; `composer phpmd` — PHPMD.

**Baselines (dette préexistante archivée pour partir d'un état vert) :**
- `phpstan-baseline.neon` — 16 erreurs PHPStan existantes (à résorber au fil de l'eau).
- `phpmd.baseline.xml` — 4 violations de complexité existantes.
- Ne pas régénérer un baseline pour masquer du **nouveau** code : corriger d'abord, puis ne baseliner que le legacy.
- Pour resserrer la rigueur : monter `level` dans `phpstan.neon` (5 → 9/max) après avoir vidé le baseline.

## Development Conventions
- **Routing:** Use named routes for all links. Admin routes are prefixed with `/admin` and require authentication.
- **Service Injection:** Always type-hint interfaces (like `EmailSenderInterface`) in constructors to allow for easy service swapping.
- **Frontend:** Prefer Alpine.js for interactive components. CSS should follow Tailwind CSS 4 utility patterns.
- **Modals & Toasts:** Reusable Blade components for UI feedback are located in `resources/views/partial`.

## Specialized Agents

Sub-agents are provided by the `@jack6tm-studio` plugin marketplace (all enabled globally — the full toolbox). **This section is the project's authoritative map**: it selects the agents relevant to Atelier Steel Art (Laravel 12 / Blade web app), defines the order in which to engage them, and how they hand off to one another. Each agent reads this `CLAUDE.md` at runtime for the real stack, versions, and folder structure — the plugin only carries stack expertise and house style.

> **Out of scope — do NOT delegate to these here:** `git-referent` (excluded by request) and every Spring / Flutter / Flame-game variant (`backend-architect-spring`, `frontend-architect-flutter`, `fullstack-spring-flutter`, `ux-designer`, `qa-test-spring`, `qa-test-flutter`, `flame-physics-expert`, `pixel-art-designer`, `game-audio-designer`). They stay enabled globally for other projects but are irrelevant to this Laravel stack.

### Agents in scope

**Stack — Laravel / Blade (build the feature)**
- **`fullstack-laravel`** — Default workhorse. Implements a feature end-to-end: route → Form Request → service/action → Blade → Alpine/GSAP. Start here for most feature work.
- **`backend-architect-laravel`** — Server-side design & SOLID arbitration (Eloquent models, migrations, services/actions, thin controllers). Engage when backend logic is non-trivial.
- **`frontend-architect-blade`** — UI architecture: Blade composition, Tailwind 4 tokens, Alpine.js, GSAP, Vite. Engage for ambitious interface decomposition / design-system work.
- **`qa-test-laravel`** — Pest/PHPUnit Feature & Unit tests, `RefreshDatabase` + factories, Laravel fakes (`Mail`, `Queue`, `Storage`…).

**Cross-cutting — Product, Security, Review (gate the feature)**
- **`business-product-owner`** — Upstream: business value, acceptance criteria (Given/When/Then), V1/V1.x/V2 roadmap arbitration.
- **`security-auditor`** — OWASP / auth / RGPD audit, GO/NO-GO verdict before prod (contact form, Fortify auth, `/admin` area, personal data).
- **`senior-code-reviewer`** — Last rampart: the code actually compiles, runs, and respects project standards.
- **`style-guardian`** — Code homogeneity, architecture compliance, zero technical debt (new code indistinguishable from existing).

**Web audits — read-only diagnostics (polish the public showcase)**
- **`accessibility-insight`** — WCAG 2.1/2.2 + Lighthouse A11Y.
- **`performance-insight`** — Core Web Vitals (LCP, INP, CLS), PageSpeed.
- **`seo-insight`** — Crawlability, meta tags, structured data, mobile-friendly.
- **`best-practices-insight`** — HTTPS, front security/CSP, deprecated APIs, console errors.

### Reading order & hand-offs (a feature's lifecycle)

1. **Frame** — `business-product-owner` sets the value and acceptance criteria → feeds them to QA and validates scope with the architects.
2. **Design** — `backend-architect-laravel` (server) and `frontend-architect-blade` (UI) produce the architecture *before* any code.
3. **Build** — `fullstack-laravel` implements end-to-end; it escalates heavy backend design back to `backend-architect-laravel` and ambitious UI back to `frontend-architect-blade`.
4. **Secure** — `security-auditor` audits critical paths, **hands the critical-scope perimeter to `qa-test-laravel`** for smoke tests, and sends required fixes back to `backend-architect-laravel`.
5. **Test** — `qa-test-laravel` covers the pyramid (Unit → Feature → HTTP → persistence); relies on `backend-architect-laravel` for tested-code conventions and on `security-auditor` for the critical perimeter.
6. **Review** — `senior-code-reviewer` (compiles / runs / meets standards) then `style-guardian` (stylistic harmony); both **defer architecture definition** to the architect agents and to this `CLAUDE.md`.
7. **Polish** — `accessibility-insight`, `performance-insight`, `seo-insight`, `best-practices-insight` run read-only audits and **hand implementation back** to `frontend-architect-blade` / `fullstack-laravel`.

### Cross-reference map (who delegates to whom)

| Agent | Hands off / delegates to | Receives input from |
| :-- | :-- | :-- |
| `business-product-owner` | architects (scope), `qa-test-laravel` (acceptance criteria) | — |
| `backend-architect-laravel` | `senior-code-reviewer`, `style-guardian` | `fullstack-laravel`, `security-auditor`, `qa-test-laravel` |
| `frontend-architect-blade` | `accessibility-insight` (deep A11Y) | `fullstack-laravel`, web-audit agents |
| `fullstack-laravel` | `backend-architect-laravel`, `frontend-architect-blade` | `business-product-owner` |
| `security-auditor` | `qa-test-laravel` (perimeter), `backend-architect-laravel` (fixes) | — |
| `qa-test-laravel` | `backend-architect-laravel` (conventions) | `security-auditor` (perimeter) |
| `senior-code-reviewer` | open questions → this `CLAUDE.md` / architects | all build agents |
| `style-guardian` | architects (architecture authority) | all build agents |
| `accessibility-insight` | `frontend-architect-blade` / `fullstack-laravel` | ↔ `performance-insight`, `seo-insight` |
| `performance-insight` | `frontend-architect-blade` / `fullstack-laravel` | ↔ `accessibility-insight`, ← `seo-insight` |
| `seo-insight` | `performance-insight` (speed / CWV) | ↔ `accessibility-insight` |
| `best-practices-insight` | `frontend-architect-blade` / `fullstack-laravel` | — |