scaffold-feature

name	scaffold-feature
description	Scaffold a full vertical slice for a new domain feature in LogisticsX - entity, EF configuration, migration, command/query handlers, controller, DTO/mapper, Angular page, and feature-map row. Use when the user asks to add a new top-level feature (e.g., "add a Subcontractor entity with CRUD"). Outputs an ordered checklist tailored to the LogisticsX folder structure.

Scaffold a Feature (Vertical Slice)

Adds a new top-level feature end-to-end. Run through the steps in order - earlier steps gate later ones (e.g., the migration depends on the entity + EF config).

Decide first

Before writing any code:

1. Master DB or tenant DB? Master = platform-level data shared across tenants (Tenant, Subscription, BlogPost). Tenant = per-company operational data (Load, Trip, Customer). Most new features are tenant-scoped.
2. Which module? Application code lives under Logistics.Application/Modules/{Module}/{Feature}/. Pick by bounded context: Operations (dispatching, fleet), Compliance (ELD, DVIR, safety, privacy), Financial (invoices, payments, payroll, tax), IdentityAccess (users, tenants, subscriptions), Integrations (AI dispatch, load board, webhooks), Platform (stats, marketing, notifications). See module-layout.md.
3. Aggregate root or child entity? A new aggregate gets its own folder under Entities/{Feature}/. A child entity belongs to an existing aggregate's folder.
4. Is it auditable? Almost always yes - inherit AuditableEntity. Use Entity only for very simple lookup tables.
5. Which marker interface? IMasterEntity (master DB) or ITenantEntity (tenant DB). The DbContext picks up the entity automatically based on this - no manual DbSet<T> needed.

Step-by-step

1. Domain entity

src/Core/Logistics.Domain/Entities/{Feature}/{Entity}.cs

using Logistics.Domain.Core;

namespace Logistics.Domain.Entities;

public class Subcontractor : AuditableEntity, ITenantEntity
{
    public required string Name { get; set; }
    public string? ContactEmail { get; set; }
    public SubcontractorStatus Status { get; set; } = SubcontractorStatus.Active;
    // value objects: Address, Money, etc.
}

If status enum needed: src/Core/Logistics.Domain.Primitives/Enums/{Feature}/{Status}.cs. Use GetDescription() for display - [Description] only when humanization isn't enough (acronyms, special formatting).

2. EF configuration

src/Infrastructure/Logistics.Infrastructure.Persistence/Configurations/{Feature}/{Entity}EntityConfiguration.cs

internal sealed class SubcontractorEntityConfiguration : IEntityTypeConfiguration<Subcontractor>
{
    public void Configure(EntityTypeBuilder<Subcontractor> builder)
    {
        builder.ToTable("subcontractors");
        builder.HasKey(s => s.Id);
        builder.Property(s => s.Name).HasMaxLength(200).IsRequired();
        builder.Property(s => s.Status).HasConversion<string>();
        // builder.ComplexProperty(s => s.Address); for value objects
    }
}

Complex types cannot participate in a unique index. If the entity needs uniqueness spanning a value-object member, EF can't express it - enforce it in code on every write path (see IftaTaxRateUniqueness.FindConflictAsync) and give the value object a normalizing factory like TaxJurisdiction.Create so casing or an empty-vs-null member can't defeat the comparison.

The MasterDbContext / TenantDbContext discover configurations via ApplyConfigurationsFromAssembly - you don't need to register them.

3. Migration

Use the migration-creator skill or run:

# Tenant
dotnet ef migrations add Add{Entity} \
  --project src/Infrastructure/Logistics.Infrastructure.Persistence \
  --context TenantDbContext \
  -o Migrations/Tenant

Name it for what it does (AddSubcontractor) - EF prefixes the timestamp, so no Version_NNNN, numeric suffix, or date. Inspect the generated SQL before committing.

4. Reads (inline .Query() first)

Default to an inline .Query() inside the query handler - do not create a Specification<T> class for a one-off read. Only add a dedicated spec (src/Core/Logistics.Domain/Specifications/{Feature}/) when the same condition is genuinely reused across handlers; there are just a few left in the codebase (FilterLoadInvoices, FilterPayrollInvoices, FilterLoadsByDeliveryDate).

5. Commands and queries

Commands and queries are the request contract - bind them directly as the request body (flat properties), no *Dto wrapper. Add a dedicated *Request record only when the wire shape must differ from the command.

src/Core/Logistics.Application/Modules/{Module}/{Feature}/Commands/:

• Create{Entity}/Create{Entity}Command.cs - flat-property command : ICommand (or ICommand<Result<T>> if the client needs data back)
• Create{Entity}/Create{Entity}Handler.cs - internal sealed class, primary-constructor DI
• Create{Entity}/Create{Entity}Validator.cs - FluentValidation (see validator rules below)
• Same pattern for Update{Entity}/, Delete{Entity}/

Don't hand-write trivial handlers. Delete/GetById/Update slices subclass the generic base handlers in src/Core/Logistics.Application/Handlers/ - DeleteTenantEntityHandler, DeleteMasterEntityHandler, GetTenantEntityByIdHandler, UpdateTenantEntityHandler. Only write a bespoke handler when there's real logic.

