ERR_EMPTY_RESPONSE

[nop1984]

Pretty annoying thing.
If you catch this one by opening "bad mdx" - all logs are clean, but whole app is sending ERR_EMPTY_RESPONSE despite its up running. You gonna need to restart whole nextjs container to make other pages working (bad one still will be putting app in not operatable state)

Yet is not very clear what exactly does this, but I suspect it is about MDX parse/syntax

[nop1984]

literally impossible to reproduce

I have "bad MDX"

I copy its content to notepad and adding block by block to VS code - block by block appears in NextJS dev mode.
I refresh the page - and SUBJ - its broken (despite all content was displayed before)

[nop1984]

upgrade to next16 - does't help
enforcing Webpack - does not help

[nop1984]

MDX itself

---
title: Search Sessions
description: Server-Side Search Criteria implementation.
icon: Database
---

# Server-Side Search Criteria (SSSC) Implementation Plan

## Overview

Implement a **Server-Side Search Criteria (SSSC)** system to persist search filters and pagination state server-side, enabling:

1. Shareable search URLs with simple UUID reference
2. Reduced request payload size (filters stored once, referenced by ID)
3. Persistent PIT (Point-in-Time) context across pagination
4. User-scoped search history tracking

**Alternative Names:**

- `SearchSession` (shorter, clearer purpose)
- `SearchContext` (describes what it holds)
- `PersistedSearchCriteria`
- **Recommended: `SearchSession`** (clearest, most intuitive)

## Architecture

### Storage Layer

- **Backend:** Redis (already configured via `cache.redis`)
- **Key Pattern:** `search_session:{uuid}`
- **TTL:** 24 hours (86400 seconds)
- **Data Structure:** Serialized SearchSession entity

### Endpoint Separation

**POST `/search/properties`** - Session Management

- Creates or updates search session
- Stores filters, returns session UUID
- Does NOT execute search or return property data
- Lightweight, fast response

**GET `/properties`** - Data Fetching (Native JSON:API)

- Requires `searchSessionId` query param
- Loads filters + PIT ID from session
- Executes Elasticsearch query
- Returns paginated property results
- Supports `searchAfter` for pagination
- PIT ID hidden from client (managed server-side)

### Flow Diagram

 P2 --> P3
    end
    
    subgraph GET ["GET /properties?searchSessionId=(uuid)"]
        G1["GET /properties?searchSessionId=(uuid)\n+ optional searchAfter for pagination"]
        G2["SearchSessionManager\n- Load SearchSession from Redis\n- Validate ownership userId match\n- Extract: filters, pageSize, PIT ID"]
        G3["PropertySearchProcessor\n- Execute ES query with stored filters\n- Use stored PIT ID or create if missing\n- Use searchAfter from query param\n- Update session with new PIT ID\n- Return property results JSON:API"]
        
        G1 --> G2 --> G3
    end
    
    POST -.->|Session created| GET`}
/>

## Implementation Details

### 1. SearchSession Entity

**File:** `src/Infrastructure/SearchEngine/Search/SearchSession.php`

```php
> $filters           Serialized filter collection
     * @param null|array                $searchAfter       Current cursor for pagination
     * @param array>    $paginationHistory Stack of previous cursors for back navigation (max 10)
     */
    public function __construct(
        public Uuid $id,
        public string $userId,              // User who created this session
        public string $searchType,          // e.g., 'property', 'location' - for multi-type support
        public array $filters,              // Extracted filters from request DTO
        public ?array $searchAfter,         // Current cursor for pagination
        public ?string $pitId,              // Elasticsearch PIT ID
        public int $pageSize,               // Results per page
        public array $paginationHistory,    // Stack of previous cursors [null, cursor1, cursor2, ...]
        public bool $hasReachedEnd,         // True if we've navigated to last page
        public \DateTimeImmutable $createdAt,
        public \DateTimeImmutable $expiresAt, // 24h from creation
    ) {}

    /**
     * @param array> $filters
     * @param null|array                $searchAfter
     */
    public static function create(
        string $userId,
        string $searchType,
        array $filters,
        int $pageSize,
        ?array $searchAfter = null,
        ?string $pitId = null,
    ): self {
        $now = new \DateTimeImmutable();

        return new self(
            id: Uuid::v7(),
            userId: $userId,
            searchType: $searchType,
            filters: $filters,
            searchAfter: $searchAfter,
            pitId: $pitId,
            pageSize: $pageSize,
            paginationHistory: [null], // Start with first page (no cursor)
            hasReachedEnd: false,
            createdAt: $now,
            expiresAt: $now->modify('+24 hours'),
        );
    }

    // ... additional methods (withPaginationState, withFilters, etc.)
}
```

### 2. SearchSessionRepository

**File:** `src/Infrastructure/SearchEngine/Search/SearchSessionRepository.php`

```php
buildKey($session->id);
        $ttl = $session->getTtl();

        $item = $this->cache->getItem($key);
        $item->set($this->serialize($session));
        $item->expiresAfter($ttl);

        $this->cache->save($item);
    }

    /**
     * Find a search session by UUID.
     */
    public function find(Uuid $id): ?SearchSession
    {
        $key = $this->buildKey($id);
        $item = $this->cache->getItem($key);

        if (!$item->isHit()) {
            return null;
        }

        $data = $item->get();

        return $this->deserialize($data);
    }

    // ... helper methods (buildKey, serialize, deserialize)
}
```

### 3. SearchSessionManager

**File:** `src/Infrastructure/SearchEngine/Search/SearchSessionManager.php`

```php
repository->save($session);

        return $session;
    }

    /**
     * Get a session by UUID, validating ownership and expiration.
     */
    public function getSession(Uuid $id, string $userId): SearchSession
    {
        $session = $this->repository->find($id);

        if ($session === null) {
            throw new SearchSessionNotFoundException(sprintf(
                'Search session "%s" not found or expired',
                $id->toRfc4122()
            ));
        }

        // ... validation logic (expiration, ownership)

        return $session;
    }

    // ... additional methods (updatePaginationState, updateFilters, deleteSession)
}

