Receiver Architecture Guide

bijux-gnss-receiver owns staged runtime execution. The engine validates configuration and composes effects; acquisition, tracking, observations, and optional navigation adapters exchange typed state; artifacts and diagnostics record what happened without choosing repository placement.

Runtime Structure

flowchart LR
    config["validated receiver<br/>configuration"]
    ports["samples, clock,<br/>sinks, metrics"]
    engine["receiver engine"]
    acquisition["acquisition"]
    tracking["tracking"]
    observations["observations"]
    navigation["optional navigation"]
    artifacts["in-memory artifacts<br/>and diagnostics"]

    config --> engine
    ports --> engine
    engine --> acquisition --> tracking --> observations --> navigation
    acquisition --> artifacts
    tracking --> artifacts
    observations --> artifacts
    navigation --> artifacts

Every stage may enrich evidence, but no stage may erase uncertainty, ambiguity, degradation, or refusal from the stage before it.

Locate The Runtime Owner

concern	architecture route	ownership rule
Configuration, defaults, validation, runtime effects, support, or top-level composition	Module map	engine code owns receiver policy, not command defaults
Acquisition, tracking, observations, or optional navigation order	Execution model	pipeline stages own handoff and lifecycle evidence
Samples, clocks, artifacts, metrics, tracing, or logs	Integration seams	effects cross explicit ports rather than hidden globals
Dependency on core, signal, navigation, infrastructure, or command	Dependency direction	receiver composes lower science and is consumed by higher repository layers
Channel state, filter state, artifacts, or persisted runs	State and persistence	receiver owns in-memory runtime state; infrastructure owns durable placement
Input, acquisition, tracking, observation, or navigation failure	Error model	failure remains attributable to the earliest failing boundary
New stage, adapter, port, or artifact family	Extensibility model	additions require durable runtime responsibility and evidence
Cross-stage coupling or imported repository policy	Architecture risks	convenience must not blur scientific or persistence ownership

State Moves Forward, Evidence Fans Out

flowchart TD
    candidate["acquisition candidate"]
    channel["tracking channel state"]
    measurement["observation decision"]
    solution["optional navigation outcome"]
    acq_evidence["candidate evidence"]
    track_evidence["lock and transition evidence"]
    obs_evidence["quality and refusal evidence"]
    nav_evidence["solution or refusal evidence"]
    run["run artifacts"]

    candidate --> channel --> measurement --> solution
    candidate --> acq_evidence --> run
    channel --> track_evidence --> run
    measurement --> obs_evidence --> run
    solution --> nav_evidence --> run

The runtime path and evidence path are related but not identical. A rejected candidate may never become a channel yet still belongs in acquisition evidence. A refused observation may stop navigation input yet remain essential to diagnosis.

Effects Are Replaceable

Stage math must not open repository files, choose run directories, read wall-clock time implicitly, or render command reports. Samples and time enter through owned seams; artifacts, diagnostics, metrics, traces, and logs leave through explicit runtime boundaries. Tests can replace those effects without changing stage semantics.

Optional Navigation Is An Adapter

The receiver decides when observations are ready for a navigation call and how the resulting evidence joins a run. Navigation owns orbit, correction, estimation, integrity, PPP, and RTK science. Feature-gating the adapter must not change ownership or semantics of acquisition, tracking, or observations.

Implementation Evidence

Use code navigation after identifying the concern. The implementation authorities are the receiver engine, pipeline boundary, runtime ports, sample adapters, artifact model, and simulation boundary.

The crate architecture defines the complete runtime dataflow and dependency boundary.