# Add Entity

> Adds a backend-only domain entity with EF Core configuration, migration, and minimal API endpoints to a dotnet-vite-webapp-template app without frontend UI. Use when the user invokes /add-entity, asks for a new model/table/API only, or needs schema work before a React page.

- Skill: `manifold-works/add-entity` (Agent Skill)
- Install (CLI): `npx skillmds@latest add manifold-works/add-entity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manifold-works/add-entity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Manifold-Works (https://skillmd.com/u/manifold-works)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/manifold-works/add-entity

---


# Add Entity

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

**Read first:** [`~/.cursor/skills/webapp-shared/reference.md`](../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

| Input | Example |
|-------|---------|
| Entity name | `TodoItem` |
| Fields + types | `Title: string`, `UserId: Guid` |
| API surface | CRUD / read-only / custom |
| Authorization | `[Authorize]` default |

## 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

```bash
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)

```bash
# 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`