```

### 4. PropertyQueryDTO

**File:** `src/Http/Api/Public/DTO/Catalog/Property/PropertyQueryDTO.php`

```php
searchSessionId !== null) {
            return $this->processWithSession($data, $config);
        }

        // Legacy direct search (no session)
        // ...
    }

    /**
     * Process search request using SearchSession from Redis.
     */
    private function processWithSession(PropertyQueryDTO $queryDto, AsSearchable $config): object
    {
        // ... validation

        // Load session from Redis
        $session = $this->sessionManager->getSession(
            Uuid::fromString($queryDto->searchSessionId),
            $userId
        );

        // ... rebuild search request
        
        // Execute search
        $response = $processor->search($searchRequest, $config);

        // ... update session with new pagination state

        return $response;
    }
}
```

### 6. AbstractSearchResponseNormalizer

**File:** `src/Http/Api/Shared/Serializer/Normalizer/AbstractSearchResponseNormalizer.php`

```php
getBaseUrl($context);
        $request = $this->requestStack->getCurrentRequest();
        $searchSessionId = $request?->query->get('searchSessionId');
        
        // ...

        // Build current page URL (self link)
        $selfParams = [];
        if ($searchSessionId !== null) {
            $selfParams['searchSessionId'] = $searchSessionId;
        }
        // ...
        
        // Next link
        if ($hasNextPage && $searchAfter !== null) {
            $nextParams = [];
            if ($searchSessionId !== null) {
                $nextParams['searchSessionId'] = $searchSessionId;
            }
            $nextParams['searchAfter'] = json_encode($searchAfter);

            $response['links']['next'] = $baseUrl.'?'.http_build_query($nextParams);
        }

        return $response;
    }
}
```

### 7. PropertyResource

**File:** `src/Http/Api/Public/Resource/Catalog/PropertyResource.php`

```php
 'string', 'format' => 'uuid'],
                        description: 'Search session UUID from POST /search/properties',
                        example: '01936d8a-1234-7890-abcd-0123456789ab',
                    ),
                    new Parameter(
                        name: 'searchAfter',
                        in: 'query',
                        required: false,
                        schema: ['type' => 'string'],
                        description: 'Elasticsearch cursor for pagination (JSON encoded array)',
                        example: '[1763853914000,20,55834574849]',
                    ),
                ],
                extensionProperties: [
                    OpenApiFactory::API_PLATFORM_TAG => [
                        ApiPlatformTag::WEB_USER->value,
                        ApiPlatformTag::PARTNER_API->value,
                    ],
                ],
            ),
        ),
    ],
)]
#[AsSearchable(
    processor: PropertySearchProcessor::class,
    searchType: 'property',
    defaultPageSize: 10,
    maxPageSize: 100,
)]
final class PropertyResource
{
    // Empty class - serves as API resource marker
}
```

### 8. Configure Services

**File:** `config/services.yaml`


```yaml
services:
  # Search Session services
  App\Infrastructure\SearchEngine\Search\SearchSessionRepository:
    arguments:
      $cache: "@cache.redis"

  App\Infrastructure\SearchEngine\Search\SearchSessionManager:
    autowire: true
    autoconfigure: true
```

---

### 9. Exception Handling

**File:** `src/Http/Api/Shared/EventListener/SearchSessionExceptionListener.php`

Create event listener to handle search session exceptions:

```php
getThrowable();

        if ($exception instanceof SearchSessionNotFoundException) {
            $response = new JsonResponse([
                'errors' => [[
                    'status' => '404',
                    'title' => 'Search Session Not Found',
                    'detail' => $exception->getMessage(),
                ]],
            ], 404);

            $event->setResponse($response);
        } elseif ($exception instanceof SearchSessionAccessDeniedException) {
            $response = new JsonResponse([
                'errors' => [[
                    'status' => '403',
                    'title' => 'Access Denied',
                    'detail' => $exception->getMessage(),
                ]],
            ], 403);

            $event->setResponse($response);
        }
    }
}
```

---

## API Usage Examples

### 1. Create Search Session (No Data Returned)

**Request:**

```http
POST /api/search/properties
Content-Type: application/vnd.api+json
Authorization: Bearer {token}

