Initial working implementation (MVP)

DEVELOPER_GUIDE.md

@@ -0,0 +1,61 @@
+# RMon Developer Guide
+
+This guide covers the internal architecture, protocol, and extension points of the RMon system.
+
+## Architecture Overview
+
+RMon is built with a focus on performance, safety, and portability.
+
+### `rmon-common`
+Contains shared types used by both the agent and UI.
+- **Protocol**: Defined in `src/protocol.rs`. Uses `bincode` for serialization over a length-prefixed TCP stream.
+- **Data Model**: `src/signal.rs` defines `Sample`, `SignalInfo`, and `SignalId`.
+
+### `rmon-agent`
+A multi-threaded server using `tokio`.
+- **Dispatcher**: Samples from all sources flow through a central `mpsc` channel to a dispatcher task.
+- **Fan-out**: The dispatcher sends samples to:
+  1. The **Storage Engine** (binary append logs).
+  2. All connected **Session Handlers** via a `broadcast` channel.
+- **DataSource Trait**: Abstract interface for data ingestion. New source types only need to implement the `run` and `signals` methods.
+
+### `rmon-ui`
+An immediate-mode GUI application.
+- **Backend Thread**: A separate thread runs the `tokio` runtime for non-blocking network I/O.
+- **Event Loop**: Communicates with the UI thread via `mpsc` channels (`UiMessage`).
+- **Repaint Policy**: The UI only repaints when new data arrives or on a fixed interval (50ms) to ensure smooth real-time performance.
+
+## Adding a New Data Source
+
+To add a new source type (e.g., `MQTT` or `Serial`):
+
+1. **Update Config**: Add relevant fields to `SourceConfig` and `SignalSourceConfig` in `rmon-agent/src/config.rs`.
+2. **Implement `DataSource`**: Create a new file in `rmon-agent/src/sources/` and implement the trait:
+   ```rust
+   #[async_trait]
+   pub trait DataSource: Send + 'static {
+       fn name(&self) -> &str;
+       fn signals(&self) -> Vec<SignalInfo>;
+       async fn run(self: Box<Self>, tx: mpsc::Sender<(SignalId, Sample)>) -> Result<()>;
+   }
+   ```
+3. **Register**: Add the source to `rmon-agent/src/sources/mod.rs` and update the `run_agent` loop in `rmon-agent/src/lib.rs`.
+
+## Development Workflows
+
+### Static Agent Build (Linux)
+```bash
+cargo build --release --target x86_64-unknown-linux-musl -p rmon-agent
+```
+
+### Integration Testing
+The project uses automated integration tests that spin up real agent instances and verify the protocol flow.
+```bash
+cargo test -p rmon-agent --test agent_test
+```
+
+### Protocol Changes
+If you modify `rmon-common/src/protocol.rs`:
+1. Increment `PROTOCOL_VERSION` in `protocol.rs`.
+2. Rebuild both the UI and the Agent.
+3. The UI will automatically detect the version mismatch on handshake and refuse to connect to old agents.