# Handoff File Templates (7 Categories)

> **PATH HIERARCHY CONVENTION:** All backend file paths MUST include the context and application hierarchy.
> - `{ContextPascal}` = PascalCase of `metadata.context` (e.g., `"business"` -> `"Business"`)
> - `{ApplicationName}` = `metadata.application` (e.g., `"HumanResources"`)
> - `{ModuleName}` = `metadata.module` (e.g., `"Projects"`)
>
> **Controller context-to-folder mapping (`{ContextShort}`):**
> | metadata.context | Controller Folder |
> |-----------------|-------------------|
> | `business` | `Business` |
> | `platform` | `Admin` |
> | `personal` | `User` |

## 4.1 Domain Files

From `analysis.entities[]`:

```json
"domain": [
  { "path": "src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}.cs", "type": "Entity", "linkedFRs": [], "linkedUCs": [], "module": "{moduleCode}" }
]
```

Include: Value objects, Enums (`src/Domain/Enums/...`), Domain exceptions (`src/Domain/Exceptions/...`)

## 4.2 Application Files

From `analysis.useCases[]`:

```json
"application": [
  { "path": "src/Application/Services/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}Service.cs", "type": "Service", "linkedFRs": [], "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Application/DTOs/{ContextPascal}/{ApplicationName}/{ModuleName}/{DtoName}Dto.cs", "type": "Dto", "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Application/Validators/{ContextPascal}/{ApplicationName}/{ModuleName}/{ValidatorName}Validator.cs", "type": "Validator", "linkedFRs": [], "module": "{moduleCode}" }
]
```

Include: Service per UC cluster, DTOs for API contracts, Validators (FluentValidation), Query handlers

## 4.3 Infrastructure Files

From `analysis.entities[]`:

```json
"infrastructure": [
  { "path": "src/Infrastructure/Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}Configuration.cs", "type": "EFConfiguration", "linkedFRs": [], "module": "{moduleCode}" }
]
```

Include: EF Core config per entity, DbSet in IExtensionsDbContext, DI registration, Specifications

## 4.4 API Files

From `specification.apiEndpoints[]`:

```json
"api": [
  { "path": "src/API/Controllers/{ContextShort}/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
]
```

Include: One controller per aggregate root, all HTTP methods, error handling

## 4.5 Frontend Files

From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.useCases[]`:

> **WIREFRAME TRACEABILITY:** Every frontend file MUST include `linkedWireframes[]` referencing wireframe `screen` identifiers.

```json
"frontend": [
  { "path": "src/pages/{ContextPascal}/{ApplicationName}/{ModuleName}/{PageName}Page.tsx", "type": "Page", "linkedUCs": [], "linkedWireframes": ["{module}-list"], "module": "{moduleCode}", "wireframeAcceptanceCriteria": "Layout MUST match wireframe...", "skill": "/ui-components" },
  { "path": "src/pages/{ContextPascal}/{ApplicationName}/{ModuleName}/{PageName}DetailPage.tsx", "type": "Page", "linkedUCs": [], "linkedWireframes": ["{module}-detail"], "module": "{moduleCode}", "skill": "/ui-components" },
  { "path": "src/pages/{ContextPascal}/{ApplicationName}/{ModuleName}/{DashboardName}DashboardPage.tsx", "type": "DashboardPage", "linkedUCs": [], "linkedWireframes": ["{module}-dashboard"], "module": "{moduleCode}", "dashboardRef": "{module}-dashboard", "instructions": "Use Recharts library...", "skill": "/ui-components" },
  { "path": "src/components/{ModuleName}/{ComponentName}.tsx", "type": "Component", "linkedUCs": [], "linkedWireframes": [], "module": "{moduleCode}", "skill": "/ui-components" },
  { "path": "src/hooks/use{ModuleName}{Hook}.ts", "type": "Hook", "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/i18n/locales/fr/{moduleLower}.json", "type": "I18n", "language": "fr", "module": "{moduleCode}" },
  { "path": "src/i18n/locales/en/{moduleLower}.json", "type": "I18n", "language": "en", "module": "{moduleCode}" },
  { "path": "src/i18n/locales/it/{moduleLower}.json", "type": "I18n", "language": "it", "module": "{moduleCode}" },
  { "path": "src/i18n/locales/de/{moduleLower}.json", "type": "I18n", "language": "de", "module": "{moduleCode}" }
]
```

**Page generation:** ALL pages and components MUST be generated via `/ui-components` skill (entity lists, grids, tables, dashboards, charts). The `"skill"` field indicates which skill to invoke.

**I18n generation:** 4 JSON files per module (fr, en, it, de) with identical key structures. `{moduleLower}` = lowercase module code. See `smartstack-frontend.md` for JSON template (keys: actions, labels, columns, form, errors, validation, messages, empty).

**Dashboard acceptance criteria:** Chart library (Recharts), chart types matching spec, KPI cards, filters, CSS variables, responsive layout, wireframe-matching positions.

## 4.6 SeedData Files

**OBLIGATORY: 2 app-level CORE + per module CORE (NavigationModule + NavigationSections + Permissions + Roles) + business per module:**

```json
"seedData": [
  { "path": "src/Infrastructure/Persistence/Seeding/Data/NavigationApplicationSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationApplications", "module": "shared", "description": "Application-level navigation seed data. Created ONCE per application (FIRST). Provides ApplicationId for modules and roles." },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.rolePermissions", "module": "shared", "description": "Application-scoped role definitions (admin, manager, contributor, viewer). Created ONCE per application. Provides role entries for SeedRolesAsync()." },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationModuleSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationModules", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationSectionSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationSections", "module": "{moduleCode}", "description": "MANDATORY when sections defined. Seeds section-level navigation entries (list, dashboard, etc.) with full absolute routes." },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/PermissionsSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.permissions", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.rolePermissions", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs", "type": "SeedData", "category": "business", "source": "specification.seedDataBusiness.{module}", "module": "{moduleCode}" }
]
```

**For client projects (ExtensionsDbContext), add MANDATORY infrastructure files:**

```json
[
  { "path": "src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs", "type": "IClientSeedDataProvider", "category": "infrastructure", "description": "Runtime provider that injects core seed data into Core schema" },
  { "path": "src/Infrastructure/Persistence/Seeding/DevDataSeeder.cs", "type": "DevDataSeeder", "category": "infrastructure" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs", "type": "SeedConstants", "category": "infrastructure" }
]
```

**Path convention:** All seed data under `Persistence/Seeding/Data/`. NEVER use `Data/SeedData/`.

## 4.7 Test Files

```json
"tests": [
  { "path": "src/Tests/Unit/Domain/{ContextPascal}/{ApplicationName}/{ModuleName}/{Entity}Tests.cs", "type": "UnitTests", "linkedFRs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Unit/Application/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}ServiceTests.cs", "type": "UnitTests", "linkedFRs": [], "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Integration/{ContextPascal}/{ApplicationName}/{ModuleName}/{ApiControllerName}ControllerTests.cs", "type": "IntegrationTests", "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Security/{ContextPascal}/{ApplicationName}/{ModuleName}/{ModuleName}SecurityTests.cs", "type": "SecurityTests", "linkedFRs": [], "module": "{moduleCode}" }
]
```
