# Migration Plan

Constraints:

- No big-bang rewrite of packet semantics.
- Current FreeDMR remains live until FreeDMR 2 is tested.
- Build FreeDMR 2 core beside current code where practical.
- Preserve behaviours behind tests.
- Compatibility adapters are allowed, but old internal shape should not define the new core.
- Worker-process scaling is a design direction, not a reason for a big-bang rewrite.

## Stages

Stage 0: Stabilise current code, harness, docs, codec, and known behaviour.

Stage 1: Distil architecture, glossary, state model, and reporting event contract.

Stage 2: Extract packet/codec helpers and deterministic routing/subscription seams.

Stage 3: Introduce explicit internal message/event objects in-process.

Stage 4: Implement new subscription store in parallel with compatibility export if needed.

Stage 5: Move reporting/MQTT publisher to an independent worker/sidecar.

Stage 6: Move global lastheard exporter, SQL writes, dashboard aggregation, and non-critical analytics to workers.

Stage 7: Define v2 API/control-plane operations over sessions, subscriptions, mesh state, and reporting health, and express them as owner-handled `ControlCommand` messages.

Stage 8: Introduce listener/client session model supporting multiple clients per listener.

Stage 9: Introduce mesh auth/BCXX identity admission into the control plane.

Stage 10: Experiment with a single routing-core worker behind the already-tested message interface.

Stage 11: Evaluate multi-routing-worker sharding only after single-worker routing is stable and covered.

Stage 12: Cut over only after deterministic, UDP, and live RF validation.

## Non-Goals

- Do not add general user-to-user private voice routing.
- Do not make FreeDMR core a GPS/SMS application processor.
- Do not make reporting/dashboard consumers part of packet routing.
- Do not encrypt amateur-radio traffic by default.
- Do not replace Twisted before extracting and test-covering the core.
- Do not preserve the old dashboard protocol inside the FreeDMR 2 packet core.
- Do not make worker-process scaling an immediate rewrite requirement.
- Do not use Redis, Postgres, MQTT, dashboards, or APIs for live per-packet routing decisions.

## Open Questions

- Exact cut-over mechanism from current `BRIDGES` state to subscription state.
- Whether old dashboard compatibility is shipped as part of FreeDMR 2 or maintained with the dashboard.
- Final mesh authentication wire format and key distribution policy.
- Live RF validation matrix for repeaters, hotspots, terminals, and analogue/digital bridges.