---
name: step-04-backend
description: Generate backend code using MCP scaffold_extension
prev_step: steps/step-03-roles.md
next_step: steps/step-05-frontend.md
---

# Step 4: Backend Generation

## MANDATORY EXECUTION RULES

- ALWAYS use MCP `scaffold_extension` tool - NEVER use templates
- ALWAYS generate Entity + Service + Controller as a unit
- NEVER skip controller generation - API is required
- YOU ARE AN ORCHESTRATOR calling MCP, not a generator

## YOUR TASK

Call the SmartStack MCP `scaffold_extension` tool with type "feature" to generate:
1. Domain Entity with EF Configuration
2. Application Service (Interface + Implementation)
3. API Controller with NavRoute attribute
4. DTOs (Response, Create, Update)

---

## AVAILABLE STATE

From previous steps:

| Variable | Description |
|----------|-------------|
| `{level}` | context, application, module, or section |
| `{code}` | kebab-case identifier |
| `{full_path}` | Complete navigation path (navRoute) |
| `{labels}` | Object with fr, en, it, de |

---

## EXECUTION SEQUENCE

### 1. Derive Entity Name

Convert `{code}` to PascalCase for entity name:

```
code: "products"        → entityName: "Product"
code: "order-items"     → entityName: "OrderItem"
code: "user-profiles"   → entityName: "UserProfile"
```

### 2. Determine Table Prefix

Based on navigation context:

| Context | Prefix |
|---------|--------|
| platform.administration | `auth_` or `cfg_` |
| platform.support | `support_` |
| business.* | `ref_` or domain-specific |
| personal.* | `usr_` |

### 3. Call MCP scaffold_extension

```
Tool: mcp__smartstack__scaffold_extension
Args:
  type: "feature"
  name: "{entityName}"  # PascalCase
  options:
    navRoute: "{full_path}"
    tablePrefix: "{prefix}"
    schema: "core"
    withDtos: true
    withValidation: true
    withRepository: false  # Use service pattern
    skipComponent: true    # Frontend in next step
    dryRun: false
```

### 4. Parse MCP Response

The tool generates:
- `Domain/{EntityName}.cs` - Entity with BaseEntity
- `Infrastructure/Persistence/Configurations/{EntityName}Configuration.cs` - EF Config
- `Application/Services/I{EntityName}Service.cs` - Interface
- `Application/Services/{EntityName}Service.cs` - Implementation
- `Api/Controllers/{EntityName}Controller.cs` - REST Controller
- `Application/DTOs/{EntityName}Dto.cs` - Response DTO
- `Application/DTOs/Create{EntityName}Dto.cs` - Create request
- `Application/DTOs/Update{EntityName}Dto.cs` - Update request

### 5. Present Output to User

```markdown
## Backend Code Generated

### Domain Layer
- `Domain/{EntityName}.cs`

### Infrastructure Layer
- `Persistence/Configurations/{EntityName}Configuration.cs`

### Application Layer
- `Services/I{EntityName}Service.cs`
- `Services/{EntityName}Service.cs`
- `DTOs/{EntityName}Dto.cs`
- `DTOs/Create{EntityName}Dto.cs`
- `DTOs/Update{EntityName}Dto.cs`

### API Layer
- `Controllers/{EntityName}Controller.cs`
  - NavRoute: `{full_path}`
  - Endpoints:
    - GET /api/{code} - List all
    - GET /api/{code}/{id} - Get by ID
    - POST /api/{code} - Create
    - PUT /api/{code}/{id} - Update
    - DELETE /api/{code}/{id} - Delete

### Next Steps
1. Add DbSet to ICoreDbContext: `public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();`
2. Register service in DI: `services.AddScoped<I{EntityName}Service, {EntityName}Service>();`
3. Run: `dotnet ef migrations add core_vX.X.X_XXX_Add{EntityName}`
```

### 6. Store Entity Info

Store entity information for frontend generation:

```
{entity_name} = "{EntityName}"
{entity_code} = "{code}"
{api_route} = "/api/{code}"
```

---

## CONTROLLER NAVROUTE

The generated controller uses NavRoute attribute:

```csharp
[NavRoute("{full_path}")]
[ApiController]
[Authorize]
public class {EntityName}Controller : ControllerBase
{
    [HttpGet]
    [RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
    public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }

    // ... other CRUD methods
}
```

This ensures:
- API route is derived from navigation path
- Permissions use the constants from Permissions.cs
- Frontend can discover API path from NavRoute registry

---

## MCP RESPONSE HANDLING

### Success Case

If MCP returns successfully:
- Display all generated files
- Show DbSet and DI registration instructions
- Store entity info for frontend
- Proceed to step-05-frontend.md

### Error Case

If MCP call fails:
- Display error message
- Suggest checking entity name format
- Do NOT proceed automatically

---

## SUCCESS METRICS

- MCP scaffold_extension called successfully
- Entity, Service, Controller generated
- DTOs generated
- NavRoute attribute included
- Entity info stored for frontend
- Proceeded to step-05-frontend.md

## FAILURE MODES

- MCP call failed (display error, stop)
- Invalid entity name (must be PascalCase)
- Invalid navRoute format

---

## NEXT STEP

After displaying backend code, proceed to `./step-05-frontend.md`
