3.2.1 Define catalogue and descriptor domain types

[leynos]

Per docs/backend-roadmap.md formulate a plan for the following implementation activity:

3. Data platform foundation

Ensure schema and ingestion work expose their operations through domain ports, so persistence details stay confined to outbound adapters.

3.2. Catalogue and descriptor read models

• 3.2.1. Define catalogue and descriptor domain types (RouteSummary, RouteCategory, Theme, RouteCollection, TrendingRouteHighlight, CommunityPick, Tag, Badge, SafetyToggle, and SafetyPreset) with localization maps and semantic icon identifiers.

Ensure that the new feature is validated with unit tests (using rstest) and behavioural tests (using rstest-bdd), covering happy and unhappy paths and any relevant edge cases. Use pg-embedded-setup-unpriv to enable local testing with Postgres.

Record any design decisions taken in the backend architecture document.

Please ensure that make check-fmt, make lint, and make test all succeed.

See docs/wildside-backend-architecture.md, docs/rust-testing-with-rstest-fixtures.md, docs/rust-doctest-dry-guide.md, docs/complexity-antipatterns-and-refactoring-strategies.md, docs/pg-embed-setup-unpriv-users-guide.md and docs/rstest-bdd-users-guide.md

On completion of this feature, mark the relevant entry in the roadmap as "done".

[traycerai]

Plan

Implementation Plan: Define Catalogue and Descriptor Domain Types

Observations

The codebase follows a hexagonal architecture with clear separation between domain types (in file:backend/src/domain/) and port ingestion types (in file:backend/src/domain/ports/). Existing ingestion types (RouteCategoryIngestion, ThemeIngestion, etc.) are defined in file:backend/src/domain/ports/catalogue_ingestion_repository.rs and file:backend/src/domain/ports/descriptor_ingestion_repository.rs for write operations. The domain layer currently lacks corresponding read model types with proper validation, immutability, and localization support. The schema baseline migration in file:backend/migrations/2026-02-06-012424_schema_baseline_catalogue_descriptor_user_state/up.sql defines the database tables with JSONB columns for localizations and image metadata. The existing domain types (User, UserPreferences) demonstrate the pattern: validated constructors, builder patterns, serde support, comprehensive doctests, and unit tests using rstest.

Approach

Define pure domain types for catalogue and descriptor read models in new modules under file:backend/src/domain/, following the established patterns for validation, immutability, and localization. Each type will have a validated constructor, builder pattern where appropriate, serde serialization/deserialization, and comprehensive documentation with doctests. Localization maps will be represented as HashMap<String, String> (locale → text) with validation to ensure non-empty keys and values. Semantic icon identifiers will be validated string types (e.g., IconKey) to prevent empty or malformed values. The types will be distinct from ingestion types to maintain separation between write (ingestion) and read (API) concerns, aligning with CQRS principles. Unit tests will use rstest for parameterized testing, and behavioral tests will use rstest-bdd with embedded PostgreSQL via pg-embedded-setup-unpriv. Design decisions will be documented in file:docs/wildside-backend-architecture.md, and the roadmap entry will be marked complete.

Implementation Steps

1. Create Shared Localization and Icon Types

File: file:backend/src/domain/localization.rs

Define LocalizationMap as a validated wrapper around HashMap<String, String> with:

• Constructor validating non-empty locale keys (e.g., "en", "es", "ja")
• Constructor validating non-empty localized text values
• Serde support for JSON serialization/deserialization
• Helper methods: get(&str) -> Option<&str>, insert(String, String) -> Result<(), ValidationError>, is_empty() -> bool
• Validation error enum: LocalizationValidationError with variants EmptyLocale, EmptyText, InvalidLocaleFormat
• Doctests demonstrating valid and invalid usage
• Unit tests using rstest covering edge cases (empty maps, whitespace-only values, locale format validation)

File: file:backend/src/domain/icon_key.rs

Define IconKey as a validated string wrapper with:

• Constructor validating non-empty, trimmed strings
• Pattern validation (alphanumeric, hyphens, underscores only)
• Serde support with try_from and into conversions
• Validation error enum: IconKeyValidationError with variants Empty, InvalidCharacters
• Doctests showing valid icon keys (e.g., "route-hiking", "badge_achievement")
• Unit tests using rstest with parameterized cases for valid/invalid patterns

2. Define Catalogue Domain Types

File: file:backend/src/domain/catalogue/route_category.rs

Define RouteCategory with fields:

• id: Uuid
• slug: String (validated, lowercase, hyphenated)
• icon_key: IconKey
• localizations: LocalizationMap (name, description per locale)
• route_count: u32

Include:

• Validated constructor new(id, slug, icon_key, localizations, route_count) -> Result<Self, ValidationError>
• Builder pattern RouteCategoryBuilder for incremental construction
• Serde support with #[serde(rename_all = "camelCase")]
• Slug validation (non-empty, lowercase, alphanumeric + hyphens)
• Doctests demonstrating construction and serialization
• Unit tests using rstest for validation edge cases

File: file:backend/src/domain/catalogue/theme.rs

Define Theme with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap
• image: ImageMetadata (new type wrapping serde_json::Value with validation)
• walk_count: u32
• distance_range_metres: (u32, u32) (validated min ≤ max)
• rating: f32 (validated 0.0 ≤ rating ≤ 5.0)

Include builder pattern, validation for distance range and rating bounds, doctests, and unit tests.

File: file:backend/src/domain/catalogue/route_summary.rs

Define RouteSummary with fields:

• id: Uuid
• route_id: Uuid
• category_id: Uuid
• theme_id: Uuid
• slug: Option<String> (validated if present)
• localizations: LocalizationMap
• hero_image: ImageMetadata
• distance_metres: u32
• duration_seconds: u32
• rating: f32 (validated 0.0-5.0)
• badge_ids: Vec<Uuid>
• difficulty: Difficulty (enum: Easy, Moderate, Hard)
• interest_theme_ids: Vec<Uuid>
• created_at: DateTime<Utc>

Include Difficulty enum with serde support, builder pattern, validation, doctests, and unit tests.

