# Controller NavRoute and Folder Hierarchy

> Referenced from `steps/step-04-backend.md` — Controller file organization and NavRoute conventions.

---

## Controller File Location

Controllers are organized by **context short name** and **application** (matching SmartStack.app pattern):

```
Api/Controllers/
├── Admin/                     ← platform.administration
│   ├── {Application}/         ← Application sub-folder (e.g., AI/, Communications/, Tenants/)
│   │   └── {EntityName}Controller.cs
│   └── {EntityName}Controller.cs  ← Direct controllers (no application sub-folder)
├── Business/                  ← business.*
│   └── {EntityName}Controller.cs
├── Support/                   ← platform.support
│   └── {EntityName}Controller.cs
├── User/                      ← personal.*
│   └── {EntityName}Controller.cs
└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
```

## Context-to-Folder Mapping

| NavRoute Context | Controller Folder | Example |
|-----------------|-------------------|---------|
| `platform.administration` | `Admin` | `Controllers/Admin/TenantsController.cs` |
| `platform.administration.{app}` | `Admin/{App}` | `Controllers/Admin/AI/AiPromptsController.cs` |
| `platform.support` | `Support` | `Controllers/Support/TicketsController.cs` |
| `business.*` | `Business` | `Controllers/Business/MyTicketsController.cs` |
| `personal.*` | `User` | `Controllers/User/PreferencesController.cs` |

## Controller Attributes

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
- Controller file is in the correct context/application folder
