# Design

## Source Of Truth And Migration

The native compiler owns a versioned area-local signal model and override
artifact. It is generated from OSM controls and native geometry inputs, then
edited by the Workbench without QGIS. The existing
`traffic_signal_assemblies.geojson` is a migration adapter: it can be imported
into the native model and exported for legacy QGIS/reimport workflows, but a
native compile never requires it to exist.

The existing `buildTrafficSignalFeatures()` and validation functions remain the
compatibility implementation for initial generation and import/export. Imported
features retain their legacy `signal_uid` where valid; newly generated native
features use the same deterministic identity rule so downstream runtime IDs do
not fork.

## Workbench API And Editing

`GET /api/state` adds the normalized native signal model, source control
metadata, migration provenance, and derived runtime signal records. A signal
edit is represented as an atomic replacement of the validated native signal
override artifact through a dedicated signal save endpoint. A separate import
or export action handles the legacy QGIS collection; road overrides remain in
their existing file and schema.

The browser uses stable `signal_uid` values. It supports:

- generate: choose an OSM traffic-signal control and arm, then create the
  deterministic assembly using the existing generator contract;
- move: update the Point coordinates while retaining stop-line/source fields;
- rotate: update `heading_deg` with normalized degrees;
- delete: remove the assembly from the editable collection;
- edit enabled state, display ID, mast reach, z offset, and phase group.

Every save validates uniqueness, identity, finite geometry, source references,
and field ranges before an atomic write. Deleted features are absent from the
runtime output; disabled features remain in the editable/QGIS layer but are
omitted by `buildTrafficSignalsFromFeatures()`.

## Delivery Flow

The native road compile result includes signal assemblies and derived runtime
metadata without adding them to road geometry layers. Native Blender/Cesium
stages consume `traffic_signals.json` and dynamic GLB inputs generated directly
from the native model. The legacy QGIS adapter may materialize the old GeoJSON,
but it is not in the native build's critical path.

## Compatibility And Rollback

QGIS reimport continues to read/export the compatibility GeoJSON while the
legacy path remains unchanged. If native signal editing fails validation, the
previous atomic native override remains in place and the user receives a
field-level error. Rollback is selecting the legacy provider or exporting the
last native state to the QGIS adapter.