Node Supporting Reasoning Notes

This section explains key design decisions and rationale for the node architecture.

---

1. Why Decode Toggles Live on the Node API

1.1 Problem statement

Should telemetry parameter decoding (converting binary payload to typed values) happen on the node, central server, or frontend?

1.2 Design decision

Payload predecoding is an optional node feature (predecode_enabled flag in API). When enabled, the node emits typed parameter values alongside raw frame bytes for the payload definitions it has been configured to decode. Central source selection is a separate routing decision and does not change the node's output contract.

1.3 Reasoning

1. Transport efficiency: The cheapest path is to keep candidate streams raw until central selects the winner, then decode only the preferred stream at the appropriate layer. The node is already demodulating the stream, so optional edge decode adds local CPU when desired; it should not be used to process every candidate source
2. Node simplicity: The node is hardware + RF. Knowing how to extract fields from a frame (bitwise operations) is reasonable; asking it to bind parameters to UI violates node abstraction
3. Flexibility: Central server and UI handle binding and display. Node doesn't need to know about UI context, and central can later promote or demote a source stream without changing the schema decode on the node
4. Fallback: Raw frame bytes always accompany decoded output, so decoding failures don't lose data. Central can still discard a source after source selection without having to re-decode raw RF, and the same node output can be decoded centrally if edge decode is not enabled

1.4 Consequence

• Node API includes predecode_enabled and field_schema[]
• Central server applies binding rules to decoded parameters
• Frontend displays using central's binding rules

---

2. Why Typed Decoding and Raw Export Coexist

2.1 Problem statement

Should the node output only decoded parameters, only raw bytes, or both?

2.2 Design decision

Both. Node always outputs raw frame bytes. If predecode_enabled: true, it also outputs typed parameter values alongside the raw bytes.

2.3 Reasoning

1. Forensic safety: Raw bytes preserve exact bit pattern for post-flight analysis or protocol reverse-engineering
2. Fallback: If decoding schema is wrong, raw bytes are still available
3. Latency: Some consumers (engineering tools) want raw ASAP; splitting doesn't help, so include both

2.4 Consequence

• Every telemetry event includes raw_payload (bytes or hex)
• If pre-decode is enabled, also includes decoded_values (typed parameters)
• If pre-decode is disabled, only raw payload (no decoded fields)
• Central server and frontend handle both modes transparently

The node does not know which stream the central server will prefer downstream; it only emits the formats it has been configured to publish.

---

3. Why Target Identity is Preserved but Not Interpreted

3.1 Problem statement

Multiple rockets could theoretically downlink on the same frequency. How should the node handle target identity (which rocket is sending)?

3.2 Design decision

Node preserves target_id from incoming frames (if present in payload) but doesn't interpret or use it for DSP logic. Target identity is purely metadata passed through to central server.

3.3 Reasoning

1. Separation: RF decoding (node job) is separate from mission context (central server job)
2. Agnosticism: Node doesn't need to know how many targets exist or what they are
3. Central authority: Multiple targets should not affect node DSP behavior; central server decides routing and binding
4. Flexibility: If target identity scheme changes (e.g., from header field to frequency band), node code doesn't change

3.4 Consequence

• Node extracts target_id from payload if schema includes it
• Node outputs every frame with target_id preserved
• Central server routes frames per target to dashboard
• Frontend renders telemetry per target independently

---

Next: See Node-Gaps-Deferred for unresolved node-level architecture decisions.