{
  "data": {
    "type": "PropertySearchRequest",
    "attributes": {
      "filters": {
        "transactionType": "SELL",
        "minPrice": 100000,
        "maxPrice": 500000,
        "locationIds": ["uuid1", "uuid2"]
      }
    }
  }
}
```

**Response:**

```json
{
  "data": {
    "type": "PropertySearchSession",
    "id": "01936d8a-1234-7890-abcd-0123456789ab",
    "attributes": {
      "searchSessionId": "01936d8a-1234-7890-abcd-0123456789ab",
      "expiresAt": "2025-12-16T10:30:00Z",
      "filtersApplied": {
        "transactionType": "SELL",
        "minPrice": 100000,
        "maxPrice": 500000,
        "locationIds": ["uuid1", "uuid2"]
      }
    }
  },
  "links": {
    "properties": "https://api.example.com/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab"
  }
}
```

**Key Points:**

- Session created/updated but NO property data returned
- Returns session UUID for subsequent requests
- Includes link to fetch actual data

---

### 2. Fetch Properties Using Session (Native JSON:API)

**Request:**

```http
GET /api/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab
Accept: application/vnd.api+json
Authorization: Bearer {token}
```

**Response:**

```json
{
  "data": [
    {
      "type": "PropertySearchResultDTO",
      "id": "/.well-known/genid/354763aebb3e4d707512",
      "attributes": {
        "uuid": "019b1331-7dce-71b3-8aee-09be1b35d113",
        "listings": [...],
        "createdAt": "2025-12-11T05:12:51+00:00",
        "updatedAt": "2025-12-11T05:12:51+00:00"
      }
    },
    {
      "type": "PropertySearchResultDTO",
      "id": "/.well-known/genid/d7a3f221ae8a241f93dc",
      "attributes": {...}
    }
  ],
  "meta": {
    "totalItems": 156,
    "hasNextPage": true,
    "pagination": {
      "cursor": [1763853914000, 20, 55834574849]
    }
  },
  "links": {
    "self": "https://api.example.com/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab",
    "next": "https://api.example.com/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab&searchAfter=%5B1763853914000%2C20%2C55834574849%5D"
  }
}
```

**Key Points:**

- Filters loaded from session automatically
- PIT ID loaded from session (not in response, not in URL)
- Only `searchAfter` cursor exposed for pagination
- Clean, native JSON:API format

---

### 3. Pagination (Next Page)

**Request:**

```http
GET /api/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab&searchAfter=%5B1763853914000%2C20%2C55834574849%5D
Accept: application/vnd.api+json
Authorization: Bearer {token}
```

**What Happens:**

1. Load session by UUID
2. Extract filters + PIT ID from session
3. Use provided `searchAfter` cursor
4. Execute ES query with stored PIT
5. Return next page of results

**Benefits:**

- PIT ID managed server-side (hidden from client)
- Client only tracks cursor position
- Consistent results across pagination

---

### 4. Update Search Session Filters

**Request:**

```http
POST /api/search/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab
Content-Type: application/vnd.api+json
Authorization: Bearer {token}

{
  "data": {
    "type": "PropertySearchRequest",
    "attributes": {
      "filters": {
        "transactionType": "RENT",  // Changed filter
        "minPrice": 500,
        "maxPrice": 2000
      }
    }
  }
}
```

**Response:**

```json
{
  "data": {
    "type": "PropertySearchSession",
    "id": "01936d8a-1234-7890-abcd-0123456789ab",
    "attributes": {
      "searchSessionId": "01936d8a-1234-7890-abcd-0123456789ab",
      "expiresAt": "2025-12-16T10:30:00Z",
      "filtersApplied": {
        "transactionType": "RENT",
        "minPrice": 500,
        "maxPrice": 2000
      }
    }
  },
  "links": {
    "properties": "https://api.example.com/properties?searchSessionId=01936d8a-1234-7890-abcd-0123456789ab"
  }
}
```

**Key Points:**

- Updates existing session with new filters
- Resets pagination (clears PIT, cursor)
- Same session ID, new search context
- Use returned link to fetch updated results

---

## Benefits

### 1. **Shareable Search URLs**

- Users can share: `?searchSessionId=...`
- No need to pass complex filter objects in URL
- Clean, short URLs

### 2. **Reduced Request Size**

- After initial POST, only session ID needed
- Especially beneficial for complex filters with many parameters
- Faster requests, lower bandwidth

### 3. **Persistent Pagination State**

- PIT ID stored server-side
- Consistent results across pagination requests
- Client doesn't need to manage PIT lifecycle

### 4. **User-Scoped Security**

- Each session tied to user ID
- Prevents unauthorized access to other users' searches
- Automatic cleanup after 24h

### 5. **Search History/Analytics**

- Can log session creation for analytics
- Track popular search patterns
- User search history (if needed)

---

## Testing Checklist

- [ ] Unit tests for `SearchSession` value object
- [ ] Unit tests for `SearchSessionRepository` (with mock cache)
- [ ] Unit tests for `SearchSessionManager`
- [ ] Integration test: Create session → Load session → Validate ownership
- [ ] Integration test: Session expiration handling
- [ ] Integration test: POST with filters → GET with session ID → Verify same results
- [ ] Integration test: Update session filters → Verify pagination reset
- [ ] Functional test: Full flow with PropertySearchResource
- [ ] Test exception handling (not found, access denied)
- [ ] Load test: Redis performance with concurrent sessions

---

## Migration Strategy

### Phase 1: Implement (Current Branch)

- Add all new classes
- Update SearchStateProcessor
- Keep backward compatibility (session ID optional)

### Phase 2: Update Clients

- Frontend updates to use session ID
- Mobile app updates
- Documentation

### Phase 3: Monitor & Optimize

- Monitor Redis memory usage
- Adjust TTL if needed
- Add metrics for session usage

---

## Migration Strategy

### Phase 1: Implement (Current Branch)

- Add all new classes
- Update SearchStateProcessor
- Keep backward compatibility (session ID optional)

### Phase 2: Update Clients

- Frontend updates to use session ID
- Mobile app updates
- Documentation

### Phase 3: Monitor & Optimize

- Monitor Redis memory usage
- Adjust TTL if needed
- Add metrics for session usage

---

## Future Enhancements

1. **Named Searches**
   - Allow users to save searches with custom names
   - Store permanently in DB instead of Redis
   - Link to SearchSession for temporary state

2. **Session Analytics**
   - Track session creation/usage
   - Popular filter combinations
   - Search-to-result conversion rates

3. **Cross-Device Sync**
   - Share sessions across user's devices
   - Persist in DB with longer TTL

4. **Search Suggestions**
   - Analyze stored sessions for autocomplete
   - Trending searches

---

## Redis Memory Estimation

**Assumptions:**

- 10,000 active sessions (concurrent users)
- Average session size: 2 KB (filters + metadata)
- Total: ~20 MB

**Monitoring:**

```bash
# Check Redis memory usage
redis-cli INFO memory

