# Entity-to-Domain File Mapping

> **Used by:** step-01-transform (section 6: Map Entity to Domain File)
> **Purpose:** Define the 1:1 mapping between BA entities and Domain layer files.

---

## Mapping Rules

Each entity identified during business analysis maps to exactly one file in the Domain layer. The mapping is deterministic based on entity type and module.

### Entity -> Domain Entity File

```
BA: entities.json > entities[].name = "{EntityName}"
    entities.json > entities[].module = "{ModuleCode}"
    metadata.application = "{AppName}"

Domain: src/SmartStack.{AppName}.Domain/{ModuleCode}/Entities/{EntityName}.cs
```

**Example:**
```
BA: entities.json > entities[].name = "Employee"
    module = "Employees"
    application = "HumanResources"

Domain: src/SmartStack.HumanResources.Domain/Employees/Entities/Employee.cs
```

### ValueObject -> Domain ValueObject File

```
BA: entities.json > entities[].valueObjects[].name = "{VOName}"

Domain: src/SmartStack.{AppName}.Domain/{ModuleCode}/ValueObjects/{VOName}.cs
```

**Example:**
```
BA: valueObject.name = "Address"
    module = "Employees"

Domain: src/SmartStack.HumanResources.Domain/Employees/ValueObjects/Address.cs
```

### Enum -> Domain Enum File

```
BA: entities.json > entities[].enums[].name = "{EnumName}"
    OR attributes with type "enum" and enumValues[]

Domain: src/SmartStack.{AppName}.Domain/{ModuleCode}/Enums/{EnumName}.cs
```

**Example:**
```
BA: enum.name = "EmployeeStatus"
    module = "Employees"

Domain: src/SmartStack.HumanResources.Domain/Employees/Enums/EmployeeStatus.cs
```

---

## Path Pattern Summary

| BA Element | Domain File Path |
|------------|-----------------|
| Entity | `src/SmartStack.{App}.Domain/{Module}/Entities/{EntityName}.cs` |
| ValueObject | `src/SmartStack.{App}.Domain/{Module}/ValueObjects/{VOName}.cs` |
| Enum | `src/SmartStack.{App}.Domain/{Module}/Enums/{EnumName}.cs` |
| Domain Exception | `src/SmartStack.{App}.Domain/{Module}/Exceptions/{ExceptionName}.cs` |
| Domain Service | `src/SmartStack.{App}.Domain/{Module}/Services/{ServiceName}.cs` |

---

## Cross-Module Entity References

When an entity in module A references an entity in module B:
- The reference is by ID only (no direct entity dependency across modules)
- Navigation properties use the same `{App}.Domain/{Module}/Entities/` path
- Cross-module FK: `{OtherModuleEntity}Id` property + configuration in Infrastructure layer

---

## Integration with filesToCreate.domain

Each mapped entity becomes an entry in `handoff.filesToCreate.domain[]`:

```json
{
  "path": "src/SmartStack.HumanResources.Domain/Employees/Entities/Employee.cs",
  "type": "Entity",
  "module": "Employees",
  "dependencies": []
}
```

ValueObjects and Enums are also included:

```json
{
  "path": "src/SmartStack.HumanResources.Domain/Employees/ValueObjects/Address.cs",
  "type": "ValueObject",
  "module": "Employees",
  "dependencies": []
},
{
  "path": "src/SmartStack.HumanResources.Domain/Employees/Enums/EmployeeStatus.cs",
  "type": "Enum",
  "module": "Employees",
  "dependencies": []
}
```