File: file:backend/src/domain/catalogue/route_collection.rs

Define RouteCollection with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap
• lead_image: ImageMetadata
• map_preview: ImageMetadata
• distance_range_metres: (u32, u32) (validated)
• duration_range_seconds: (u32, u32) (validated)
• difficulty: Difficulty
• route_ids: Vec<Uuid>

Include builder pattern, range validation, doctests, and unit tests.

File: file:backend/src/domain/catalogue/trending_route_highlight.rs

Define TrendingRouteHighlight with fields:

• id: Uuid
• route_summary_id: Uuid
• trend_delta: String (e.g., "+15%", "🔥 Hot")
• subtitle_localizations: LocalizationMap
• highlighted_at: DateTime<Utc>

Include validation, doctests, and unit tests.

File: file:backend/src/domain/catalogue/community_pick.rs

Define CommunityPick with fields:

• id: Uuid
• route_summary_id: Option<Uuid>
• user_id: Option<Uuid>
• localizations: LocalizationMap
• curator_display_name: String (validated, non-empty)
• curator_avatar: ImageMetadata
• rating: f32 (validated 0.0-5.0)
• distance_metres: u32
• duration_seconds: u32
• saves: u32
• picked_at: DateTime<Utc>

Include validation, doctests, and unit tests.

File: file:backend/src/domain/catalogue/mod.rs

Re-export all catalogue types and create module documentation explaining the catalogue read model purpose.

3. Define Descriptor Domain Types

File: file:backend/src/domain/descriptor/tag.rs

Define Tag with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap

Include validation, doctests, and unit tests.

File: file:backend/src/domain/descriptor/badge.rs

Define Badge with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap

Include validation, doctests, and unit tests.

File: file:backend/src/domain/descriptor/safety_toggle.rs

Define SafetyToggle with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap

Include validation, doctests, and unit tests.

File: file:backend/src/domain/descriptor/safety_preset.rs

Define SafetyPreset with fields:

• id: Uuid
• slug: String (validated)
• icon_key: IconKey
• localizations: LocalizationMap
• safety_toggle_ids: Vec<Uuid>

Include validation, doctests, and unit tests.

File: file:backend/src/domain/descriptor/mod.rs

Re-export all descriptor types and create module documentation.

4. Update Domain Module Exports

File: file:backend/src/domain/mod.rs

Add new modules:

pub mod catalogue;
pub mod descriptor;
pub mod icon_key;
pub mod localization;

Export public types in the module documentation and public surface section.

5. Create Shared Image Metadata Type

File: file:backend/src/domain/image_metadata.rs

Define ImageMetadata as a validated wrapper around serde_json::Value with:

• Constructor validating required fields (e.g., "url", "alt")
• Serde support for transparent serialization
• Validation error enum
• Doctests and unit tests

6. Write Unit Tests

File: file:backend/src/domain/catalogue/tests.rs

Create comprehensive unit tests using rstest for:

• Each catalogue type's validation (happy paths, boundary conditions, invalid inputs)
• Builder pattern functionality
• Serde round-trip serialization/deserialization
• Localization map operations
• Icon key validation
• Range validation (distance, duration, rating)
• Difficulty enum parsing

Use #[rstest] with #[case] for parameterized tests covering multiple scenarios.

File: file:backend/src/domain/descriptor/tests.rs

Create unit tests for descriptor types following the same pattern.

File: file:backend/src/domain/localization/tests.rs

Test localization map validation, insertion, retrieval, and edge cases.

File: file:backend/src/domain/icon_key/tests.rs

Test icon key validation with various valid and invalid patterns.

7. Write Behavioral Tests

File: file:backend/tests/catalogue_domain_types_bdd.rs

Create BDD tests using rstest-bdd with scenarios:

• "Constructing a valid RouteCategory"
• "Rejecting invalid slugs"
• "Validating localization maps"
• "Building themes with valid ranges"
• "Rejecting out-of-range ratings"

Use #[given], #[when], #[then] steps with fixtures.

File: file:backend/tests/descriptor_domain_types_bdd.rs

Create BDD tests for descriptor types with similar scenarios.

File: file:backend/tests/features/catalogue_domain_types.feature

Write Gherkin feature file describing catalogue type validation scenarios.

File: file:backend/tests/features/descriptor_domain_types.feature

Write Gherkin feature file for descriptor types.

8. Document Design Decisions

File: file:docs/wildside-backend-architecture.md

Add a new section under "Domain Layer" titled "Catalogue and Descriptor Read Models" documenting:

• Separation between ingestion types (write) and domain types (read)
• Localization strategy using HashMap<String, String>
• Icon key validation approach
• Image metadata structure
• Validation patterns for slugs, ranges, and ratings
• Rationale for using builders vs. direct constructors
• Alignment with CQRS principles (separate read/write models)

Include a Mermaid class diagram showing relationships between catalogue types:

classDiagram
    class RouteSummary {
        +Uuid id
        +Uuid route_id
        +Uuid category_id
        +Uuid theme_id
        +LocalizationMap localizations
        +ImageMetadata hero_image
        +Difficulty difficulty
    }
    class RouteCategory {
        +Uuid id
        +String slug
        +IconKey icon_key
        +LocalizationMap localizations
    }
    class Theme {
        +Uuid id
        +String slug
        +IconKey icon_key
        +LocalizationMap localizations
        +ImageMetadata image
    }
    class RouteCollection {
        +Uuid id
        +Vec~Uuid~ route_ids
        +LocalizationMap localizations
    }
    class TrendingRouteHighlight {
        +Uuid id
        +Uuid route_summary_id
        +LocalizationMap subtitle_localizations
    }
    class CommunityPick {
        +Uuid id
        +Uuid route_summary_id
        +LocalizationMap localizations
    }
    
    RouteSummary --> RouteCategory
    RouteSummary --> Theme
    RouteCollection --> RouteSummary
    TrendingRouteHighlight --> RouteSummary
    CommunityPick --> RouteSummary

Loading

9. Update Roadmap

File: file:docs/backend-roadmap.md

Mark task 3.2.1 as complete by changing:

