Skip to content

Simplify Domain Entities and Mapper

Priority: 🟠 HIGH Status: Planning Related QA Analysis: qa-analysis-overview.md

Problem Statement

Two core domain components have excessive complexity:

CoffeeBean Entity

File: Entity/CoffeeBean.php:20

Violations:

  • Class Complexity: 74/60 (23% over threshold)

Impact:

  • Central domain entity - complexity ripples through entire system
  • Frequently modified for new features
  • High risk of regression bugs
  • Difficult to understand business rules

EntityToDtoMapper

File: Service/Api/Mapper/EntityToDtoMapper.php:33

Violations:

  • Class Complexity: 63/60 (5% over threshold)
  • Method Complexity: Line 143 - mapProcessingMethodToDto() CC: 10 (at threshold)

Impact:

  • Core API mapping logic
  • Makes API changes difficult and error-prone
  • Complex mapping suggests entity/DTO misalignment
  • Difficult to test mapping edge cases

Guideline Violations

  • God Objects Anti-pattern: Classes have too many responsibilities
  • SOLID - Single Responsibility Principle: Entities/mappers doing too much
  • Domain-Driven Design: Complex entity suggests missing value objects

Root Cause Analysis

CoffeeBean Entity (74/60 complexity)

Likely causes:

  1. Too many properties managed in single entity
  2. Business logic embedded in entity
  3. Missing value objects for complex concepts
  4. Relationships managed directly in entity
  5. Validation logic in entity

EntityToDtoMapper (63/60 complexity)

Likely causes:

  1. Mapping too many entity types
  2. Complex transformation logic
  3. Conditional mapping based on context
  4. No specialized mappers for complex entities
  5. Business logic in mapping

Proposed Refactoring Strategy

Step 1: Analyze CoffeeBean Entity

  • Document all properties and relationships
  • Identify business logic in entity
  • Find candidates for value objects (e.g., Price, FlavorProfile, Origin)
  • Review validation rules
  • Check for methods that should be in services

Step 2: Extract Value Objects from CoffeeBean

Potential value objects to extract:

  • Price (amount, currency)
  • FlavorProfile (notes, intensity, characteristics)
  • OriginInfo (country, region, farm)
  • RoastProfile (level, date, method)
  • Quality Scores (cupping score, ratings)

Benefits:

  • Encapsulate validation in value objects
  • Improve type safety
  • Reduce entity complexity
  • Better expressiveness

Step 3: Extract Services from CoffeeBean

Move business logic to dedicated services:

  • Validation logic → CoffeeBeanValidator
  • Calculation logic → Domain services
  • Complex queries → Repository patterns

Step 4: Analyze EntityToDtoMapper

  • Document all mapping responsibilities
  • Identify complex mapping methods
  • Find patterns and duplication
  • Check for business logic in mapper

Step 5: Decompose EntityToDtoMapper

Strategies:

  1. Specialized Mappers - One mapper per entity type

    • CoffeeBeanMapper
    • ProcessingMethodMapper (line 143 complexity)
    • RoasterMapper
    • etc.

  2. Mapping Strategy - Strategy pattern for complex mappings

  3. Mapping Helper - Extract common utilities

  4. Keep Facade - EntityToDtoMapper orchestrates specialized mappers

Step 6: Simplify ProcessingMethodToDto Mapping

  • Extract method complexity (line 143, CC: 10)
  • Break into smaller methods
  • Consider dedicated ProcessingMethodMapper

Success Criteria

CoffeeBean Entity

  • Class complexity < 60
  • Value objects extracted for complex concepts
  • Business logic moved to services
  • Entity focuses on state management only
  • Improved testability

EntityToDtoMapper

  • Class complexity < 60
  • All methods have CC < 10
  • Clear separation of concerns
  • Specialized mappers for complex entities
  • Easy to add new entity mappings

General

  • No regression in functionality
  • Improved code readability
  • Better domain model expressiveness
  • Easier to extend

Risk Assessment

High Risk:

  • CoffeeBean is THE core domain entity
  • EntityToDtoMapper affects ALL API responses
  • Changes could break many features

Mitigation:

  • Comprehensive test coverage before refactoring
  • Incremental refactoring (one value object at a time)
  • Extensive integration testing
  • API contract testing
  • Database migration planning (if needed)

Estimated Effort

Medium-High:

  • CoffeeBean analysis: 1 day
  • Value object extraction: 2-3 days (multiple value objects)
  • Service extraction: 1-2 days
  • EntityToDtoMapper decomposition: 2-3 days
  • Testing & verification: 2-3 days
  • Total: 8-12 days

Implementation Order

Phase 1: CoffeeBean Entity

  1. Add comprehensive test coverage
  2. Extract first value object (e.g., Price)
  3. Test thoroughly
  4. Extract remaining value objects incrementally
  5. Move business logic to services

Phase 2: EntityToDtoMapper

  1. Create specialized mapper for ProcessingMethod (most complex)
  2. Create mappers for other entities
  3. Refactor EntityToDtoMapper to use specialized mappers
  4. Verify API responses unchanged

Dependencies

  • H3: Refactor DTO Parameter Lists - Related, consider coordinating
    • CoffeeBeanDTO has 22 parameters likely because CoffeeBean entity is complex
    • Value objects could simplify both entity AND DTO
  • CoffeeBeanDTO excessive parameters (22) likely stems from complex entity
  • Refactoring entity may simplify DTO needs
  • Consider doing these refactorings together

Notes

  • This is fundamental domain model refactoring - impacts entire system
  • Value object extraction is a classic DDD refactoring
  • May uncover business rules not previously explicit
  • Consider domain expert review of value objects
  • Database schema may need updates for value objects (embeddables)
  • This refactoring could improve domain model significantly