# List all search sessions
redis-cli KEYS "search_session:*"

# Get session count
redis-cli KEYS "search_session:*" | wc -l

# Get TTL for specific session
redis-cli TTL "search_session:01936d8a-1234-7890-abcd-0123456789ab"
```

---

## Summary

This implementation provides a robust, scalable solution for persisting search state server-side while maintaining security, performance, and developer ergonomics. The architecture is extensible to other search types (locations, listings, etc.) through the abstract `searchType` field.

[nop1984]

Same for next file (but sometimes it opens)

---
title: Autocomplete
description: Implementation of autocomplete for locations and properties.
icon: Search
---

# 🔍 Autocomplete / Elasticsearch

This document describes the autocomplete infrastructure built on top of Elasticsearch. It covers the architecture, implementation details for the Location autocomplete, and a guide to extend the pattern to new entities.

---

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Location Autocomplete Implementation](#location-autocomplete-implementation)
4. [How to Add Autocomplete for a New Entity](#how-to-add-autocomplete-for-a-new-entity)
5. [API Reference](#api-reference)
6. [Configuration](#configuration)
7. [Testing](#testing)

---

## Overview

The autocomplete system provides fast, typo-tolerant search suggestions for entities indexed in Elasticsearch. It is designed with:

- **Extensibility**: Add autocomplete to any entity using the `#[AsAutocomplete]` attribute
- **API Platform Integration**: Exposes endpoints via API Platform's StateProvider pattern
- **Type Safety**: Uses DTOs for both documents and responses
- **Fuzzy Search**: Built-in typo tolerance with configurable fuzziness
- **Boosting**: Prioritize certain types or fields in search results
- **CRUD Sync**: Automatic index updates via Doctrine lifecycle events

### Key Features

| Feature                   | Description                                         |
| ------------------------- | --------------------------------------------------- |
| **Fulltext Search**       | Multi-field search with configurable boosts         |
| **Fuzzy Matching**        | Typo tolerance using Elasticsearch AUTO fuzziness   |
| **Type Filtering**        | Filter results by entity type/subtype               |
| **Limit Control**         | Default and max limits to prevent abuse             |
| **Deterministic Results** | Consistent ordering via score + secondary sort      |
| **Edge N-gram**           | Autocomplete-optimized analyzer for prefix matching |

---

## Architecture

### Component Overview



### Directory Structure

- `src/`
  - `Infrastructure/`
    - `SearchEngine/`
      - `Autocomplete/`
        - `Attribute/`
          - `AsAutocomplete.php` - Core attribute
        - `DTO/`
          - `LocationSuggestionDTO.php` - Response DTO
        - `Processor/`
          - `AbstractAutocompleteProcessor.php`
          - `LocationAutocompleteProcessor.php`
        - `Resource/`
          - `LocationAutocompleteResource.php` - API endpoint
        - `State/`
          - `AutocompleteStateProvider.php` - API Platform provider
      - `Document/`
        - `Location/`
          - `V1/`
            - `LocationDocument.php` - Index DTO
            - `LocationMapping.php` - ES mapping
      - `Index/`
        - `LocationIndexer.php` - Entity indexer
        - `LocationIndexNameResolver.php` - Index naming
      - `Subscriber/`
        - `LocationIndexationSubscriber.php`
  - `Domain/`
    - `Location/`
      - `Event/`
        - `LocationReadyForIndexationEvent.php`
      - `Subscriber/`
        - `LocationLifecycleSubscriber.php`

---

## Location Autocomplete Implementation

### 1. Index Document (`LocationDocument`)

Defines the structure of data stored in Elasticsearch:

