# Data Model Concept

This is a conceptual model for Codex. It is not a final database schema, but the implementation must preserve these domain relationships.

## Core Concept

A distribution board contains a circuit list.

A circuit list contains sections.

A section contains circuits.

A circuit contains zero, one or multiple device rows.

A device row may be:

- linked to a project device
- manually entered without a linked project device

## ProjectDevice

A project device is a reusable project-specific consumer or consumer group.

A project device can represent:

- one physical device
- a recurring device type
- a consumer group, for example six workstation sockets

User-facing fields:

- `name`
- `displayName`
- `phaseType`
- `connectionKind`
- `costGroup`
- `category`
- `quantity`
- `powerPerUnit`
- `simultaneityFactor`
- `cosPhi`
- `totalPower`
- `remark`

Notes:

- `name` is the technical or product-related name, for example `E-Line Pro`.
- `displayName` is a default display name used when inserting the device into the circuit list.
- After insertion, the circuit list display name is local and not automatically synchronized.
- `quantity` is allowed on project devices because a project device may represent a consumer group.
- Project devices must not define final cable or protection data.

## Circuit

A circuit represents one outgoing circuit / equipment identifier in a distribution board section.

User-facing fields:

- `equipmentIdentifier`
- `section`
- `displayName` optional
- `circuitTotalPower`
- `protectionType`
- `protectionRatedCurrent`
- `protectionCharacteristic`
- `cableType`
- `cableCrossSection`
- `cableLength`
- `rcdAssignment` optional
- `terminalDesignation` optional
- `voltage` optional
- `status` optional
- `isReserve` optional
- `remark` optional

Circuit-level fields only:

- protection type
- protection rated current
- protection characteristic
- cable type
- cable cross-section
- cable length
- RCD assignment
- terminal designation
- circuit total power

Reason:

Protection and cable data are dimensioned for the complete circuit. They depend on the combined load, installation context, cable length, voltage drop and planning rules.

## CircuitDeviceRow

A circuit device row represents a device assigned to a circuit.

User-facing fields:

- `linkedProjectDeviceId` optional
- `name`
- `displayName`
- `phaseType`
- `connectionKind` optional
- `costGroup` optional
- `category` optional
- `level`
- `roomNumber`
- `roomName`
- `quantity`
- `powerPerUnit`
- `simultaneityFactor`
- `cosPhi`
- `rowTotalPower`
- `remark`
- `overriddenFields`

A circuit device row can be manual.

A manual row has no linked project device.

A manual row can later be saved as a project device. After saving, the row becomes linked to the newly created project device.

## Single-Device vs Multi-Device Display

If a circuit has exactly one device row, it is displayed as one compact circuit row.

If a circuit has multiple device rows, it is displayed as:

- one circuit summary row
- indented device rows below it

The circuit summary row shows:

- equipment identifier
- optional circuit display name
- circuit total power
- circuit-level protection data
- circuit-level cable data

The device rows show:

- individual device values
- quantity
- power
- cost group
- category
- room data
- remarks

## Load Calculation

Device row load:

```text
rowTotalPower = quantity × powerPerUnit × simultaneityFactor
```

Circuit total:

```text
circuitTotalPower = sum(rowTotalPower of all device rows assigned to the circuit)
```

`cosPhi` is stored even if it is not visible in the default table view.

Later apparent power calculation:

```text
apparentPower = totalActivePower / cosPhi
```

For circuits with multiple devices, apparent power should be calculated per device row and then summed. This avoids losing information when different devices have different power factors.