DD3-LoRa-Bridge-MultiSender/docs/REFRACTOR_NOTES.md

Refactor Notes: main.cpp Split

Architecture

The firmware remains a unified image. Role selection is still done at boot in src/main.cpp using the role pin. src/main.cpp is now a thin coordinator that:

• detects role and initializes shared platform subsystems,
• creates role module config,
• calls begin() once,
• delegates runtime via loop().

Sender Logic

Sender-only runtime now lives in:

• src/sender_state_machine.h
• src/sender_state_machine.cpp

Public API:

• SenderStateMachineConfig
• SenderStats
• SenderStateMachine::begin(...)
• SenderStateMachine::loop()
• SenderStateMachine::stats()

Sender state machine exposes explicit states (Syncing, Normal, Catchup, WaitAck) and keeps sender flow isolated from top-level orchestration.

Sender helpers:

• handleMeterRead(...)
• maybeSendBatch(...)
• handleAckWindow(...)
• applyTimeFromAck(...)
• validateInvariants()

Sender invariants are checked and debug-traceable (DD3_DEBUG) for:

• single inflight batch at a time,
• ACK acceptance only for matching batch_id,
• retry bounded by BATCH_MAX_RETRIES,
• queue depth bounded by BATCH_QUEUE_DEPTH.

Receiver Logic

Receiver-only runtime now lives in:

• src/receiver_pipeline.h
• src/receiver_pipeline.cpp

Shared receiver arrays and fault/discovery state used by setup wiring and runtime are held in:

• src/app_context.h (ReceiverSharedState)

Public API:

• ReceiverPipelineConfig
• ReceiverStats
• ReceiverPipeline::begin(...)
• ReceiverPipeline::loop()
• ReceiverPipeline::stats()

Receiver pipeline owns LoRa RX processing, reassembly/decode, ACK send path, MQTT/SD/display updates, and receiver fault/discovery publication flow.

HA Manufacturer Single Source

include/config.h defines the canonical manufacturer:

• HA_MANUFACTURER = "AcidBurns"

Home Assistant discovery payload generation in src/mqtt_client.cpp uses this constant directly (device["manufacturer"] = HA_MANUFACTURER).

Drift guards:

• compile-time lock in include/config.h via static_assert,
• test/check_ha_manufacturer.ps1 validates discovery assignment and rejects stray hardcoded manufacturer literals in src/ and include/,
• smoke test test/test_refactor_smoke/test_refactor_smoke.cpp asserts the constant value and module header compatibility.