```php
#[AsSearchDocument(
    name: 'location',
    version: 1,
    indexNameResolverClass: LocationIndexNameResolver::class,
)]
final readonly class LocationDocument
{
    public function __construct(
        public string $id,
        public string $name,
        public ?string $type,
        public ?string $parentName,
        public ?string $regionName,
        public ?string $countryCode,
        /** @var string[] */
        public array $postalCodes,
        public ?int $population,
        public ?string $uniqCode,
    ) {}
}
```

### 2. Index Mapping (`LocationMapping`)

Defines the Elasticsearch mapping with autocomplete analyzer:

```php
#[AsSearchMapping(documentClass: LocationDocument::class)]
final class LocationMapping
{
    public static function getMapping(): array
    {
        return [
            'settings' => [
                'analysis' => [
                    'analyzer' => [
                        'autocomplete' => [
                            'type' => 'custom',
                            'tokenizer' => 'standard',
                            'filter' => ['lowercase', 'autocomplete_filter'],
                        ],
                        'autocomplete_search' => [
                            'type' => 'custom',
                            'tokenizer' => 'standard',
                            'filter' => ['lowercase'],
                        ],
                    ],
                    'filter' => [
                        'autocomplete_filter' => [
                            'type' => 'edge_ngram',
                            'min_gram' => 1,
                            'max_gram' => 20,
                        ],
                    ],
                ],
            ],
            'mappings' => [
                'properties' => [
                    'id' => ['type' => 'keyword'],
                    'name' => [
                        'type' => 'text',
                        'analyzer' => 'autocomplete',
                        'search_analyzer' => 'autocomplete_search',
                    ],
                    'type' => ['type' => 'keyword'],
                    'postal_codes' => [
                        'type' => 'text',
                        'analyzer' => 'autocomplete',
                        'search_analyzer' => 'autocomplete_search',
                    ],
                    'population' => ['type' => 'integer'],
                    // ... other fields
                ],
            ],
        ];
    }
}
```

### 3. API Resource (`LocationAutocompleteResource`)

Defines the API endpoint using the `#[AsAutocomplete]` attribute:

```php
#[AsAutocomplete(
    processor: LocationAutocompleteProcessor::class,
    filters: ['type' => 'type'],      // ?type=CITY
    fulltext: ['name^3', 'postal_codes^2'],  // Boosted fields
    fuzzy: ['name'],                   // Typo-tolerant fields
    defaultLimit: 30,
    maxLimit: 30,
)]
#[ApiResource(
    shortName: 'LocationAutocomplete',
    operations: [
        new GetCollection(
            uriTemplate: '/autocomplete/locations',
            provider: AutocompleteStateProvider::class,
        ),
    ],
    output: LocationSuggestionDTO::class,
)]
final class LocationAutocompleteResource {}
```

### 4. Processor (`LocationAutocompleteProcessor`)

Implements entity-specific search logic:

```php
final class LocationAutocompleteProcessor extends AbstractAutocompleteProcessor
{
    // CITY type gets highest boost for prioritization
    public function getBoosts(): array
    {
        return [
            'type' => [
                'CITY' => 5.0,
                'DEPARTMENT' => 2.0,
                'REGION' => 1.5,
            ],
        ];
    }

    // Secondary sort by population for deterministic results
    public function getSort(): array
    {
        return [
            ['_score' => ['order' => 'desc']],
            ['population' => ['order' => 'desc', 'missing' => '_last']],
        ];
    }

    // Transform ES hit to response DTO
    protected function mapHit(array $hit): LocationSuggestionDTO
    {
        $source = $hit['_source'];
        return new LocationSuggestionDTO(
            id: $source['id'],
            name: $source['name'],
            type: $source['type'] ?? null,
            parentName: $source['parent_name'] ?? null,
            regionName: $source['region_name'] ?? null,
            countryCode: $source['country_code'] ?? null,
            postalCode: $source['postal_codes'][0] ?? null,
            metadata: ['uniqCode' => $source['uniq_code'] ?? null],
        );
    }
}
```

### 5. CRUD Events

Doctrine lifecycle events trigger automatic index updates:

```php
// Domain Layer: Doctrine subscriber dispatches domain event
class LocationLifecycleSubscriber implements EventSubscriber
{
    #[PostPersist]
    #[PostUpdate]
    public function onLocationChange(AdministrativeDivision $location): void
    {
        $this->eventDispatcher->dispatch(
            new LocationReadyForIndexationEvent($location, IndexOperation::INDEX)
        );
    }

    #[PostRemove]
    public function onLocationRemove(AdministrativeDivision $location): void
    {
        $this->eventDispatcher->dispatch(
            new LocationReadyForIndexationEvent($location, IndexOperation::DELETE)
        );
    }
}

// Infrastructure Layer: Event subscriber handles indexation
class LocationIndexationSubscriber implements EventSubscriberInterface
{
    public function onLocationReadyForIndexation(LocationReadyForIndexationEvent $event): void
    {
        match ($event->operation) {
            IndexOperation::INDEX => $this->indexer->index($event->location, 1),
            IndexOperation::DELETE => $this->indexer->delete($event->location, 1),
        };
    }
}
```

---

## How to Add Autocomplete for a New Entity