- [ ] 3.2.1. Define catalogue and descriptor domain types...

to:

- [x] 3.2.1. Define catalogue and descriptor domain types...

10. Verify Quality Gates

Run the following commands and ensure they all pass:

make check-fmt
make lint
make test

Address any formatting issues with cargo fmt, lint warnings with code fixes or #[allow] attributes (with justification comments), and test failures by debugging and fixing the implementation.

Summary

This plan delivers 10 new domain types (RouteCategory, Theme, RouteSummary, RouteCollection, TrendingRouteHighlight, CommunityPick, Tag, Badge, SafetyToggle, SafetyPreset) plus 3 shared types (LocalizationMap, IconKey, ImageMetadata) with comprehensive validation, localization support, and semantic icon identifiers. Each type follows the established patterns in the codebase (validated constructors, builders, serde support, doctests). Unit tests use rstest for parameterized testing, and behavioral tests use rstest-bdd with Gherkin features. The implementation maintains hexagonal architecture boundaries by keeping domain types separate from ingestion types, aligning with CQRS principles. Design decisions are documented in the architecture guide, and the roadmap is updated to reflect completion.

Import In IDE

🤖 Prompt for AI Agents

# Implementation Plan: Define Catalogue and Descriptor Domain Types

## Observations

The codebase follows a hexagonal architecture with clear separation between domain types (in `file:backend/src/domain/`) and port ingestion types (in `file:backend/src/domain/ports/`). Existing ingestion types (`RouteCategoryIngestion`, `ThemeIngestion`, etc.) are defined in `file:backend/src/domain/ports/catalogue_ingestion_repository.rs` and `file:backend/src/domain/ports/descriptor_ingestion_repository.rs` for write operations. The domain layer currently lacks corresponding read model types with proper validation, immutability, and localization support. The schema baseline migration in `file:backend/migrations/2026-02-06-012424_schema_baseline_catalogue_descriptor_user_state/up.sql` defines the database tables with JSONB columns for localizations and image metadata. The existing domain types (`User`, `UserPreferences`) demonstrate the pattern: validated constructors, builder patterns, serde support, comprehensive doctests, and unit tests using `rstest`.

## Approach

Define pure domain types for catalogue and descriptor read models in new modules under `file:backend/src/domain/`, following the established patterns for validation, immutability, and localization. Each type will have a validated constructor, builder pattern where appropriate, serde serialization/deserialization, and comprehensive documentation with doctests. Localization maps will be represented as `HashMap<String, String>` (locale → text) with validation to ensure non-empty keys and values. Semantic icon identifiers will be validated string types (e.g., `IconKey`) to prevent empty or malformed values. The types will be distinct from ingestion types to maintain separation between write (ingestion) and read (API) concerns, aligning with CQRS principles. Unit tests will use `rstest` for parameterized testing, and behavioral tests will use `rstest-bdd` with embedded PostgreSQL via `pg-embedded-setup-unpriv`. Design decisions will be documented in `file:docs/wildside-backend-architecture.md`, and the roadmap entry will be marked complete.

## Implementation Steps

### 1. Create Shared Localization and Icon Types

**File:** `file:backend/src/domain/localization.rs`

Define `LocalizationMap` as a validated wrapper around `HashMap<String, String>` with:
- Constructor validating non-empty locale keys (e.g., "en", "es", "ja")
- Constructor validating non-empty localized text values
- Serde support for JSON serialization/deserialization
- Helper methods: `get(&str) -> Option<&str>`, `insert(String, String) -> Result<(), ValidationError>`, `is_empty() -> bool`
- Validation error enum: `LocalizationValidationError` with variants `EmptyLocale`, `EmptyText`, `InvalidLocaleFormat`
- Doctests demonstrating valid and invalid usage
- Unit tests using `rstest` covering edge cases (empty maps, whitespace-only values, locale format validation)

**File:** `file:backend/src/domain/icon_key.rs`

Define `IconKey` as a validated string wrapper with:
- Constructor validating non-empty, trimmed strings
- Pattern validation (alphanumeric, hyphens, underscores only)
- Serde support with `try_from` and `into` conversions
- Validation error enum: `IconKeyValidationError` with variants `Empty`, `InvalidCharacters`
- Doctests showing valid icon keys (e.g., "route-hiking", "badge_achievement")
- Unit tests using `rstest` with parameterized cases for valid/invalid patterns

### 2. Define Catalogue Domain Types

**File:** `file:backend/src/domain/catalogue/route_category.rs`

Define `RouteCategory` with fields:
- `id: Uuid`
- `slug: String` (validated, lowercase, hyphenated)
- `icon_key: IconKey`
- `localizations: LocalizationMap` (name, description per locale)
- `route_count: u32`

Include:
- Validated constructor `new(id, slug, icon_key, localizations, route_count) -> Result<Self, ValidationError>`
- Builder pattern `RouteCategoryBuilder` for incremental construction
- Serde support with `#[serde(rename_all = "camelCase")]`
- Slug validation (non-empty, lowercase, alphanumeric + hyphens)
- Doctests demonstrating construction and serialization
- Unit tests using `rstest` for validation edge cases

**File:** `file:backend/src/domain/catalogue/theme.rs`

Define `Theme` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`
- `image: ImageMetadata` (new type wrapping `serde_json::Value` with validation)
- `walk_count: u32`
- `distance_range_metres: (u32, u32)` (validated min ≤ max)
- `rating: f32` (validated 0.0 ≤ rating ≤ 5.0)

Include builder pattern, validation for distance range and rating bounds, doctests, and unit tests.

**File:** `file:backend/src/domain/catalogue/route_summary.rs`

Define `RouteSummary` with fields:
- `id: Uuid`
- `route_id: Uuid`
- `category_id: Uuid`
- `theme_id: Uuid`
- `slug: Option<String>` (validated if present)
- `localizations: LocalizationMap`
- `hero_image: ImageMetadata`
- `distance_metres: u32`
- `duration_seconds: u32`
- `rating: f32` (validated 0.0-5.0)
- `badge_ids: Vec<Uuid>`
- `difficulty: Difficulty` (enum: Easy, Moderate, Hard)
- `interest_theme_ids: Vec<Uuid>`
- `created_at: DateTime<Utc>`

Include `Difficulty` enum with serde support, builder pattern, validation, doctests, and unit tests.

**File:** `file:backend/src/domain/catalogue/route_collection.rs`

Define `RouteCollection` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`
- `lead_image: ImageMetadata`
- `map_preview: ImageMetadata`
- `distance_range_metres: (u32, u32)` (validated)
- `duration_range_seconds: (u32, u32)` (validated)
- `difficulty: Difficulty`
- `route_ids: Vec<Uuid>`

