# Project architecture `tiny-wb` has a reusable acquisition library and a thin terminal application. The core accepts typed values and I/O interfaces; it does not depend on UI widgets, port discovery, worker threads, or the application's working directory. ## Source map | File | Responsibility | | --- | --- | | `src/lib.rs` | Public core module boundary. | | `src/config.rs` | Typed settings, recursive partial overrides, legacy-key compatibility and validation. | | `config/default.toml` | Authoritative embedded defaults, with units and comments. | | `src/storage.rs` | Same-directory atomic replacement for saved configuration. | | `src/protocol.rs` | Basic input-path rules, scan request validation and pure raw-frame decoding. | | `src/transport.rs` | Buffered `Read + Write` shell I/O, complete command writes, text prompts and length-delimited raw frames. | | `src/connection.rs` | Runtime serial/TCP adapter; native serial is optional. | | `src/mock/` | Opt-in bounded device simulation and stream server. | | `examples/mock-tinysa-server.rs` | Portable TCP listener for the mock, outside release binaries. | | `src/acquisition.rs` | Command ordering, progress events, frame decoding and resume attempts. | | `src/export.rs` | CSV serialization to a writer and collision-safe file export. | | `src/main.rs` | Load configuration, start diagnostics, enumerate ports and manage terminal lifetime. | | `src/error.rs` | Application/UI boundary errors with original context. | | `src/scan.rs` | Open the configured connection, adapt core events to shared progress, and export successful acquisitions. | | `src/ui/mod.rs` | Screen transitions, keyboard handling, worker startup and progress reconciliation. | | `src/ui/state.rs` | UI state, configured port/baud choices and bounded numeric input. | | `src/ui/view.rs` | Ratatui rendering and selection styling. | | `build.rs` | Embed Git revision and compile the Windows icon resource. | | `Jenkinsfile` | Required quality gates, coverage, badge cleanup/archival/publication and diagnostic smoke execution. | ## Data flow ```text embedded defaults + runtime overrides -> validated Config | startup / terminal controller | ScanRequest (Hz) + selected Config | connection worker | Shell -> acquisition | decode_frame -> Vec | CSV export + completed UI snapshot ``` `ScanRequest` carries Hz, sample count and repeat count. `Sample` carries MHz and dBm. Units are converted at the UI/core boundary, not inside widgets or file naming. The selected zero offset is both sent to the instrument and used by the decoder. Frequency labeling is an explicit policy; inclusive labels remain the default for compatibility. The core reports `ScanEvent` values. `ScanState` adapts them to one `Arc>`; completion publishes samples, filename, status and 100% progress together only after export succeeds. The UI transfers the completed sample vector once, rather than cloning it every frame. Error reporting uses the original error's message instead of a second exhaustive mapping. ## UI state machine ```text SelectingConnection -> SelectingScan -> Scanning -> Complete -> exit | | | +------------------+-------------+-> Error -> exit ``` The constructor takes configuration and enumerated ports as values, without reading files. Selection is clamped before rendering, including empty lists. Before a scan starts, the controller validates the complete selected settings and request, atomically saves settings, then starts a worker. The controller reconciles worker status before drawing; rendering does not consume samples. The terminal guard restores terminal modes on ordinary returns and unwinding. Configuration, logging and enumeration errors occur before terminal takeover. Process termination or release-mode panic abort cannot be recovered by a guard. ## Acquisition and protocol boundary 1. Validate the Basic range and sample/repeat limits before opening/using a port. 2. Synchronize with stale input, allowing an idle timeout only during this step. 3. Query `version`, `info` and the existing diagnostic commands. 4. Set `repeat` and the configured raw zero offset, then query markers. 5. Attempt `pause`, select input mode, and configure the display sweep. 6. Optionally retain the historical `scan START STOP 290 101` preparation. 7. Request `scanraw`, consume exactly the expected framed record count, then consume the trailing shell prompt. 8. Decode/validate all records and attempt `resume` on success or failure after pause was attempted. Preserve both failures if resume also fails. 9. Export validated samples and mark the application scan complete. The transport uses a persistent buffered stream. Prompt matching spans serial reads; bytes beyond a prompt remain available. Binary records are read by length, so sample bytes equal to braces or text characters are not delimiters. EOF, disconnect, oversized text and missing prompts are errors rather than successful partial reads. Writers use `write_all`, and protocol sequencing does not require `unsafe`. See [USB protocol](usb-protocol.md) for firmware evidence and the unresolved frequency-label compatibility decision. Device facts are not inferred from our synthetic test transcripts. ## Configuration and persistence The six legacy selection keys remain top-level. Additional sections cover serial timing/choices, scan policy, event timing, chart bounds, output and logging. Partial files merge with embedded defaults; unknown or invalid values fail explicitly. Saving selection values retains all recognized sections. CSV formatting is independent of file creation. The worker does not create a CSV until a complete frame has been validated and acquisition has returned success. Filenames contain microseconds plus a collision counter; exclusive creation avoids overwriting earlier scans. Failed writes remove incomplete files when the filesystem permits it. A file may be visible while being written; the returned path/completed status is the success indicator. See [configuration](configuration.md) for settings, paths and exact behavior. ## Extension points and remaining limits - Add model/capability recognition ahead of request planning. The current Basic mode rules must not be stretched to imply Ultra support. - Add new output formats beside `write_csv`, consuming `Sample` values rather than parsing the wire format again. - Inject transcript streams into `Shell` and writers into export tests. Keep UI tests on Ratatui's in-memory backend. See [testing](testing.md). - Settings change policy and timing; wire delimiters, fixed-point scaling and command grammar remain protocol invariants. - Known error/usage replies reject configuration commands, but responses are not a complete typed acknowledgement protocol. An echo-only identity can appear nonempty; prompt arrival alone is not proof of acceptance. - Serial timeouts are per-read idle timeouts, not a whole-transaction deadline. Cancellation/abort and complete device-state restoration remain future work. Quitting during a scan can terminate the worker before its resume attempt. - Synthetic tests do not establish the connected firmware's frequency stepping, raw-offset acceptance, or need for the legacy preliminary scan. Defaults retain previous behavior until hardware evidence supports changing it. ## Dependency policy The core uses standard-library byte decoding instead of `packed_struct`, and buffered framing instead of a separate direct `memchr` dependency. Transitive `memchr` use elsewhere in the graph is unrelated. Serde/TOML handle settings; serialport, Ratatui, chrono, log/flexi_logger, color-eyre and thiserror retain their device, presentation, timestamp and error-reporting roles. Library consumers can omit terminal and serial dependencies; see [feature selection](library.md). The [mock](mock-device.md) uses the same shell/acquisition code over memory or TCP.