Follow these steps to add autocomplete functionality to a new entity (e.g., `Agency`).

### Step 1: Create Index Document

```php
// src/Infrastructure/SearchEngine/Document/Agency/V1/AgencyDocument.php

namespace App\Infrastructure\SearchEngine\Document\Agency\V1;

use App\Infrastructure\SearchEngine\Attribute\AsSearchDocument;

#[AsSearchDocument(
    name: 'agency',
    version: 1,
    indexNameResolverClass: AgencyIndexNameResolver::class,
)]
final readonly class AgencyDocument
{
    public function __construct(
        public string $id,
        public string $name,
        public ?string $city,
        public ?string $countryCode,
        public ?string $siret,
    ) {}
}
```

### Step 2: Create Index Mapping

```php
// src/Infrastructure/SearchEngine/Document/Agency/V1/AgencyMapping.php

namespace App\Infrastructure\SearchEngine\Document\Agency\V1;

use App\Infrastructure\SearchEngine\Attribute\AsSearchMapping;

#[AsSearchMapping(documentClass: AgencyDocument::class)]
final class AgencyMapping
{
    public static function getMapping(): array
    {
        return [
            'settings' => [
                'analysis' => [
                    'analyzer' => [
                        'autocomplete' => [
                            'type' => 'custom',
                            'tokenizer' => 'standard',
                            'filter' => ['lowercase', 'autocomplete_filter'],
                        ],
                        'autocomplete_search' => [
                            'type' => 'custom',
                            'tokenizer' => 'standard',
                            'filter' => ['lowercase'],
                        ],
                    ],
                    'filter' => [
                        'autocomplete_filter' => [
                            'type' => 'edge_ngram',
                            'min_gram' => 1,
                            'max_gram' => 20,
                        ],
                    ],
                ],
            ],
            'mappings' => [
                'properties' => [
                    'id' => ['type' => 'keyword'],
                    'name' => [
                        'type' => 'text',
                        'analyzer' => 'autocomplete',
                        'search_analyzer' => 'autocomplete_search',
                    ],
                    'city' => ['type' => 'keyword'],
                    'country_code' => ['type' => 'keyword'],
                    'siret' => ['type' => 'keyword'],
                ],
            ],
        ];
    }
}
```

### Step 3: Create Index Name Resolver

```php
// src/Infrastructure/SearchEngine/Index/AgencyIndexNameResolver.php

namespace App\Infrastructure\SearchEngine\Index;

final readonly class AgencyIndexNameResolver implements IndexNameResolverInterface
{
    public function __construct(
        private string $envPrefix,
    ) {}

    public function buildIndexName(int $version, ?\DateTimeInterface $date = null): string
    {
        return sprintf('%sagency_v%d', $this->envPrefix, $version);
    }

    public function buildAliasName(): string
    {
        return sprintf('%sagencies_read', $this->envPrefix);
    }
}
```

### Step 4: Create Entity Indexer

```php
// src/Infrastructure/SearchEngine/Index/AgencyIndexer.php

namespace App\Infrastructure\SearchEngine\Index;

use App\Domain\Agency\Entity\Agency;
use App\Infrastructure\SearchEngine\Document\Agency\V1\AgencyDocument;

final class AgencyIndexer extends AbstractEntityIndexer
{
    protected function createDocument(object $entity, int $version): object
    {
        assert($entity instanceof Agency);

        return new AgencyDocument(
            id: (string) $entity->getId(),
            name: $entity->getName(),
            city: $entity->getCity(),
            countryCode: $entity->getCountryCode()?->value,
            siret: $entity->getSiret(),
        );
    }
}
```

### Step 5: Create Response DTO

```php
// src/Infrastructure/SearchEngine/Autocomplete/DTO/AgencySuggestionDTO.php

namespace App\Infrastructure\SearchEngine\Autocomplete\DTO;

final readonly class AgencySuggestionDTO
{
    public function __construct(
        public string $id,
        public string $name,
        public ?string $city = null,
        public ?string $countryCode = null,
    ) {}
}
```

### Step 6: Create Processor

```php
// src/Infrastructure/SearchEngine/Autocomplete/Processor/AgencyAutocompleteProcessor.php

namespace App\Infrastructure\SearchEngine\Autocomplete\Processor;

use App\Infrastructure\SearchEngine\Autocomplete\DTO\AgencySuggestionDTO;
use App\Infrastructure\SearchEngine\Index\AgencyIndexNameResolver;

final class AgencyAutocompleteProcessor extends AbstractAutocompleteProcessor
{
    public function __construct(
        private AgencyIndexNameResolver $indexNameResolver,
    ) {}

    public function getIndexName(): string
    {
        return $this->indexNameResolver->buildAliasName();
    }

    public function getBoosts(): array
    {
        return []; // No type boosting needed
    }

    public function getSort(): array
    {
        return [
            ['_score' => ['order' => 'desc']],
            ['name.keyword' => ['order' => 'asc']], // Alphabetical secondary sort
        ];
    }

    protected function mapHit(array $hit): AgencySuggestionDTO
    {
        $source = $hit['_source'];
        return new AgencySuggestionDTO(
            id: $source['id'],
            name: $source['name'],
            city: $source['city'] ?? null,
            countryCode: $source['country_code'] ?? null,
        );
    }
}
```