Include builder pattern, range validation, doctests, and unit tests.

**File:** `file:backend/src/domain/catalogue/trending_route_highlight.rs`

Define `TrendingRouteHighlight` with fields:
- `id: Uuid`
- `route_summary_id: Uuid`
- `trend_delta: String` (e.g., "+15%", "🔥 Hot")
- `subtitle_localizations: LocalizationMap`
- `highlighted_at: DateTime<Utc>`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/catalogue/community_pick.rs`

Define `CommunityPick` with fields:
- `id: Uuid`
- `route_summary_id: Option<Uuid>`
- `user_id: Option<Uuid>`
- `localizations: LocalizationMap`
- `curator_display_name: String` (validated, non-empty)
- `curator_avatar: ImageMetadata`
- `rating: f32` (validated 0.0-5.0)
- `distance_metres: u32`
- `duration_seconds: u32`
- `saves: u32`
- `picked_at: DateTime<Utc>`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/catalogue/mod.rs`

Re-export all catalogue types and create module documentation explaining the catalogue read model purpose.

### 3. Define Descriptor Domain Types

**File:** `file:backend/src/domain/descriptor/tag.rs`

Define `Tag` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/descriptor/badge.rs`

Define `Badge` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/descriptor/safety_toggle.rs`

Define `SafetyToggle` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/descriptor/safety_preset.rs`

Define `SafetyPreset` with fields:
- `id: Uuid`
- `slug: String` (validated)
- `icon_key: IconKey`
- `localizations: LocalizationMap`
- `safety_toggle_ids: Vec<Uuid>`

Include validation, doctests, and unit tests.

**File:** `file:backend/src/domain/descriptor/mod.rs`

Re-export all descriptor types and create module documentation.

### 4. Update Domain Module Exports

**File:** `file:backend/src/domain/mod.rs`

Add new modules:
```rust
pub mod catalogue;
pub mod descriptor;
pub mod icon_key;
pub mod localization;
```

Export public types in the module documentation and public surface section.

### 5. Create Shared Image Metadata Type

**File:** `file:backend/src/domain/image_metadata.rs`

Define `ImageMetadata` as a validated wrapper around `serde_json::Value` with:
- Constructor validating required fields (e.g., "url", "alt")
- Serde support for transparent serialization
- Validation error enum
- Doctests and unit tests

### 6. Write Unit Tests

**File:** `file:backend/src/domain/catalogue/tests.rs`

Create comprehensive unit tests using `rstest` for:
- Each catalogue type's validation (happy paths, boundary conditions, invalid inputs)
- Builder pattern functionality
- Serde round-trip serialization/deserialization
- Localization map operations
- Icon key validation
- Range validation (distance, duration, rating)
- Difficulty enum parsing

Use `#[rstest]` with `#[case]` for parameterized tests covering multiple scenarios.

**File:** `file:backend/src/domain/descriptor/tests.rs`

Create unit tests for descriptor types following the same pattern.

**File:** `file:backend/src/domain/localization/tests.rs`

Test localization map validation, insertion, retrieval, and edge cases.

**File:** `file:backend/src/domain/icon_key/tests.rs`

Test icon key validation with various valid and invalid patterns.

### 7. Write Behavioral Tests

**File:** `file:backend/tests/catalogue_domain_types_bdd.rs`

Create BDD tests using `rstest-bdd` with scenarios:
- "Constructing a valid RouteCategory"
- "Rejecting invalid slugs"
- "Validating localization maps"
- "Building themes with valid ranges"
- "Rejecting out-of-range ratings"

Use `#[given]`, `#[when]`, `#[then]` steps with fixtures.

**File:** `file:backend/tests/descriptor_domain_types_bdd.rs`

Create BDD tests for descriptor types with similar scenarios.

**File:** `file:backend/tests/features/catalogue_domain_types.feature`

Write Gherkin feature file describing catalogue type validation scenarios.

**File:** `file:backend/tests/features/descriptor_domain_types.feature`

Write Gherkin feature file for descriptor types.

### 8. Document Design Decisions

**File:** `file:docs/wildside-backend-architecture.md`

Add a new section under "Domain Layer" titled "Catalogue and Descriptor Read Models" documenting:
- Separation between ingestion types (write) and domain types (read)
- Localization strategy using `HashMap<String, String>`
- Icon key validation approach
- Image metadata structure
- Validation patterns for slugs, ranges, and ratings
- Rationale for using builders vs. direct constructors
- Alignment with CQRS principles (separate read/write models)

Include a Mermaid class diagram showing relationships between catalogue types:

```mermaid
classDiagram
    class RouteSummary {
        +Uuid id
        +Uuid route_id
        +Uuid category_id
        +Uuid theme_id
        +LocalizationMap localizations
        +ImageMetadata hero_image
        +Difficulty difficulty
    }
    class RouteCategory {
        +Uuid id
        +String slug
        +IconKey icon_key
        +LocalizationMap localizations
    }
    class Theme {
        +Uuid id
        +String slug
        +IconKey icon_key
        +LocalizationMap localizations
        +ImageMetadata image
    }
    class RouteCollection {
        +Uuid id
        +Vec~Uuid~ route_ids
        +LocalizationMap localizations
    }
    class TrendingRouteHighlight {
        +Uuid id
        +Uuid route_summary_id
        +LocalizationMap subtitle_localizations
    }
    class CommunityPick {
        +Uuid id
        +Uuid route_summary_id
        +LocalizationMap localizations
    }
    
    RouteSummary --> RouteCategory
    RouteSummary --> Theme
    RouteCollection --> RouteSummary
    TrendingRouteHighlight --> RouteSummary
    CommunityPick --> RouteSummary
```

