From 060454780f2d2e54f66a8860ca4442c7cc88d95f Mon Sep 17 00:00:00 2001
From: Stan Grams <sjg@haxx.space>
Date: Tue, 24 Feb 2026 18:05:59 +0100
Subject: [PATCH] [docs](trx-rs): add CLAUDE.md for Claude Code guidance

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Stan Grams <sjg@haxx.space>
---
 CLAUDE.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..cd925b1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Build
+cargo build --release
+
+# Run tests
+cargo test
+
+# Lint
+cargo clippy
+
+# Run a single test (by name pattern)
+cargo test <test_name>
+
+# Run tests for a specific crate
+cargo test -p trx-core
+
+# Generate example config
+./target/release/trx-server --print-config > trx-server.toml
+./target/release/trx-client --print-config > trx-client.toml
+
+# Run server
+./target/release/trx-server --config trx-server.toml
+# or via CLI args:
+./target/release/trx-server -r ft817 "/dev/ttyUSB0 9600"
+
+# Run client
+./target/release/trx-client --config trx-client.toml
+```
+
+## Crate Layout
+
+This is a Cargo workspace. All crates live under `src/`:
+
+```
+src/
+  trx-core/           # Core types, traits, state machine, controller
+  trx-protocol/       # Client↔server protocol conversion, auth, codec
+  trx-app/            # Shared application helpers (config, plugins, logging)
+  trx-server/         # Server binary (rig_task, audio, APRS-IS, PSKReporter)
+    trx-backend/      # Backend abstraction trait + factory
+      trx-backend-ft817/    # Yaesu FT-817 CAT implementation
+      trx-backend-ft450d/   # Yaesu FT-450D CAT implementation
+  trx-client/         # Client binary (connects to server, runs frontends)
+    trx-frontend/     # Frontend trait (FrontendSpawner)
+      trx-frontend-http/      # Web UI with REST API, SSE, and auth
+      trx-frontend-http-json/ # JSON-over-TCP control frontend
+      trx-frontend-rigctl/    # Hamlib-compatible rigctl TCP interface
+  decoders/
+    trx-aprs/         # APRS packet decoder
+    trx-cw/           # CW (Morse) decoder
+    trx-ft8/          # FT8 decoder (wraps external ft8_lib C library)
+    trx-wspr/         # WSPR decoder
+    trx-decode-log/   # Shared decoder logging (JSON Lines, date-rotated files)
+```
+
+## Architecture
+
+The project is split into a **server** (connects to the radio hardware) and a **client** (exposes user-facing frontends). They communicate over a JSON TCP connection (default port 4530). Audio streams over a separate TCP connection (default port 4531) using Opus encoding.
+
+### Data flow
+
+```
+Radio hardware
+    ↕ serial/TCP
+trx-server (rig_task.rs)
+    ↕ trx-protocol JSON-TCP (port 4530)
+trx-client (remote_client.rs)
+    ↕ internal channels
+Frontends: HTTP (8080), rigctl (4532), http-json (ephemeral)
+```
+
+### trx-core controller
+
+The rig controller (`src/trx-core/src/rig/controller/`) is the central state management component:
+
+- **`machine.rs`** — `RigMachineState` enum with states: `Disconnected`, `Connecting`, `Initializing`, `PoweredOff`, `Ready`, `Transmitting`, `Error`
+- **`handlers.rs`** — `RigCommandHandler` trait; commands: `SetFreq`, `SetMode`, `SetPtt`, `PowerOn/Off`, `ToggleVfo`, `Lock/Unlock`, `GetSnapshot`, etc.
+- **`events.rs`** — `RigListener` trait and `RigEventEmitter` for broadcasting frequency/mode/PTT/state/meter/lock/power changes
+- **`policies.rs`** — `RetryPolicy` (`ExponentialBackoff`, `FixedDelay`, `NoRetry`) and `PollingPolicy` (`AdaptivePolling`, `FixedPolling`, `NoPolling`)
+
+### Decoders
+
+Signal decoders run as background tasks in `trx-server`, consuming decoded audio. `trx-ft8` wraps a C library (`external/ft8_lib`). Decoded frames can be forwarded to PSKReporter and APRS-IS (IGate) uplinks, or logged via `trx-decode-log`.
+
+### Plugin system
+
+Both `trx-server` and `trx-client` can load shared-library plugins exporting a `trx_register` symbol. Search paths: `./plugins`, `~/.config/trx-rs/plugins`, `TRX_PLUGIN_DIRS` env var.
+
+## Commit Format
+
+```
+[<type>](<crate>): <description>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`. Use `(trx-rs)` for repo-wide changes. Sign commits with `git commit -s`. Write isolated commits per crate.