# Circuit List Editor Architecture

## Purpose

The circuit-list editor is a circuit-first planning workspace for distribution-board design. It is optimized for spreadsheet-like editing while preserving electrical domain boundaries: circuit-level data stays on circuits, and load rows stay inside circuits.

## Domain Model Overview

- `CircuitSection`
  - Groups circuits by planning section (for example lighting, single-phase, three-phase).
  - Owns section metadata (`key`, `displayName`, `prefix`, ordering).
- `Circuit`
  - Core electrical unit in the list.
  - Owns circuit-level identifiers and technical data:
    - `equipmentIdentifier` (BMK)
    - protection data
    - cable data
    - reserve state
    - circuit-level remark/status
- `CircuitDeviceRow`
  - Load/device line inside a circuit.
  - Owns row-level load and context values:
    - `quantity`
    - `powerPerUnit`
    - `simultaneityFactor`
    - `cosPhi`
    - room snapshots
    - category/cost group and related row attributes
- `ProjectDevice`
  - Reusable device template entity at project level.
  - Can be linked to `CircuitDeviceRow` entries, with copied display values on insert.
- Legacy `Consumer`
  - Old row-first model still present for compatibility/migration.
  - Should not be extended for new circuit-list behavior.

## Why A Circuit Is Not One Row

A circuit can contain zero, one, or many device rows. Treating a circuit as a single row breaks:

- BMK ownership (belongs to circuit, not each device row)
- circuit-level protection/cable fields
- grouped calculations and circuit move/reorder semantics

The tree model keeps circuit identity stable while allowing row-level load composition.

## Rendering Model: Single vs Multi Device

- Single-device circuit:
  - Rendered as compact combined row (`circuitCompact`) for fast editing.
- Multi-device circuit:
  - Rendered as one circuit summary row (`circuitSummary`) plus indented `deviceRow` entries.

This keeps visual density high without losing ownership boundaries.

## Reserve / Empty Circuits

Circuits with no device rows are rendered as reserve rows (`reserveCircuit`).  
Section-level `-frei-` placeholder rows represent insertion targets for creating a new circuit in that section.

## BMK Ownership (`equipmentIdentifier`)

`equipmentIdentifier` / BMK is circuit-owned (`Circuit.equipmentIdentifier`).

- Device rows do not have their own BMK.
- Existing identifiers must stay stable unless explicitly changed by user action.
- Renumbering is explicit, not implicit on move/sort/delete.

## Data Ownership Split: Circuit vs Device Row

Circuit-level fields on `Circuit`:

- protection type/rating/characteristic
- cable type/cross-section/length
- RCD/terminal/status

Device-level load fields on `CircuitDeviceRow`:

- quantity, power per unit, simultaneity, cosPhi
- row naming/categorization and room snapshots

This split matches execution-design workflows where many loads share one protective path.

## Calculated Totals

- `rowTotalPower` is calculated per `CircuitDeviceRow`.
- `circuitTotalPower` is calculated as sum of all row totals in one circuit.

Totals are exposed by the tree response and shown in computed read-only cells.

## Frontend Route

Primary circuit-first editor route:

- `/projects/:projectId/circuit-lists/:circuitListId/tree-edit`

Legacy route remains separate (read-only/preview/migration transition path) and is intentionally not merged into the editable tree editor.