### 9. Update Roadmap

**File:** `file:docs/backend-roadmap.md`

Mark task 3.2.1 as complete by changing:
```markdown
- [ ] 3.2.1. Define catalogue and descriptor domain types...
```
to:
```markdown
- [x] 3.2.1. Define catalogue and descriptor domain types...
```

### 10. Verify Quality Gates

Run the following commands and ensure they all pass:

```bash
make check-fmt
make lint
make test
```

Address any formatting issues with `cargo fmt`, lint warnings with code fixes or `#[allow]` attributes (with justification comments), and test failures by debugging and fixing the implementation.

## Summary

This plan delivers 10 new domain types (`RouteCategory`, `Theme`, `RouteSummary`, `RouteCollection`, `TrendingRouteHighlight`, `CommunityPick`, `Tag`, `Badge`, `SafetyToggle`, `SafetyPreset`) plus 3 shared types (`LocalizationMap`, `IconKey`, `ImageMetadata`) with comprehensive validation, localization support, and semantic icon identifiers. Each type follows the established patterns in the codebase (validated constructors, builders, serde support, doctests). Unit tests use `rstest` for parameterized testing, and behavioral tests use `rstest-bdd` with Gherkin features. The implementation maintains hexagonal architecture boundaries by keeping domain types separate from ingestion types, aligning with CQRS principles. Design decisions are documented in the architecture guide, and the roadmap is updated to reflect completion.

---

Execution Information

Branch: main
Commit: 099c143

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[leynos]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Establish foundation types (LocaleCode, LocalizedStringSet, EntityLocalizations, IconKey, ImageMetadata) first, as they are dependencies for all domain types
• Create catalogue and descriptor domain types as validated read models following existing patterns (User, UserPreferences) with constructors that enforce invariants
• Keep domain types as pure data structures without business logic, consistent with existing aggregates like RouteAnnotations
• Validate through both inline unit tests (rstest) and behavioral tests (rstest-bdd) covering valid and invalid inputs

Design Choices

Design Choice 1: Should localization types be validated or accept arbitrary locale codes?

Options Considered:

1. Strict validation against a predefined set of allowed locale codes (enum-like)
2. Flexible string validation with format rules (BCP-47 pattern matching)
3. Accept any non-empty string as a locale code

Chosen Option: 2

Rationale: Use format validation (lowercase letters, optional region code) without restricting to a predefined set, allowing new locales to be added without code changes while preventing obviously invalid values.

Design Choice 2: Should domain types include business logic for locale resolution/fallback?

Options Considered:

1. Pure data structures with no behavior beyond validation
2. Include helper methods for locale resolution and fallback logic
3. Defer locale resolution to a separate domain service

Chosen Option: 1

Rationale: Keep domain types as validated data structures. Locale resolution logic would be a service concern, not a type concern, following the existing pattern where RouteAnnotations is a simple aggregate without business methods.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Foundation Types

Create the shared value types that all catalogue and descriptor domain types will use for localization and icon identification.

Task 1: Create Localization Types Module

Establish typed localization support to replace raw serde_json::Value usage in domain types.

• Create backend/src/domain/localization.rs module for all localization-related types
• Define LocaleCode as a validated newtype wrapping String with BCP-47-style format validation (e.g., "en", "en-GB", "cy")
• Define LocalizedStringSet struct with fields: name: String, short_label: Option<String>, description: Option<String>
• Define EntityLocalizations as a newtype wrapping HashMap<LocaleCode, LocalizedStringSet> with serialization to/from JSONB-compatible format
• Implement TryFrom<serde_json::Value> for EntityLocalizations to enable construction from database JSONB
• Define LocalizationError enum for validation failures following the define_port_error! pattern
• Export types from backend/src/domain/mod.rs

Task 2: Create IconKey Type

Define a validated semantic icon identifier type to replace plain strings.

• Create backend/src/domain/icon_key.rs module
• Define IconKey as a validated newtype wrapping String with format validation (lowercase alphanumeric with hyphens, e.g., "hiking-trail", "historical-site")
• Define IconKeyValidationError enum for invalid format errors
• Implement serde traits with try_from/into pattern for string serialization
• Export from backend/src/domain/mod.rs

Task 3: Create Image Metadata Type

Define a typed structure for image metadata used by themes and route summaries.

• Create backend/src/domain/image_metadata.rs module
• Define ImageMetadata struct with fields matching the JSONB image structure (url, alt_text, attribution, etc.)
• Implement TryFrom<serde_json::Value> for construction from database JSONB
• Export from backend/src/domain/mod.rs

🤖 Prompt for AI agents

Implement foundation types for localization and icon identification that will be
used by all catalogue and descriptor domain types.

**Localization Types (`backend/src/domain/localization.rs`)**:
- Create `LocaleCode` newtype wrapping `String` with BCP-47-style format
validation (lowercase letters, optional region code like "en", "en-GB", "cy")
- Create `LocalizedStringSet` struct with fields: `name: String`, `short_label:
Option<String>`, `description: Option<String>`
- Create `EntityLocalizations` newtype wrapping `HashMap<LocaleCode,
LocalizedStringSet>` with JSONB-compatible serialization
- Implement `TryFrom<serde_json::Value>` for `EntityLocalizations` to construct
from database JSONB
- Define `LocalizationError` enum following the `define_port_error!` pattern for
validation failures

**IconKey Type (`backend/src/domain/icon_key.rs`)**:
- Create `IconKey` newtype wrapping `String` with format validation (lowercase
alphanumeric with hyphens, e.g., "hiking-trail", "historical-site")
- Define `IconKeyValidationError` enum for invalid formats
- Implement serde traits using `try_from`/`into` pattern for string
serialization

**Image Metadata Type (`backend/src/domain/image_metadata.rs`)**:
- Create `ImageMetadata` struct with fields matching JSONB image structure (url,
alt_text, attribution, etc.)
- Implement `TryFrom<serde_json::Value>` for construction from database JSONB