### Step 7: Create API Resource

```php
// src/Infrastructure/SearchEngine/Autocomplete/Resource/AgencyAutocompleteResource.php

namespace App\Infrastructure\SearchEngine\Autocomplete\Resource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use App\Infrastructure\SearchEngine\Autocomplete\Attribute\AsAutocomplete;
use App\Infrastructure\SearchEngine\Autocomplete\DTO\AgencySuggestionDTO;
use App\Infrastructure\SearchEngine\Autocomplete\Processor\AgencyAutocompleteProcessor;
use App\Infrastructure\SearchEngine\Autocomplete\State\AutocompleteStateProvider;

#[AsAutocomplete(
    processor: AgencyAutocompleteProcessor::class,
    filters: ['country' => 'country_code'],
    fulltext: ['name^3', 'siret'],
    fuzzy: ['name'],
    defaultLimit: 10,
    maxLimit: 30,
)]
#[ApiResource(
    shortName: 'AgencyAutocomplete',
    operations: [
        new GetCollection(
            uriTemplate: '/autocomplete/agencies',
            provider: AutocompleteStateProvider::class,
        ),
    ],
    output: AgencySuggestionDTO::class,
)]
final class AgencyAutocompleteResource {}
```

### Step 8: Create Domain Event and Subscribers

```php
// src/Domain/Agency/Event/AgencyReadyForIndexationEvent.php
final readonly class AgencyReadyForIndexationEvent
{
    public function __construct(
        public Agency $agency,
        public IndexOperation $operation,
    ) {}
}

// src/Domain/Agency/Subscriber/AgencyLifecycleSubscriber.php
#[AsDoctrineListener(event: Events::postPersist)]
#[AsDoctrineListener(event: Events::postUpdate)]
#[AsDoctrineListener(event: Events::postRemove)]
final readonly class AgencyLifecycleSubscriber
{
    public function __construct(
        private EventDispatcherInterface $eventDispatcher,
    ) {}

    public function postPersist(PostPersistEventArgs $args): void
    {
        $this->handleChange($args->getObject(), IndexOperation::INDEX);
    }

    public function postUpdate(PostUpdateEventArgs $args): void
    {
        $this->handleChange($args->getObject(), IndexOperation::INDEX);
    }

    public function postRemove(PostRemoveEventArgs $args): void
    {
        $this->handleChange($args->getObject(), IndexOperation::DELETE);
    }

    private function handleChange(object $entity, IndexOperation $operation): void
    {
        if (!$entity instanceof Agency) {
            return;
        }
        $this->eventDispatcher->dispatch(
            new AgencyReadyForIndexationEvent($entity, $operation)
        );
    }
}

// src/Infrastructure/SearchEngine/Subscriber/AgencyIndexationSubscriber.php
final readonly class AgencyIndexationSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private EntityIndexerInterface $agencyIndexer,
    ) {}

    public static function getSubscribedEvents(): array
    {
        return [AgencyReadyForIndexationEvent::class => 'onAgencyReadyForIndexation'];
    }

    public function onAgencyReadyForIndexation(AgencyReadyForIndexationEvent $event): void
    {
        match ($event->operation) {
            IndexOperation::INDEX => $this->agencyIndexer->index($event->agency, 1),
            IndexOperation::DELETE => $this->agencyIndexer->delete($event->agency, 1),
        };
    }
}
```

### Step 9: Register Services

Add to `config/infrastructure/search.yaml`:

```yaml
services:
  # Index Name Resolver
  App\Infrastructure\SearchEngine\Index\AgencyIndexNameResolver:
    arguments:
      $envPrefix: "%env(INDEX_PREFIX)%"

  # Indexer
  App\Infrastructure\SearchEngine\Index\AgencyIndexer:
    arguments:
      $client: '@Elastic\Elasticsearch\Client'
      $indexNameResolver: '@App\Infrastructure\SearchEngine\Index\AgencyIndexNameResolver'

  # Processor (tagged for auto-discovery)
  App\Infrastructure\SearchEngine\Autocomplete\Processor\AgencyAutocompleteProcessor:
    tags:
      - { name: "app.autocomplete_processor" }

  # Indexation Subscriber
  App\Infrastructure\SearchEngine\Subscriber\AgencyIndexationSubscriber:
    arguments:
      $agencyIndexer: '@App\Infrastructure\SearchEngine\Index\AgencyIndexer'
```

### Step 10: Initialize Index

```bash
# Create the index
bin/console app:search-engine:init agency --version=1

# Or manually via ES API
curl -X PUT "localhost:9200/agency_v1" -H 'Content-Type: application/json' -d @agency_mapping.json
```

### Step 11: Test the Endpoint

```bash
# Basic search
curl "http://localhost/autocomplete/agencies?q=immo"

# With filter
curl "http://localhost/autocomplete/agencies?q=paris&country=FR"

# With limit
curl "http://localhost/autocomplete/agencies?q=century&limit=5"
```

---

## API Reference

### Endpoint: `/autocomplete/locations`

| Method | URL                                 | Description      |
| ------ | ----------------------------------- | ---------------- |
| GET    | `/autocomplete/locations?q={query}` | Search locations |

