# Phase 05: Data Model Design

## Entry Gate

```bash
devforgeai-validate phase-check ${SOLARCH_ID} --workflow=solution-architecture --from=04 --to=05 --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Proceed to Phase 05 |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — previous phase not complete |

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Design the solution data model for the epic — the entities (domain objects / persisted records) and the relationships between them. The data model is what the domain-layer and infrastructure-layer components are built around. |
| **REFERENCE** | `.claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json` |
| **STEP COUNT** | 4 mandatory steps |

## Phase Exit Criteria

Before this phase can complete, ALL of the following MUST be true:

- [ ] `data_model.entities` enumerated — each with a `name` and an `attributes` list
- [ ] `data_model.relationships` mapped (or an explicit empty-set record for a single-entity model)
- [ ] Every relationship `from`/`to` resolves to a defined entity
- [ ] Every relationship `cardinality` is one of the 4 enum values

**IF any criterion is unmet: HALT. Do NOT proceed to Phase 06.**

---

## Reference Loading

```
Read(file_path=".claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json")
```

The `data_model` property and the `$defs.entity` / `$defs.relationship` shapes
are exactly what each step below must produce. IF the Read fails: HALT —
"Phase 05 output contract not loaded."

Do NOT rely on memory of previous reads. Load fresh every time this phase executes.

---

## Mandatory Steps

### Step 5.1: Identify the Entities

**EXECUTE:**

From `epic_scope` (Phase 02), the domain-layer `components` (Phase 03), and the
interface contracts' request/response shapes (Phase 04), identify the data
entities this epic needs:

```
entity = {
  name: "<singular noun — the entity name>",
  attributes: [],                # populated in Step 5.2
  description: "<what this entity represents, one sentence>"
}
```

Every persisted record, domain object, or value object the epic operates on is a
candidate entity. A contract `request`/`response` shape that names a structured
object usually implies an entity.

**VERIFY:**
- ≥ 1 entity identified
- Every entity has a unique, singular `name`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=05 --step=5.1 --project-root=. 2>&1
```
```json
{ "phase": "05", "step": "5.1", "entities_identified": [ { "name": "...", "description": "..." } ] }
```

---

### Step 5.2: Define the Attributes

**EXECUTE:**

For each entity, define its attributes as `"<name>: <type>"` strings:

```
entity.attributes = [
  "id: UUID",
  "created_at: timestamp",
  "<field>: <type>",
  ...
]
```

Types should be consistent with the locked tech stack and database from the
System Architecture `tech_stack_rationale` (Phase 01). Every entity needs an
identity attribute. A genuinely unknown attribute set → flag it as an open
question for the handoff rather than inventing fields.

**VERIFY:**
- Every entity has ≥ 1 attribute
- Every entity has an identity / primary-key attribute

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=05 --step=5.2 --project-root=. 2>&1
```
```json
{ "step": "5.2", "entities": [ { "name": "...", "attributes": [ ... ], "description": "..." } ] }
```

---

### Step 5.3: Map the Relationships

**EXECUTE:**

For each pair of related entities, define a relationship:

```
relationship = {
  from: "<entity name>",
  to: "<entity name>",
  cardinality: "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many",
  description: "<what the relationship means>"
}
```

`from` and `to` MUST be names of entities defined in Step 5.1. A single-entity
data model records `relationships: []` explicitly — do not silently omit the key.
A `many-to-many` relationship usually implies a join entity — note whether one is
needed.

**VERIFY:**
- Every `from` / `to` resolves to a defined entity name
- Every `cardinality` is one of the 4 enum values

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=05 --step=5.3 --project-root=. 2>&1
```
```json
{ "step": "5.3", "relationships": [ { "from": "...", "to": "...",
  "cardinality": "...", "description": "..." } ] }
```

---

### Step 5.4: Record the Data Model

**EXECUTE:**
```
Assemble the data_model object:
data_model = { entities: [ ... ], relationships: [ ... ] }
```

**VERIFY:**
- `data_model.entities` is a non-empty array
- `data_model.relationships` is an array (may be empty, never null)

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=05 --step=5.4 --project-root=. 2>&1
```
```json
checkpoint.phases["05"] = {
  "status": "completed",
  "data_model": {
    "entities": [ { "name": "...", "attributes": [ ... ], "description": "..." }, ... ],
    "relationships": [ { "from": "...", "to": "...", "cardinality": "...",
                         "description": "..." }, ... ]
  }
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${SOLARCH_ID} --workflow=solution-architecture --phase=05 --checkpoint-passed --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Phase 05 complete — proceed to next phase |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — checkpoint/step validation failed |

---

## Phase Transition Display

```
Display:
  "Phase 05 Complete: Data Model Design"
  "Entities: {count}  |  Relationships: {count}"
  "Proceeding to Phase 06: Integration Design"
```