**Module Exports**:
- Export all types from `backend/src/domain/mod.rs`

Phase 2: Catalogue Domain Types

Create read model types for the catalogue entities that represent curated walking content.

Task 1: Create Theme Domain Type

Define the read model for interest themes that categorize walking routes.

• Create backend/src/domain/catalogue/theme.rs
• Define Theme struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations, image: Option<ImageMetadata>, walk_count: u32, distance_range_metres: (i32, i32), rating_range: (f32, f32)
• Provide constructor that validates invariants (e.g., range min <= max)
• Implement Serialize for future API responses

Task 2: Create RouteCategory Domain Type

Define the read model for route categories in the taxonomy.

• Create backend/src/domain/catalogue/route_category.rs
• Define RouteCategory struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations, route_count: u32
• Provide constructor for validated construction

Task 3: Create RouteSummary Domain Type

Define the read model for route preview information shown in listings.

• Create backend/src/domain/catalogue/route_summary.rs
• Define RouteSummary struct with fields: route_id: Uuid, category_id: Uuid, theme_id: Uuid, slug: String, localizations: EntityLocalizations, hero_image: Option<ImageMetadata>, distance_metres: i32, duration_seconds: i32, rating: f32, badge_ids: Vec<Uuid>, difficulty: String, interest_theme_ids: Vec<Uuid>
• Provide constructor for validated construction

Task 4: Create RouteCollection Domain Type

Define the read model for curated route collections.

• Create backend/src/domain/catalogue/route_collection.rs
• Define RouteCollection struct with fields: id: Uuid, slug: String, localizations: EntityLocalizations, image: Option<ImageMetadata>, route_ids: Vec<Uuid>, featured_at: Option<DateTime<Utc>>
• Provide constructor for validated construction

Task 5: Create TrendingRouteHighlight Domain Type

Define the read model for trending route overlay information.

• Create backend/src/domain/catalogue/trending_route_highlight.rs
• Define TrendingRouteHighlight struct with fields: id: Uuid, route_id: Uuid, subtitle_localizations: EntityLocalizations, position: i32
• Provide constructor for validated construction

Task 6: Create CommunityPick Domain Type

Define the read model for community-curated route picks.

• Create backend/src/domain/catalogue/community_pick.rs
• Define CommunityPick struct with fields: id: Uuid, route_id: Uuid, localizations: EntityLocalizations, picked_at: DateTime<Utc>
• Provide constructor for validated construction

Task 7: Create Catalogue Module Structure

Organize all catalogue types under a cohesive module.

• Create backend/src/domain/catalogue/mod.rs to re-export all catalogue types
• Update backend/src/domain/mod.rs to expose the catalogue module

🤖 Prompt for AI agents

Implement read model domain types for catalogue entities representing curated
walking content. All types follow the validated data structure pattern from
existing domain types like `User` and `UserPreferences`.

**Theme (`backend/src/domain/catalogue/theme.rs`)**:
- Define `Theme` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`, `image: Option<ImageMetadata>`,
`walk_count: u32`, `distance_range_metres: (i32, i32)`, `rating_range: (f32,
f32)`
- Provide constructor that validates invariants (range min <= max)
- Implement `Serialize` for API responses

**RouteCategory (`backend/src/domain/catalogue/route_category.rs`)**:
- Define `RouteCategory` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`, `route_count: u32`
- Provide constructor for validated construction

**RouteSummary (`backend/src/domain/catalogue/route_summary.rs`)**:
- Define `RouteSummary` struct with fields: `route_id: Uuid`, `category_id:
Uuid`, `theme_id: Uuid`, `slug: String`, `localizations: EntityLocalizations`,
`hero_image: Option<ImageMetadata>`, `distance_metres: i32`, `duration_seconds:
i32`, `rating: f32`, `badge_ids: Vec<Uuid>`, `difficulty: String`,
`interest_theme_ids: Vec<Uuid>`
- Provide constructor for validated construction

**RouteCollection (`backend/src/domain/catalogue/route_collection.rs`)**:
- Define `RouteCollection` struct with fields: `id: Uuid`, `slug: String`,
`localizations: EntityLocalizations`, `image: Option<ImageMetadata>`,
`route_ids: Vec<Uuid>`, `featured_at: Option<DateTime<Utc>>`
- Provide constructor for validated construction

**TrendingRouteHighlight
(`backend/src/domain/catalogue/trending_route_highlight.rs`)**:
- Define `TrendingRouteHighlight` struct with fields: `id: Uuid`, `route_id:
Uuid`, `subtitle_localizations: EntityLocalizations`, `position: i32`
- Provide constructor for validated construction

**CommunityPick (`backend/src/domain/catalogue/community_pick.rs`)**:
- Define `CommunityPick` struct with fields: `id: Uuid`, `route_id: Uuid`,
`localizations: EntityLocalizations`, `picked_at: DateTime<Utc>`
- Provide constructor for validated construction

**Module Organization**:
- Create `backend/src/domain/catalogue/mod.rs` to re-export all catalogue types
- Update `backend/src/domain/mod.rs` to expose the catalogue module

Phase 3: Descriptor Domain Types

Create read model types for the descriptor registries that provide controlled vocabularies.

Task 1: Create Tag Domain Type

Define the read model for content tags.

• Create backend/src/domain/descriptors/tag.rs
• Define Tag struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations
• Provide constructor for validated construction

Task 2: Create Badge Domain Type

Define the read model for route achievement badges.

• Create backend/src/domain/descriptors/badge.rs
• Define Badge struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations
• Provide constructor for validated construction

Task 3: Create SafetyToggle Domain Type

Define the read model for safety preference toggles.

• Create backend/src/domain/descriptors/safety_toggle.rs
• Define SafetyToggle struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations
• Provide constructor for validated construction

Task 4: Create SafetyPreset Domain Type

Define the read model for predefined safety preset configurations.

