Add Entity

Add Entity

Backend-only slice: Domain → Application → Infrastructure → API → migration. No React UI.

Read first: ~/.cursor/skills/webapp-shared/reference.md

Mirror: Auth backend layout (Domain/Entities, Application/Abstractions, Infrastructure/Persistence, endpoints in Program.cs).

Prerequisites

• Scaffolded app with renamed projects (not literal AppName)
• Compose running or host .NET SDK + Postgres connection

Gather inputs

Checklist

Add-entity progress:
- [ ] 1. Domain entity
- [ ] 2. Application DTOs + I{Entity}Service
- [ ] 3. DbContext + EF configuration
- [ ] 4. Service implementation + DI registration
- [ ] 5. Minimal API endpoints
- [ ] 6. EF migration + apply
- [ ] 7. Unit/integration tests
- [ ] 8. curl smoke test

Step 1: Domain entity

File: backend/src/{App}.Domain/Entities/{Entity}.cs

• No NuGet dependencies beyond BCL
• Match naming/style of RefreshToken.cs
• Add navigation properties only if needed and kept in Infrastructure config

Step 2: Application layer

Files in backend/src/{App}.Application/:

Abstractions/I{Entity}Service.cs
{Entity}/{Entity}Dtos.cs          # CreateRequest, UpdateRequest, Response DTOs
{Entity}/{Entity}Service.cs       # optional if logic stays in Infrastructure

Interface methods should match required operations (e.g. GetAllAsync, CreateAsync).

Step 3: Infrastructure

• AppDbContext.cs: public DbSet<{Entity}> {Entities} => Set<{Entity}>();
• Fluent configuration in Persistence/Configurations/{Entity}Configuration.cs if template uses that pattern
• Implementation: Infrastructure/{Entity}/{Entity}Service.cs
• Register: services.AddScoped<I{Entity}Service, {Entity}Service>() in DependencyInjection.cs

Step 4: API endpoints

Add to Program.cs (same style as /api/auth/*):

• Route prefix: /api/{kebab-plural} e.g. /api/todo-items
• Return typed DTOs; use Results.NotFound(), Results.BadRequest(new { error })
• Apply [Authorize] on endpoints unless public read is requested

Keep endpoints thin — delegate to I{Entity}Service.

Step 5: Migration

cd backend
dotnet ef migrations add Add{Entity} \
  --project src/{App}.Infrastructure \
  --startup-project src/{App}.Api \
  --output-dir Persistence/Migrations

Dev: restart api container (auto-migrate on startup in Development).

Prod: do not rely on startup migrate — use add-migration / deploy-webapp apply steps.

Step 6: Tests

• Domain/Application: unit tests for validation/business rules
• Api.Tests: integration test with Testcontainers — create + read via HTTP

Mirror patterns in AppName.Api.Tests auth tests.

Step 7: Smoke (curl)

# Login first, save access token
TOKEN="..."
curl -sf http://localhost:8080/api/{kebab-plural} \
  -H "Authorization: Bearer $TOKEN"

curl -sf -X POST http://localhost:8080/api/{kebab-plural} \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Offer next step

Tell the user:

Backend entity is ready. Run /add-page to add the React UI, or /add-feature if you also want tests and full slice polish.

Do not

• Add React files in this skill
• Reference Infrastructure from Application
• Skip migration after DbContext changes
• Auto-migrate in Production

Related skills

• Full slice with UI → add-feature
• Frontend only → add-page
• Migration troubleshooting → add-migration