#### Query Parameters

| Parameter | Type   | Required | Default | Description                         |
| --------- | ------ | -------- | ------- | ----------------------------------- |
| `q`       | string | ✅       | -       | Search query (min 1 char)           |
| `type`    | string | ❌       | -       | Filter by type (CITY, REGION, etc.) |
| `limit`   | int    | ❌       | 30      | Max results (capped at 30)          |

#### Response

```json
{
  "@context": "/contexts/LocationAutocomplete",
  "@id": "/autocomplete/locations",
  "@type": "Collection",
  "totalItems": 3,
  "member": [
    {
      "id": "123",
      "name": "Paris",
      "type": "CITY",
      "parentName": "Paris",
      "regionName": "Île-de-France",
      "countryCode": "FR",
      "postalCode": "75001",
      "metadata": {
        "uniqCode": "75056"
      }
    }
  ]
}
```

#### Response Fields

| Field         | Type    | Description                                                      |
| ------------- | ------- | ---------------------------------------------------------------- |
| `id`          | string  | Unique identifier                                                |
| `name`        | string  | Display name                                                     |
| `type`        | string  | Location type (CITY, REGION, DEPARTMENT, DISTRICT, NEIGHBORHOOD) |
| `parentName`  | string? | Parent location name (for disambiguation)                        |
| `regionName`  | string? | Region name                                                      |
| `countryCode` | string? | ISO country code                                                 |
| `postalCode`  | string? | First postal code                                                |
| `metadata`    | object  | Additional data (uniqCode, etc.)                                 |

---

## Configuration

### Environment Variables

```bash
# Elasticsearch connection
ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASS=changeme

# Index prefix (for multi-tenant or test isolation)
INDEX_PREFIX=prod_
```

### Service Configuration

The autocomplete processors are tagged for auto-discovery:

```yaml
# config/infrastructure/search.yaml
services:
  _instanceof:
    App\Infrastructure\SearchEngine\Autocomplete\Processor\AbstractAutocompleteProcessor:
      tags:
        - { name: "app.autocomplete_processor" }

  App\Infrastructure\SearchEngine\Autocomplete\State\AutocompleteStateProvider:
    arguments:
      $processors: !tagged_locator
        tag: "app.autocomplete_processor"
        default_index_method: "getProcessorName"
```

---

## Testing

### Test Categories

| Category    | Directory                                         | Purpose                       |
| ----------- | ------------------------------------------------- | ----------------------------- |
| Unit        | `tests/Infrastructure/SearchEngine/Autocomplete/` | Test DTOs, mapping, attribute |
| Integration | `tests/Integration/SearchEngine/`                 | Test with real Elasticsearch  |
| Functional  | `tests/Http/Api/Public/Autocomplete/`             | Test full HTTP stack          |

### Running Tests

```bash
# All autocomplete tests
bin/phpunit tests/Infrastructure/SearchEngine/Autocomplete

# Integration tests (requires ES)
bin/phpunit tests/Integration/SearchEngine/LocationIndexerIntegrationTest.php
bin/phpunit tests/Integration/SearchEngine/LocationAutocompleteProcessorIntegrationTest.php

# Functional tests (requires ES + JWT)
bin/phpunit tests/Http/Api/Public/Autocomplete/LocationAutocompleteResourceTest.php
```

### Test Environment Setup

```bash
# Configure test prefix
export INDEX_PREFIX=test_

# Generate JWT keys for functional tests
openssl genpkey -out config/jwt/private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096
openssl rsa -pubout -in config/jwt/private.pem -out config/jwt/public.pem
```

### Example Test

```php
public function testSearchWithTypoTolerance(): void
{
    $client = $this->createApiClientWithUser(UserStory::PARTNER_API_USER);

    // "Marsille" instead of "Marseille"
    $response = $client->request('GET', '/autocomplete/locations?q=marsille');

    $this->assertResponseIsSuccessful();
    $data = $response->toArray();

    $this->assertNotEmpty($data['member']);
    $this->assertSame('Marseille', $data['member'][0]['name']);
}
```

---

## Troubleshooting

### Common Issues

**1. Empty results despite indexed data**

- Check index alias: `GET /_alias/locations_read`
- Refresh index: `POST /location_v1/_refresh`
- Verify mapping has autocomplete analyzer

**2. Typo tolerance not working**

- Ensure `fuzzy` parameter is set in `#[AsAutocomplete]`
- Check minimum query length (fuzzy requires 3+ chars)

**3. CITY not prioritized**

- Verify `getBoosts()` returns correct values
- Check that `type` field is indexed as `keyword`

**4. Index not updating on entity changes**

- Verify Doctrine listener is registered
- Check event subscriber is wired correctly
- Look for errors in `var/log/dev.log`

### Debug Commands

```bash
# Check index mapping
curl "localhost:9200/location_v1/_mapping?pretty"

# Check index documents
curl "localhost:9200/location_v1/_search?pretty&size=5"

# Test analyzer
curl -X POST "localhost:9200/location_v1/_analyze?pretty" \
  -H 'Content-Type: application/json' \
  -d '{"analyzer": "autocomplete", "text": "Paris"}'

# Check service wiring
bin/console debug:container | grep -i autocomplete
```