easyplatform-backend

```

[Backend Task]

├── API endpoint?

│ ├── Creates/Updates/Deletes data → CQRS Command (§1)

│ └── Reads data → CQRS Query (§2)

├── Business entity? → Entity Development (§3)

├── Side effects (notifications, emails)? → Entity Event Handler (§4) - NEVER in command handlers!

├── Data transformation/backfill? → Migration (§5)

├── Scheduled/recurring task? → Background Job (§6)

└── Cross-service sync? → Message Bus (§7) - NEVER direct DB access!

```

```

{Service}.Application/

├── UseCaseCommands/{Feature}/Save{Entity}Command.cs # Command+Handler+Result

├── UseCaseQueries/{Feature}/Get{Entity}ListQuery.cs # Query+Handler+Result

├── UseCaseEvents/{Feature}/*EntityEventHandler.cs # Side effects

├── BackgroundJobs/{Feature}/*Job.cs # Scheduled tasks

├── MessageBusProducers/*Producer.cs # Outbound events

├── MessageBusConsumers/{Entity}/*Consumer.cs # Inbound events

└── DataMigrations/*DataMigration.cs # Data migrations

{Service}.Domain/

└── Entities/{Entity}.cs # Domain entities

```

1. Repository: IPlatformQueryableRootRepository -- NEVER throw exceptions for validation
2. Validation: PlatformValidationResult fluent API
3. Side Effects: Entity Event Handlers -- NEVER in command handlers
4. DTO Mapping: DTOs own mapping via PlatformEntityDto.MapToEntity()
5. Cross-Service: Message bus -- NEVER direct database access

---

File: UseCaseCommands/{Feature}/Save{Entity}Command.cs (Command + Result + Handler in ONE file)

```csharp

public sealed class SaveEmployeeCommand : PlatformCqrsCommand

{

public string? Id { get; set; }

public string Name { get; set; } = "";

public override PlatformValidationResult Validate()

=> base.Validate().And(_ => Name.IsNotNullOrEmpty(), "Name required");

}

public sealed class SaveEmployeeCommandResult : PlatformCqrsCommandResult

{

public EmployeeDto Entity { get; set; } = null!;

}

internal sealed class SaveEmployeeCommandHandler :

PlatformCqrsCommandApplicationHandler

{

protected override async Task HandleAsync(

SaveEmployeeCommand req, CancellationToken ct)

{

var entity = req.Id.IsNullOrEmpty()

? req.MapToNewEntity().With(e => e.CreatedBy = RequestContext.UserId())

: await repository.GetByIdAsync(req.Id, ct)

.EnsureFound().Then(e => req.UpdateEntity(e));

await entity.ValidateAsync(repository, ct).EnsureValidAsync();

await repository.CreateOrUpdateAsync(entity, ct);

return new SaveEmployeeCommandResult { Entity = new EmployeeDto(entity) };

}

}

```

⚠️ MUST READ: [references/cqrs-patterns.md](references/cqrs-patterns.md) — full CQRS command patterns

---

File: UseCaseQueries/{Feature}/Get{Entity}ListQuery.cs

```csharp

public sealed class GetEmployeeListQuery : PlatformCqrsPagedQuery

{

public List Statuses { get; set; } = [];

public string? SearchText { get; set; }

}

internal sealed class GetEmployeeListQueryHandler :

PlatformCqrsQueryApplicationHandler

{

protected override async Task HandleAsync(

GetEmployeeListQuery req, CancellationToken ct)

{

var qb = repository.GetQueryBuilder((uow, q) => q

.Where(e => e.CompanyId == RequestContext.CurrentCompanyId())

.WhereIf(req.Statuses.Any(), e => req.Statuses.Contains(e.Status))

.PipeIf(req.SearchText.IsNotNullOrEmpty(), q =>

searchService.Search(q, req.SearchText, Employee.DefaultFullTextSearchColumns())));

var (total, items) = await (

repository.CountAsync((uow, q) => qb(uow, q), ct),

repository.GetAllAsync((uow, q) => qb(uow, q)

.OrderByDescending(e => e.CreatedDate).PageBy(req.SkipCount, req.MaxResultCount), ct)

);

return new GetEmployeeListQueryResult(items.SelectList(e => new EmployeeDto(e)), total, req);

}

}

```

⚠️ MUST READ: [references/cqrs-patterns.md](references/cqrs-patterns.md) — full CQRS query patterns

---

File: {Service}.Domain/Entities/{Entity}.cs

```csharp

[TrackFieldUpdatedDomainEvent]

public sealed class Employee : RootAuditedEntity

{

[TrackFieldUpdatedDomainEvent] public string Name { get; set; } = "";

public string CompanyId { get; set; } = "";

[ComputedEntityProperty]

public string DisplayName { get => $"{Code} - {Name}"; set { } }

public static Expression> OfCompanyExpr(string companyId) => e => e.CompanyId == companyId;

public static Expression> UniqueExpr(string companyId, string code) => e => e.CompanyId == companyId && e.Code == code;

public static Expression>[] DefaultFullTextSearchColumns() => [e => e.Name, e => e.Code];

public async Task ValidateAsync(IRepository repo, CancellationToken ct)

=> await PlatformValidationResult.Valid()

.And(() => Name.IsNotNullOrEmpty(), "Name required")

.AndNotAsync(() => repo.AnyAsync(e => e.Id != Id && e.Code == Code, ct), "Code exists");

}

```

⚠️ MUST READ: [references/entity-patterns.md](references/entity-patterns.md) — full entity patterns

---

CRITICAL: NEVER call side effects in command handlers!

File: UseCaseEvents/{Feature}/Send{Action}On{Event}{Entity}EntityEventHandler.cs

```csharp

internal sealed class SendNotificationOnCreateEmployeeEntityEventHandler

: PlatformCqrsEntityEventApplicationHandler

{

public override async Task HandleWhen(PlatformCqrsEntityEvent @event)

=> !@event.RequestContext.IsSeedingTestingData()

&& @event.CrudAction == PlatformCqrsEntityEventCrudAction.Created;

protected override async Task HandleAsync(PlatformCqrsEntityEvent @event, CancellationToken ct)

=> await notificationService.SendAsync(@event.EntityData.Id);

}

```

⚠️ MUST READ: [references/side-effects-patterns.md](references/side-effects-patterns.md) — side effects patterns

⚠️ MUST READ: [migration-patterns.md](references/migration-patterns.md) | [job-patterns.md](references/job-patterns.md) | [messaging-patterns.md](references/messaging-patterns.md)

---

| Don't | Do |

| --------------------------------- | ----------------------------------------------- |

| throw new ValidationException() | PlatformValidationResult fluent API |

| Side effects in command handler | Entity Event Handler in UseCaseEvents/ |

| Direct cross-service DB access | Message bus |

| DTO mapping in handler | PlatformEntityDto.MapToEntity() |

| Separate Command/Handler files | ONE file: Command + Result + Handler |

| protected bool HandleWhen() | public override async Task HandleWhen() |

• [ ] Service-specific repository, fluent validation (.And(), .AndAsync())
• [ ] No side effects in command handlers, DTO mapping in DTO class
• [ ] Cross-service uses message bus, jobs have maxConcurrent, migrations use dismissSendEvent: true

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed