# Handoff File Templates (8 Categories)

> **PATH HIERARCHY CONVENTION:** All backend file paths MUST include the application hierarchy.
> - `{ApplicationName}` = `metadata.application` (e.g., `"HumanResources"`)
> - `{ModuleName}` = `metadata.module` (e.g., `"Projects"`)

## 4.1 Domain Files

From `entities.json > entities[]`:

```json
"domain": [
  { "path": "src/Domain/Entities/{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 `usecases.json > useCases[]`:

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

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

**Validator generation rules:**
- Every entity with Create and/or Update use cases MUST have a corresponding Validator
- Validators MUST be registered in DI (`services.AddScoped<IValidator<CreateXxxDto>, CreateXxxValidator>()`)
- Validators MUST be injected into controllers/services that handle POST/PUT operations
- NO TODO/placeholder comments allowed in Validators — all validation rules from business rules (BR-VAL-*) must be implemented

## 4.3 Infrastructure Files

From `entities.json > entities[]`:

```json
"infrastructure": [
  { "path": "src/Infrastructure/Persistence/Configurations/{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

Generated from `usecases.json` + `entities.json`:

```json
"api": [
  { "path": "src/API/Controllers/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}", "isSection": false, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" },
  { "path": "src/API/Controllers/{ApplicationName}/{ModuleName}/{SectionEntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}.{section-kebab}", "isSection": true, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
]
```

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

## 4.5 Frontend Files

From `screens.json > screens[]` and `usecases.json > useCases[]`:

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

```json
"frontend": [
  { "path": "src/pages/{ApplicationName}/{ModuleName}/{PageName}Page.tsx", "type": "Page", "linkedUCs": [], "linkedWireframes": ["{module}-list"], "module": "{moduleCode}", "wireframeAcceptanceCriteria": "Layout MUST match wireframe...", "skill": "/ui-components" },
  { "path": "src/pages/{ApplicationName}/{ModuleName}/{PageName}DetailPage.tsx", "type": "Page", "linkedUCs": [], "linkedWireframes": ["{module}-detail"], "module": "{moduleCode}", "skill": "/ui-components" },
  { "path": "src/pages/{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.5b Notification Files (CONDITIONAL)

> Generated only when `lifeCycles[].transitions[].effects[]` contains entries with `type: "notification"`.

```json
"notifications": [
  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}Notification.cs", "type": "Notification", "linkedUCs": [], "module": "{moduleCode}", "description": "Notification triggered by lifecycle transition" },
  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}NotificationHandler.cs", "type": "NotificationHandler", "linkedUCs": [], "module": "{moduleCode}", "description": "Handler that sends in-app/email notification" }
]
```

**Generation rules:**
- One Notification + Handler pair per unique `notification` effect in lifecycle transitions
- NotificationName derived from transition: `{Entity}{TransitionName}` (e.g., `OrderApproved`)
- Handler must use `INotificationService` for in-app and `IEmailService` for email type
- Notification must include: recipient resolution, template reference, and payload mapping

## 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": "generated from permissions.json + screens.json", "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": "generated from permissions.json + screens.json", "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": "generated from permissions.json + screens.json", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationSectionSeedData.cs", "type": "SeedData", "category": "core", "source": "generated from permissions.json + screens.json", "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": "generated from permissions.json + screens.json", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs", "type": "SeedData", "category": "core", "source": "generated from permissions.json + screens.json", "module": "{moduleCode}" },
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs", "type": "SeedData", "category": "business", "source": "generated from entities.json", "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/{ApplicationName}/{ModuleName}/{Entity}Tests.cs", "type": "UnitTests", "linkedFRs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Unit/Application/{ApplicationName}/{ModuleName}/{ServiceName}ServiceTests.cs", "type": "UnitTests", "linkedFRs": [], "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Integration/{ApplicationName}/{ModuleName}/{ApiControllerName}ControllerTests.cs", "type": "IntegrationTests", "linkedUCs": [], "module": "{moduleCode}" },
  { "path": "src/Tests/Security/{ApplicationName}/{ModuleName}/{ModuleName}SecurityTests.cs", "type": "SecurityTests", "linkedFRs": [], "module": "{moduleCode}" }
]
```

## 4.8 Documentation Files

```json
"documentation": [
  { "path": "src/docs/{ModuleName}/doc-data.ts", "type": "DocData", "module": "{moduleCode}", "description": "Documentation data export for /documentation skill" }
]
```

Include: Technical documentation data, API specification files, user guides.
This category can be an empty array `[]` if no documentation is planned at this stage. It will be populated by the `/documentation` skill after `/business-analyse-develop` completes.

## 4.9 Specification Files (Companion Files)

> **Purpose:** Enable `/apex` and `/business-analyse-develop` to load full BA specifications per layer, avoiding monolithic context loading.

Each PRD MUST include a `specificationFiles` object referencing 5 companion files:

```json
"specificationFiles": {
  "entities": "prd-{moduleCode}.entities.json",
  "rules": "prd-{moduleCode}.rules.json",
  "usecases": "prd-{moduleCode}.usecases.json",
  "screens": "prd-{moduleCode}.screens.json",
  "permissions": "prd-{moduleCode}.permissions.json"
}
```

### Naming Convention

`prd-{moduleCode}.{section}.json` — all files colocated in `.ralph/` alongside the PRD.

| File | Source | Content |
|------|--------|---------|
| `prd-{moduleCode}.entities.json` | `{moduleDir}/entities.json` | VERBATIM copy |
| `prd-{moduleCode}.rules.json` | `{moduleDir}/rules.json` | VERBATIM copy |
| `prd-{moduleCode}.usecases.json` | `{moduleDir}/usecases.json` | VERBATIM copy |
| `prd-{moduleCode}.screens.json` | `{moduleDir}/screens.json` | VERBATIM copy |
| `prd-{moduleCode}.permissions.json` | `{moduleDir}/permissions.json` | VERBATIM copy |

### Rules

- **VERBATIM copy:** Each companion file is a 1:1 copy of the BA source file. Zero transformation, zero filtering.
- **Colocated:** All companion files live in `.ralph/` alongside the PRD file.
- **Mandatory:** All 5 companion files MUST be generated for every module PRD.
- **Layer loading:** `/apex` loads only the companion files needed per layer (see loading plan below).

| Layer | Files loaded | Estimated context |
|-------|-------------|-------------------|
| Layer 0 (domain) | `entities.json` | ~200-400 lines |
| Layer 1 (seed) | `entities.json` + `permissions.json` | ~300-500 lines |
| Layer 2 (backend) | `rules.json` + `usecases.json` | ~300-600 lines |
| Layer 3 (frontend) | `screens.json` + `usecases.json` | ~300-500 lines |