• Create backend/src/domain/descriptors/safety_preset.rs
• Define SafetyPreset struct with fields: id: Uuid, slug: String, icon_key: IconKey, localizations: EntityLocalizations, toggle_ids: Vec<Uuid>
• Provide constructor for validated construction

Task 5: Create Descriptors Module Structure

Organize all descriptor types under a cohesive module.

• Create backend/src/domain/descriptors/mod.rs to re-export all descriptor types
• Update backend/src/domain/mod.rs to expose the descriptors module

🤖 Prompt for AI agents

Implement read model domain types for descriptor registries that provide
controlled vocabularies. All types follow the validated data structure pattern.

**Tag (`backend/src/domain/descriptors/tag.rs`)**:
- Define `Tag` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**Badge (`backend/src/domain/descriptors/badge.rs`)**:
- Define `Badge` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**SafetyToggle (`backend/src/domain/descriptors/safety_toggle.rs`)**:
- Define `SafetyToggle` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**SafetyPreset (`backend/src/domain/descriptors/safety_preset.rs`)**:
- Define `SafetyPreset` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`, `toggle_ids:
Vec<Uuid>`
- Provide constructor for validated construction

**Module Organization**:
- Create `backend/src/domain/descriptors/mod.rs` to re-export all descriptor
types
- Update `backend/src/domain/mod.rs` to expose the descriptors module

Phase 4: Testing and Documentation

Validate all domain types with unit and behavioral tests, document design decisions.

Task 1: Unit Tests for Foundation Types

Create rstest-based unit tests for localization and icon validation.

• Create backend/src/domain/localization.rs inline tests module
• Test LocaleCode validation: valid codes (en, en-GB, cy), invalid codes (empty, spaces, numbers-only)
• Test LocalizedStringSet construction and optional field handling
• Test EntityLocalizations construction from valid and invalid JSON
• Create backend/src/domain/icon_key.rs inline tests module
• Test IconKey validation: valid keys (hiking-trail), invalid keys (empty, uppercase, special chars)

Task 2: Unit Tests for Domain Types

Create rstest-based unit tests for catalogue and descriptor types.

• Add inline test modules to each domain type file
• Test constructor validation for each type using fixtures for valid EntityLocalizations and IconKey
• Test serialization round-trips for types that will be exposed via API
• Use rstest #[fixture] for shared test data (sample localizations, icon keys, UUIDs)

Task 3: BDD Tests for Domain Type Validation

Create rstest-bdd behavioral tests for domain type validation scenarios.

• Create backend/tests/features/domain_types.feature with scenarios for localization and icon validation
• Create backend/tests/domain_types_bdd.rs with step definitions
• Define world struct holding test inputs and results
• Cover scenarios: valid localization construction, invalid locale codes rejected, valid icon keys accepted, invalid icon keys rejected

Task 4: Update Architecture Documentation

Record design decisions for the new domain types.

• Update docs/wildside-backend-architecture.md with section on catalogue and descriptor read models
• Document the localization type hierarchy and design rationale
• Document the IconKey validation rules and extensibility approach
• Document the relationship between ingestion types (write path) and domain types (read path)

Task 5: Finalization

Complete remaining housekeeping and verification.

• Update docs/backend-roadmap.md to mark item 3.2.1 as done
• Run make check-fmt and fix any formatting issues
• Run make lint and address any clippy warnings
• Run make test to verify all tests pass

🤖 Prompt for AI agents

Implement comprehensive testing and documentation for all domain types.

**Foundation Types Unit Tests**:
- Add inline tests module to `backend/src/domain/localization.rs`
- Test `LocaleCode` validation with valid codes (en, en-GB, cy) and invalid
codes (empty, spaces, numbers-only)
  - Test `LocalizedStringSet` construction and optional field handling
  - Test `EntityLocalizations` construction from valid and invalid JSON
- Add inline tests module to `backend/src/domain/icon_key.rs`
- Test `IconKey` validation with valid keys (hiking-trail) and invalid keys
(empty, uppercase, special chars)

**Domain Types Unit Tests**:
- Add inline test modules to each catalogue and descriptor type file
- Test constructor validation using rstest `#[fixture]` for shared test data
(sample localizations, icon keys, UUIDs)
- Test serialization round-trips for types exposed via API

**BDD Tests**:
- Create `backend/tests/features/domain_types.feature` with scenarios covering:
  - Valid localization construction
  - Invalid locale codes rejected
  - Valid icon keys accepted
  - Invalid icon keys rejected
- Create `backend/tests/domain_types_bdd.rs` with step definitions and world
struct

**Documentation Updates**:
- Update `docs/wildside-backend-architecture.md`:
  - Add section on catalogue and descriptor read models
  - Document localization type hierarchy and design rationale
  - Document IconKey validation rules and extensibility
- Document relationship between ingestion types (write path) and domain types
(read path)
- Update `docs/backend-roadmap.md` to mark item 3.2.1 as done

**Finalization**:
- Run `make check-fmt` and fix formatting issues
- Run `make lint` and address clippy warnings
- Run `make test` to verify all tests pass

Research

The backend follows hexagonal architecture with domain types in backend/src/domain/, ports in backend/src/domain/ports/, and persistence adapters in backend/src/outbound/persistence/. Database tables for catalogue and descriptor entities already exist with JSONB localization columns. Ingestion types (*Ingestion structs) exist for writing data but use untyped serde_json::Value for localizations and plain String for icon keys. The codebase lacks typed read models for these entities. Domain types follow patterns established by User, UserPreferences, and RouteNote with validated value objects and builder patterns. Testing uses rstest fixtures and rstest-bdd for behavioral tests.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement foundation types for localization and icon identification that will be
used by all catalogue and descriptor domain types.

**Localization Types (`backend/src/domain/localization.rs`)**:
- Create `LocaleCode` newtype wrapping `String` with BCP-47-style format
validation (lowercase letters, optional region code like "en", "en-GB", "cy")
- Create `LocalizedStringSet` struct with fields: `name: String`, `short_label:
Option<String>`, `description: Option<String>`
- Create `EntityLocalizations` newtype wrapping `HashMap<LocaleCode,
LocalizedStringSet>` with JSONB-compatible serialization
- Implement `TryFrom<serde_json::Value>` for `EntityLocalizations` to construct
from database JSONB
- Define `LocalizationError` enum following the `define_port_error!` pattern for
validation failures

