# 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.