Chore/cleaning archi

.env

@@ -40,3 +40,13 @@ MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
 ###> symfony/mailer ###
 MAILER_DSN=null://null
 ###< symfony/mailer ###
+
+###> symfony/mercure-bundle ###
+# See https://symfony.com/doc/current/mercure.html#configuration
+# The URL of the Mercure hub, used by the app to publish updates (can be a local URL)
+MERCURE_URL=http://mercure/.well-known/mercure
+# The public URL of the Mercure hub, used by the browser to connect
+MERCURE_PUBLIC_URL=http://localhost:3000/.well-known/mercure
+# The secret used to sign the JWTs
+MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"
+###< symfony/mercure-bundle ###

.github/workflows/quality.yml

@@ -0,0 +1,92 @@
+name: Code Quality
+
+on:
+  push:
+    branches: [ main, develop, chore/*, feature/*, fix/* ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  quality-checks:
+    name: Quality Checks (PHP 8.4)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml, ctype, iconv, intl, pdo_sqlite, dom, filter, json
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate --strict
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v3
+        with:
+          path: vendor
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-composer-
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
+      - name: Run PHPStan (Level Max)
+        run: vendor/bin/phpstan analyse --no-progress --error-format=github --memory-limit=512M
+
+      - name: Run PHP-CS-Fixer (Check only)
+        run: vendor/bin/php-cs-fixer fix --dry-run --diff --verbose
+
+      - name: Run PHPUnit Tests
+        run: vendor/bin/phpunit --testdox
+
+      - name: Run PHPMD
+        run: vendor/bin/phpmd src github rulesets.xml
+        continue-on-error: true
+
+      - name: Run PHPArkitect (Architecture validation)
+        run: vendor/bin/phparkitect check
+
+  phpunit-coverage:
+    name: PHPUnit with Coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml, ctype, iconv, intl, pdo_sqlite, dom, filter, json
+          coverage: xdebug
+          tools: composer:v2
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v3
+        with:
+          path: vendor
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-composer-
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
+      - name: Run PHPUnit with Coverage
+        run: vendor/bin/phpunit --coverage-text --coverage-clover=coverage.xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false

AGENTS.md

@@ -0,0 +1,52 @@
+# Quick Reference for Coding Agents
+
+## Commands
+```bash
+# Database & Fixtures
+make db.reset          # Drop, create, migrate database (empty)
+make db.refresh        # Reset database + load YAML fixtures
+make fixtures          # Load benchmarks from fixtures/benchmarks/*.yaml
+
+# Tests
+docker-compose run --rm main vendor/bin/phpunit                    # All tests
+docker-compose run --rm main vendor/bin/phpunit tests/Path/To/SpecificTest.php  # Single test
+
+# Code Quality
+make phpcsfixer-fix    # Fix code style (PSR-12)
+make phpstan           # Static analysis (level 9)
+make quality           # Run all checks + fixes
+
+# Assets (CSS/JS)
+make assets.refresh    # Force refresh assets: compile, regenerate hashes, clear cache, restart
+                       # Use when CSS/JS changes don't appear in browser
+                       # Don't forget to hard refresh browser (Ctrl+Shift+R)
+
+# Benchmarks
+make run test=Loop iterations=10              # Run specific benchmark
+docker-compose run --rm main php bin/console benchmark:run --test=Loop --php-version=php84
+
+# Mercure (Real-Time)
+./scripts/mercure-verify.sh              # Verify Mercure setup
+./scripts/mercure-listen.sh              # Watch real-time events
+./scripts/mercure-test.sh 5 Loop php84   # End-to-end test
+```
+
+## Code Style
+- **PHP 8.4+** with `declare(strict_types=1)` at top of every file
+- **PSR-12** + Symfony style enforced by PHP-CS-Fixer
+- **Imports**: Fully qualified, alphabetically sorted (classes, functions, constants)
+- **Arrays**: Short syntax `[]`, trailing commas in multiline
+- **Strings**: Concatenation with ` . ` (spaces around dot)
+- **Comparison**: Strict (`===`, `!==`) always, Yoda style (`null === $var`)
+- **Classes**: `final readonly` by default, ordered elements (constants → properties → constructor → methods)
+- **Types**: Full type hints everywhere (params, returns, properties with asymmetric visibility `public private(set)`)
+- **PHPDoc**: Only for interfaces, complex return types (`@return Type[]`), or "why" explanations
+
+## Architecture (Clean + DDD + Hexagonal)
+- **Namespace**: `Jblairy\PhpBenchmark\{Domain|Application|Infrastructure}\...`
+- **Dependencies flow INWARD**: Infrastructure → Application → Domain
+- **Domain**: Pure PHP, no framework (Symfony/Doctrine), defines Ports (interfaces)
+- **Infrastructure**: Implements Adapters for Domain Ports, uses any library
+- **Naming**: Ports end with `Port`, Value Objects are nouns, Services are verbs
+
+See [docs/architecture/01-overview.md](docs/architecture/01-overview.md) and [CLAUDE.md](CLAUDE.md) for details.