feat(docs): Add CLAUDE.md for project guidance and architecture overview

Author: fmontes

examples/dotcms-symfony/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Symfony 7.2 application that demonstrates integration with DotCMS using the DotCMS PHP SDK. It serves as a headless CMS frontend that dynamically renders pages, layouts, containers, and content from DotCMS.
+
+## Key Architecture Components
+
+### Core Integration Pattern
+- **Catch-all routing**: Single controller (`CatchAllController`) handles all page requests via a catch-all route
+- **Service layer**: `DotCMSService` wraps the DotCMS PHP SDK client for consistent API access
+- **Twig extensions**: `DotCMSExtension` provides template functions for rendering DotCMS content
+- **Exception mapping**: DotCMS SDK exceptions are mapped to appropriate Symfony HTTP exceptions
+
+### DotCMS Integration Flow
+1. Symfony router matches catch-all route to `CatchAllController::show()`
+2. Controller extracts path and optional query parameters (language_id, mode, personaId, publishDate)
+3. `DotCMSService` creates page request with parameters and fetches from DotCMS API
+4. Page data (layout, containers, contentlets) is passed to Twig templates
+5. Twig extension functions render content-type specific templates or fall back to SDK utilities
+
+### Template Architecture
+- `templates/page.html.twig`: Main page template that renders layout rows/columns
+- `templates/dotcms/container.twig`: Container template with contentlet rendering
+- `templates/dotcms/content-types/`: Content-type specific templates (banner.twig, product.twig, etc.)
+- `templates/dotcms/header.twig`: Navigation rendering using DotCMS navigation API
+
+## Development Commands
+
+### Start Development Server
+```bash
+symfony server:start
+```
+
+### Testing
+```bash
+# Run all tests
+vendor/bin/phpunit
+
+# Or using Symfony's PHPUnit bridge
+php bin/phpunit
+```
+
+### Dependency Management
+```bash
+# Install dependencies
+composer install
+
+# For local SDK development
+COMPOSER=composer.dev.json composer install
+```
+
+### Cache and Assets
+```bash
+# Clear cache
+php bin/console cache:clear
+
+# Install assets
+php bin/console assets:install
+
+# Update importmap
+php bin/console importmap:install
+```
+
+## Configuration
+
+### Environment Variables
+- `DOTCMS_HOST`: DotCMS instance URL (default: https://demo.dotcms.com)
+- `DOTCMS_API_KEY`: API key for DotCMS authentication
+
+### Service Configuration
+DotCMS client is configured in `config/services.yaml`:
+- `dotcms.client`: Main DotCMSClient service
+- `dotcms.config`: Configuration with host, API key, and client options
+- Client timeout: 30 seconds, SSL verification enabled
+- Debug logging enabled for development
+
+## Key Files and Their Purpose
+
+### Controllers
+- `src/Controller/CatchAllController.php`: Handles all page requests, fetches from DotCMS, maps exceptions
+
+### Services
+- `src/Service/DotCMSService.php`: Wraps DotCMS client, provides page and navigation methods with parameter support
+
+### Twig Extensions
+- `src/Twig/DotCMSExtension.php`: Template functions for content rendering, HTML attributes, grid classes
+
+### Templates
+- `templates/page.html.twig`: Main page template with layout rendering
+- `templates/dotcms/container.twig`: Container and contentlet rendering with DotCMS attributes
+- `templates/dotcms/content-types/`: Content-type specific templates
+
+## Working with Content Types
+
+To add support for new content types:
+1. Create template in `templates/dotcms/content-types/{content-type}.twig`
+2. Template receives `content` variable (Contentlet object) and `dotcms_host` variable
+3. The `generateHtmlBasedOnProperty` function automatically finds and renders the template
+4. Falls back to SDK's `simpleContentHtml` if no template exists
+
+## Error Handling
+
+The application maps DotCMS SDK exceptions to Symfony HTTP exceptions:
+- `HttpException` codes 400, 401, 404, 500, 503 map to corresponding Symfony exceptions
+- `ResponseException` maps to `ServiceUnavailableHttpException`
+- All unmapped exceptions default to `ServiceUnavailableHttpException`
+
+## Development Notes
+
+- Uses Symfony 7.2 with PHP 8.2+ requirement
+- Includes Doctrine ORM, Twig, Stimulus, and other standard Symfony components
+- PHPUnit configured for testing with Symfony bridge
+- Asset mapper handles frontend assets (CSS, JS)
+- Development uses local PHP SDK when `composer.dev.json` is specified