Validators. Skip the validator entirely when its only rule would be Id NotEmpty (the handler's not-found path covers it). For a Create/Update pair sharing ≥3 rules, put the shared rules in a base validator both subclass (see Ifta TaxRates).

src/Core/Logistics.Application/Modules/{Module}/{Feature}/Queries/:

• Get{Entity}ById/Get{Entity}ByIdQuery.cs + handler - : IQuery<Result<{Entity}Dto>> (Get{Entity}ByIdQuery can subclass the base handler)
• Get{Entities}/Get{Entities}Query.cs + handler - paged list

A command targets the master or tenant DB purely by which unit of work its handler injects (IMasterUnitOfWork vs ITenantUnitOfWork) - there is no separate marker interface. Handlers own their own SaveChangesAsync calls - there is no auto-transaction wrapper.

6. DTOs and Mapperly mapper

src/Shared/Logistics.Shared.Models/{Entity}Dto.cs for the public DTO.

src/Core/Logistics.Mappings/{Entity}Mapper.cs:

[Mapper]
public static partial class SubcontractorMapper
{
    [MapperIgnoreSource(nameof(Subcontractor.Loads))]  // ignore navigation properties
    public static partial SubcontractorDto ToDto(this Subcontractor entity);
}

Never write manual mapping in handlers.

7. Controller

src/Presentation/Logistics.API/Controllers/{Entity}Controller.cs

[Route("subcontractors")]
[Produces("application/json")]
[Authorize]
public class SubcontractorController(IMediator mediator) : ControllerBase
{
    [HttpGet]
    [Authorize(Policy = Permission.Subcontractors.View)]
    [ProducesResponseType<PagedResponse<SubcontractorDto>>(200)]
    public async Task<IActionResult> GetList([FromQuery] GetSubcontractorsQuery query, CancellationToken ct)
        => Ok(await mediator.Send(query, ct));

    // GET {id}, POST, PUT {id}, DELETE {id}
}

REST conventions:

• Plural lowercase nouns (/subcontractors, not /subcontractor)
• Path params for IDs
• Custom actions as sub-resources (POST /subcontractors/{id}/archive)
• Sort syntax: OrderBy=-CreatedAt (NOT "CreatedAt desc")

8. Permissions

Add Subcontractors.View and Subcontractors.Manage to the Permission constants (use the add-permission skill - src/Shared/Logistics.Shared.Identity/Policies/, plus the hand-mirrored projects/shared/src/lib/models/permissions.ts). Wire to TenantRole claims via the seeder or admin UI.

9. Tests

test/Logistics.Application.Tests/Commands/{Feature}/Create{Entity}HandlerTests.cs - xUnit + NSubstitute. Field name sut.

See .claude/rules/backend/testing.md for the mock-setup pattern.

10. Frontend

Angular API regen first

cd src/Client/Logistics.Angular
bun run gen:api:live   # regenerates from running API

This produces typed clients in projects/shared/src/lib/api/generated/. Update the barrel (models.ts) if a new DTO needs to be exported.

Page

src/Client/Logistics.Angular/projects/tms-portal/src/app/pages/subcontractors/:

• subcontractors.ts (list page) + .html template
• subcontractor-edit.ts (form) + .html
• subcontractor-store.ts if state is non-trivial (@ngrx/signals)

Conventions: standalone components, signals (signal(), computed()), input()/output() (not decorators), native control flow (@if, @for), <ui-form-field> for inputs.

Routing

Add a route entry in the portal's app.routes.ts. Add a sidebar menu entry if user-facing.

HTTP cache

Default cache TTL is 2 min. If the feature gets real-time updates via SignalR, add a ttl: 0 rule in projects/shared/src/lib/api/cache.config.ts before the catch-all.

11. Update feature-map.md

Add a row under the appropriate domain section in .claude/feature-map.md:

| Subcontractors | `Entities/Subcontractor.cs` | `Modules/Operations/Subcontractors/Commands/`, `Modules/Operations/Subcontractors/Queries/` | - | `SubcontractorController.cs`, `tms-portal/pages/subcontractors/` |

Verification checklist

• Entity inherits AuditableEntity/Entity and implements IMasterEntity/ITenantEntity
• EF configuration created (auto-discovered by DbContext)
• Migration generated and inspected
• Commands + queries + validators + handlers created (handlers internal sealed)
• DTO + Mapperly mapper, no manual mapping
• Controller with [Authorize(Policy = ...)] on each action
• Permissions added
• Unit tests for handlers
• Angular API client regenerated
• Angular page + route added
• Cache rule added if real-time
• Row added to .claude/feature-map.md
• dotnet build passes
• bun run lint passes
• Feature reachable end-to-end in the running app

Common mistakes

• Missing [Authorize(Policy = ...)] - controller falls back to default auth, leaks data across tenants.
• Regenerating the Angular client but not committing the models.ts barrel - breaks the build.
• Skipping the feature-map row - the feature becomes invisible to future sessions.

Related skills

• migration-creator - the EF migration in step 3
• add-permission - step 8
• add-angular-page - step 10, if the page needs nav/role wiring
• add-dispatch-tool - if the feature should be agent-callable

Related rules

• .claude/rules/backend/csharp-conventions.md
• .claude/rules/backend/api-design.md
• .claude/rules/backend/mapperly.md
• .claude/rules/backend/testing.md
• .claude/rules/code-quality.md
• .claude/rules/frontend/angular-conventions.md