---
name: step-03-roles
description: Generate application roles and role-permission mappings using MCP scaffold_role_permissions (with fallback)
prev_step: steps/step-02-permissions.md
next_step: steps/step-03b-provider.md
---

# Step 3: Application Roles & Role-Permission Mapping

## MANDATORY EXECUTION RULES

- For **client projects** (`seeding_strategy = "provider"`): Generate ApplicationRolesSeedData.cs and module role mappings
- For **core projects** (`seeding_strategy = "hasdata"`): Use RolePermissionConfiguration.cs
- PREFER MCP `scaffold_role_permissions` tool as the primary method
- If MCP is unavailable or the call fails, use the FALLBACK PROCEDURE below
- ALWAYS assign permissions to default roles
- NEVER leave permissions without role assignments
- ALWAYS WRITE generated code to the actual files

## YOUR TASK

For **client projects**:
1. **ApplicationRolesSeedData.cs** (once per application) — defines the 4 application-scoped roles
2. **{Module}RolePermissionSeedData.cs** (per module) — maps permissions to roles by Code

For **core projects**:
1. RolePermissionConfiguration.cs HasData() entries
2. Default role assignments (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser)
3. Application-scoped role assignments (Admin, Manager, Contributor, Viewer)

---

## AVAILABLE STATE

From previous steps:

| Variable | Description |
|----------|-------------|
| `{full_path}` | Complete navigation path (navRoute) |
| `{level}` | application, module, section, or resource |
| `{permission_guids}` | GUIDs for generated permissions |
| `{mcp_available}` | Boolean - MCP connectivity status |
| `{project_type}` | "core" or "client" |
| `{seeding_strategy}` | "hasdata" or "provider" |

---

## EXECUTION SEQUENCE (MCP Primary)

### 1. Determine Default Role Assignments

See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
- Default role mapping table by application prefix
- ApplicationRolesSeedData.cs requirements (once per application)
- {Module}RolePermissionSeedData.cs requirements (per module)

### 2. Call MCP scaffold_role_permissions

```
Tool: mcp__smartstack__scaffold_role_permissions
Args:
  navRoute: "{full_path}"
  roles:
    platformAdmin: ["read", "create", "update", "delete"]  # Adjust based on context
    tenantAdmin: ["read", "create", "update"]              # Adjust based on context
    standardUser: ["read"]                                  # Adjust based on context
  includeWildcard: true
```

### 3. Parse MCP Response

The tool returns:
- RolePermissionConfiguration.cs HasData() entries
- Permission ID variable references
- Role ID variable references

### 4. Write Code to Files

**CRITICAL:** WRITE the generated code to the actual RolePermissionConfiguration.cs file.

### 5. Present Summary

```markdown
## Role-Permission Mappings

| Role | Permissions |
|------|-------------|
| SuperAdmin | `{full_path}.*` (via wildcard) |
| PlatformAdmin | `{full_path}.read`, `.create`, `.update`, `.delete` |
| TenantAdmin | `{full_path}.read`, `.create`, `.update` |
| StandardUser | `{full_path}.read` |
```

### 6. Confirm with User (Optional)

```yaml
questions:
  - header: "Role Access"
    question: "Adjust role permissions for {full_path}?"
    options:
      - label: "Keep defaults (Recommended)"
        description: "PlatformAdmin: CRUD, TenantAdmin: CRU, StandardUser: R"
      - label: "All roles full access"
        description: "All roles get full CRUD access"
      - label: "Custom"
        description: "I'll specify custom permissions"
    multiSelect: false
```

---

## MCP RESPONSE HANDLING

### Success Case

If MCP returns successfully:
- Write RolePermission HasData code to file
- Show role-permission summary table
- Proceed to step-04-backend.md

### Error Case

If MCP call fails or `{mcp_available}` = false:
- Log the error for reference
- Proceed to FALLBACK PROCEDURE below
- Do NOT stop the workflow

---

## CLIENT PROJECT HANDLING

> **Condition:** `{seeding_strategy}` = "provider"

See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
- ApplicationRolesSeedData.cs creation (once per application)
- {Module}RolePermissionSeedData.cs creation (per module)
- Role code naming and GUID generation rules
- Detection of existing ApplicationRolesSeedData.cs

---

## FALLBACK PROCEDURE (When MCP Unavailable)

See [references/roles-fallback-procedure.md](../references/roles-fallback-procedure.md) for the complete 7-step fallback:
- **F1:** Read existing RolePermissionConfiguration.cs to determine state
- **F2:** Read role GUIDs (system-level and application-scoped)
- **F3:** Determine default mappings based on application prefix
- **F4:** Generate RolePermission HasData entries using permission GUIDs
- **F5:** Write code to RolePermissionConfiguration.cs (CRITICAL: WRITE not display)
- **F6:** Present summary
- **F7:** Offer user adjustment option

---

## SUCCESS METRICS

**For client projects:**
- ApplicationRolesSeedData.cs created (once per application)
- {Module}RolePermissionSeedData.cs created with role-permission mappings
- All 4 application roles defined with valid Code values
- Proceeded to step-03b-provider.md

**For core projects:**
- Role-permission mappings generated (via MCP or fallback)
- RolePermissionConfiguration.cs WRITTEN with new entries
- All default roles have appropriate access
- Proceeded to step-04-backend.md

## FAILURE MODES

- Permission GUIDs not available from step-02 (return to step-02)
- Role GUIDs not found in project (ask user, use well-known defaults)
- Invalid navRoute format (return to step-00)

---

## NEXT STEP

After role-permission mappings are generated (via MCP or fallback) and written to files,
proceed to `./step-03b-provider.md`

> **Note:** step-03b will automatically skip if `{seeding_strategy}` = "hasdata" and proceed directly to step-04-backend.
