Mappers

Infrastructure Layer — Entity ↔ Domain

Namespace: Infrastructure.Persistence.Mappers File location: Infrastructure/Persistence/Mappers/{Aggregate}Mapper.cs

Method naming

Enum mapping pattern

// Entity → Domain: parse from string
Status = Enum.Parse<ArticleStatus>(entity.Status),

// Nullable enum from entity
Role = entity.Role != null ? Enum.Parse<EventArticleRole>(entity.Role) : null,

// Domain → Entity: serialize to string
Status = domain.Status.ToString(),

// Nullable enum to entity
Role = domain.Role?.ToString(),

Never use int for enum storage. Enums are always stored as strings.

Navigation property pattern

// Required nav property — fallback to empty domain object
RawArticle = entity.RawArticle?.ToDomain() ?? new RawArticle(),

// Collection nav property — may be null if not Include()'d
Articles = entity.Articles?.Select(a => a.ToDomain()).ToList() ?? [],

Use ?? [] (not ?? new List<T>()) for collection fallbacks.

pgvector pattern

// Entity → Domain: unwrap Vector to float[]
Embedding = entity.Embedding?.ToArray(),

// Domain → Entity: wrap float[] in Vector
Embedding = domain.Embedding != null ? new Vector(domain.Embedding) : null,

Extra parameters on ToEntity

When the entity requires context that the domain model doesn't carry, add required/optional parameters after this:

// PublicationMapper — articleId is required context, editorId is optional
public static PublicationEntity ToEntity(this Publication domain, Guid articleId, Guid? editorId = null)

Use optional parameters when a value is sometimes unavailable; add required parameters only when the value is structurally absent from the domain model.

Factory methods

Use a named static factory (not ToDomain) when construction requires multiple source objects:

// ArticleMapper — combines RawArticle + analysis result + external metadata
public static Article FromAnalysisResult(
    RawArticle rawArticle,
    ArticleAnalysisResult analysis,
    string modelVersion) => new() { ... };

Api Layer — Domain → DTO

Namespace: Api.Mappers File location: Api/Mappers/{Aggregate}Mapper.cs

DTO mapping is one-way (Domain → DTO only). No ToEntity or ToDomain methods belong here.

Method naming

Enum pattern (DTOs)

Enums map to string via .ToString(). Nullable enums use null-coalescing:

Sentiment = article.Sentiment.ToString(),
Role = article.Role?.ToString() ?? string.Empty,

Never use Enum.Parse in DTO mappers — DTOs receive string representations.

Overloads vs optional parameters

Use optional parameters when the same method handles a variant that conditionally includes richer data:

// Article detail includes event context when available — same method, optional param
public static ArticleDetailDto ToDetailDto(this Article article, Event? evt = null)
{
    ArticleEventDto? eventDto = evt is null ? null : new ArticleEventDto(
        evt.Id, evt.Title, evt.Status.ToString(),
        article.Role?.ToString() ?? string.Empty
    );

    return new ArticleDetailDto(
        article.Id, article.Title, article.Content, article.Category,
        article.Tags, article.Sentiment.ToString(), article.Language,
        article.Summary, article.ProcessedAt, article.ModelVersion,
        article.RawArticle.ToDto(),
        eventDto
    );
}

Use overloads only when parameter types conflict or the logic diverges significantly — prefer optional params for "same shape, more data" cases.

Sub-object mapping

Sub-objects inside the same aggregate are mapped via their own ToDto extension:

// RawArticleMapper.cs in Api/Mappers/
public static RawArticleDto ToDto(this RawArticle raw) => new(
    raw.Id, raw.Title, raw.OriginalUrl, raw.PublishedAt, raw.Language
);

Keep related sub-mappers in the same file as their parent aggregate mapper.

Collection mapping in controllers

After extracting mappers, controller code becomes:

// Before (inline)
var items = articles.Select(a => new ArticleListItemDto(
    a.Id, a.Title, a.Category, a.Tags,
    a.Sentiment.ToString(), a.Language, a.Summary, a.ProcessedAt
)).ToList();

// After (with mapper)
var items = articles.Select(a => a.ToListItemDto()).ToList();

Example: Extracting Inline Controller Mapping

When a controller constructs DTOs inline, extract them to Api/Mappers/:

1. Create Api/Mappers/{Aggregate}Mapper.cs
2. Add using Api.Mappers; to the controller
3. Replace each new XxxDto(...) block with the appropriate ToXxxDto() call
4. Keep sub-DTO mappers (e.g., RawArticleDto, ArticleEventDto) in the same file

Checklist

Before submitting a new mapper:

• Static class, static extension methods only
• File in correct layer directory
• Correct namespace (Infrastructure.Persistence.Mappers or Api.Mappers)
• Enums use Enum.Parse<T> (load) / .ToString() (save/DTO)
• Navigation properties guarded with ?. and ?? [] / ?? new T()
• pgvector wrapped/unwrapped correctly
• Sub-type mappers co-located in same file as parent aggregate
• No logging, no side effects, no DI