**IconKey Type (`backend/src/domain/icon_key.rs`)**:
- Create `IconKey` newtype wrapping `String` with format validation (lowercase
alphanumeric with hyphens, e.g., "hiking-trail", "historical-site")
- Define `IconKeyValidationError` enum for invalid formats
- Implement serde traits using `try_from`/`into` pattern for string
serialization

**Image Metadata Type (`backend/src/domain/image_metadata.rs`)**:
- Create `ImageMetadata` struct with fields matching JSONB image structure (url,
alt_text, attribution, etc.)
- Implement `TryFrom<serde_json::Value>` for construction from database JSONB

**Module Exports**:
- Export all types from `backend/src/domain/mod.rs`
===============================================================================

Task: 2

Implement read model domain types for catalogue entities representing curated
walking content. All types follow the validated data structure pattern from
existing domain types like `User` and `UserPreferences`.

**Theme (`backend/src/domain/catalogue/theme.rs`)**:
- Define `Theme` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`, `image: Option<ImageMetadata>`,
`walk_count: u32`, `distance_range_metres: (i32, i32)`, `rating_range: (f32,
f32)`
- Provide constructor that validates invariants (range min <= max)
- Implement `Serialize` for API responses

**RouteCategory (`backend/src/domain/catalogue/route_category.rs`)**:
- Define `RouteCategory` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`, `route_count: u32`
- Provide constructor for validated construction

**RouteSummary (`backend/src/domain/catalogue/route_summary.rs`)**:
- Define `RouteSummary` struct with fields: `route_id: Uuid`, `category_id:
Uuid`, `theme_id: Uuid`, `slug: String`, `localizations: EntityLocalizations`,
`hero_image: Option<ImageMetadata>`, `distance_metres: i32`, `duration_seconds:
i32`, `rating: f32`, `badge_ids: Vec<Uuid>`, `difficulty: String`,
`interest_theme_ids: Vec<Uuid>`
- Provide constructor for validated construction

**RouteCollection (`backend/src/domain/catalogue/route_collection.rs`)**:
- Define `RouteCollection` struct with fields: `id: Uuid`, `slug: String`,
`localizations: EntityLocalizations`, `image: Option<ImageMetadata>`,
`route_ids: Vec<Uuid>`, `featured_at: Option<DateTime<Utc>>`
- Provide constructor for validated construction

**TrendingRouteHighlight
(`backend/src/domain/catalogue/trending_route_highlight.rs`)**:
- Define `TrendingRouteHighlight` struct with fields: `id: Uuid`, `route_id:
Uuid`, `subtitle_localizations: EntityLocalizations`, `position: i32`
- Provide constructor for validated construction

**CommunityPick (`backend/src/domain/catalogue/community_pick.rs`)**:
- Define `CommunityPick` struct with fields: `id: Uuid`, `route_id: Uuid`,
`localizations: EntityLocalizations`, `picked_at: DateTime<Utc>`
- Provide constructor for validated construction

**Module Organization**:
- Create `backend/src/domain/catalogue/mod.rs` to re-export all catalogue types
- Update `backend/src/domain/mod.rs` to expose the catalogue module
===============================================================================

Task: 3

Implement read model domain types for descriptor registries that provide
controlled vocabularies. All types follow the validated data structure pattern.

**Tag (`backend/src/domain/descriptors/tag.rs`)**:
- Define `Tag` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**Badge (`backend/src/domain/descriptors/badge.rs`)**:
- Define `Badge` struct with fields: `id: Uuid`, `slug: String`, `icon_key:
IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**SafetyToggle (`backend/src/domain/descriptors/safety_toggle.rs`)**:
- Define `SafetyToggle` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`
- Provide constructor for validated construction

**SafetyPreset (`backend/src/domain/descriptors/safety_preset.rs`)**:
- Define `SafetyPreset` struct with fields: `id: Uuid`, `slug: String`,
`icon_key: IconKey`, `localizations: EntityLocalizations`, `toggle_ids:
Vec<Uuid>`
- Provide constructor for validated construction

**Module Organization**:
- Create `backend/src/domain/descriptors/mod.rs` to re-export all descriptor
types
- Update `backend/src/domain/mod.rs` to expose the descriptors module
===============================================================================

Task: 4

Implement comprehensive testing and documentation for all domain types.

**Foundation Types Unit Tests**:
- Add inline tests module to `backend/src/domain/localization.rs`
- Test `LocaleCode` validation with valid codes (en, en-GB, cy) and invalid
codes (empty, spaces, numbers-only)
  - Test `LocalizedStringSet` construction and optional field handling
  - Test `EntityLocalizations` construction from valid and invalid JSON
- Add inline tests module to `backend/src/domain/icon_key.rs`
- Test `IconKey` validation with valid keys (hiking-trail) and invalid keys
(empty, uppercase, special chars)

**Domain Types Unit Tests**:
- Add inline test modules to each catalogue and descriptor type file
- Test constructor validation using rstest `#[fixture]` for shared test data
(sample localizations, icon keys, UUIDs)
- Test serialization round-trips for types exposed via API

**BDD Tests**:
- Create `backend/tests/features/domain_types.feature` with scenarios covering:
  - Valid localization construction
  - Invalid locale codes rejected
  - Valid icon keys accepted
  - Invalid icon keys rejected
- Create `backend/tests/domain_types_bdd.rs` with step definitions and world
struct

**Documentation Updates**:
- Update `docs/wildside-backend-architecture.md`:
  - Add section on catalogue and descriptor read models
  - Document localization type hierarchy and design rationale
  - Document IconKey validation rules and extensibility
- Document relationship between ingestion types (write path) and domain types
(read path)
- Update `docs/backend-roadmap.md` to mark item 3.2.1 as done

**Finalization**:
- Run `make check-fmt` and fix formatting issues
- Run `make lint` and address clippy warnings
- Run `make test` to verify all tests pass

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!