rmon/docs/architecture.md

RMon Architecture

Overview

RMon is split into two executables that communicate over a TCP connection tunneled through SSH:

Operator Machine                         Remote Network
┌─────────────────────────────┐          ┌──────────────────────────────────────┐
│  rmon-ui                    │          │  rmon-agent                          │
│  ┌──────────┐ ┌───────────┐ │   SSH    │  ┌──────────┐  ┌──────────────────┐ │
│  │ Plot     │ │ Signal    │ │  Tunnel  │  │ Protocol │  │ Source Adapters  │ │
│  │ Panels   │ │ Tree      │◄├──────────┤► │ Server   │◄─│ CSV / UDP / EPICS│ │
│  └──────────┘ └───────────┘ │          │  └──────────┘  └──────────────────┘ │
│  ┌──────────────────────┐   │          │                 ┌──────────────────┐ │
│  │ SSH Connection Mgr   │   │          │                 │ Storage Engine   │ │
│  └──────────────────────┘   │          │                 │ Continuous/Circ. │ │
└─────────────────────────────┘          │                 └──────────────────┘ │
                                         └──────────────────────────────────────┘

Language and Build Targets

Single language: Rust throughout agent, UI, and shared library.

Crate	Purpose	Build Target
rmon-common	Shared types and protocol messages	(library, no binary)
rmon-agent	Remote data acquisition server	x86_64-unknown-linux-musl (fully static, zero runtime deps)
rmon-ui	Operator desktop application	native platform (dynamically links X11 + libGL)

Why musl for the agent

The agent must run on remote machines with arbitrary (potentially old) Linux environments without root access. Compiling with x86_64-unknown-linux-musl produces a single binary with:

• No glibc dependency
• No dynamic linker requirement
• Works on any Linux kernel ≥ 3.2
• Can be copied with scp and run immediately

The UI runs on the operator's own modern desktop, so strict portability is not required there.

Why egui for the UI

• Immediate-mode rendering — natural fit for real-time data that changes every frame
• glow backend uses OpenGL 2.1+, available on all modern desktop Linux setups
• Cross-platform (Linux, Windows, macOS) from a single Rust codebase
• Ships as a single binary (dynamically links only X11/Wayland + libGL which are always present on any desktop Linux)
• egui_plot provides interactive time-series plots with zoom/pan; custom egui painter used for high-throughput rendering paths

Cargo Workspace Layout

rmon/
├── Cargo.toml              # workspace root
├── rmon-common/            # shared types and protocol (lib crate)
│   └── src/
│       ├── signal.rs       # SignalId, SignalInfo, Sample, StorageMode
│       └── protocol.rs     # ClientMessage, AgentMessage enums
├── rmon-agent/             # remote acquisition agent
│   ├── .cargo/config.toml  # sets default target to x86_64-unknown-linux-musl
│   └── src/
│       ├── main.rs
│       ├── config.rs       # TOML config file parsing
│       ├── sources/        # one module per data source type
│       │   ├── trait.rs    # DataSource trait
│       │   ├── csv.rs
│       │   ├── udp.rs
│       │   └── epics.rs
│       ├── storage/
│       │   ├── continuous.rs
│       │   └── circular.rs
│       └── server/
│           ├── listener.rs  # TCP accept loop
│           └── session.rs   # per-client session handler
└── rmon-ui/                # operator desktop UI
    └── src/
        ├── main.rs
        ├── app.rs          # top-level App struct, egui App impl
        ├── connection/
        │   ├── ssh.rs      # SSH tunnel lifecycle
        │   └── client.rs   # async protocol client (wraps TCP stream)
        ├── state/
        │   └── session.rs  # connected session state, signal cache
        └── ui/
            ├── connect_dialog.rs
            ├── signal_tree.rs
            ├── plot_panel.rs   # one per open plot window
            └── toolbar.rs

Remote Access: SSH-Based Deployment

RMon follows the same pattern as VSCode Remote: the UI manages the agent lifecycle transparently, leveraging the user's existing ~/.ssh/config (including ProxyJump for multi-hop networks).

Connection flow

1. User enters an SSH host alias (from their ~/.ssh/config) and optional agent port
2. UI runs: ssh {host} 'uname -m' to detect remote architecture
3. UI checks if agent binary is current: ssh {host} 'cat ~/.rmon/agent.sha256'
4. If stale/missing: UI pipes the correct pre-built binary via SSH:

   cat rmon-agent-{arch} | ssh {host} 'mkdir -p ~/.rmon && cat > ~/.rmon/agent && chmod +x ~/.rmon/agent'
   

5. UI starts the agent (if not already running):

   ssh {host} 'pgrep -f "rmon-agent --port {port}" || nohup ~/.rmon/agent --port {port} >> ~/.rmon/agent.log 2>&1 &'
   

6. UI establishes SSH local port forward: ssh -N -L {local_port}:localhost:{remote_port} {host}
7. UI opens TCP connection to localhost:{local_port} and sends Handshake

No special software needs to be installed on the remote machine. All multi-hop SSH configuration is handled transparently by the system ssh binary reading the user's ~/.ssh/config.

Data Flow (steady state)

Source (e.g. UDP)
    │  raw packets + source timestamp
    ▼
DataSource adapter
    │  normalizes timestamp → i64 nanoseconds since Unix epoch
    │  applies scale/offset
    ▼
Dispatcher (tokio broadcast channel per signal)
    │
    ├──► Storage engine  (writes to ring buffer or append log)
    │
    └──► Session handlers (one per connected UI client)
             │  batches samples, sends DataBatch over TCP
             ▼
         rmon-ui client
             │  updates per-signal ring buffer (last N seconds for display)
             ▼
         Plot panels (egui repaint)

Protocol Summary

Binary framing: [u32 little-endian length][bincode-serialized payload]

Messages are typed Rust enums defined in rmon-common::protocol. See docs/protocol.md for the full message reference.

Agent Configuration

The agent is configured via a TOML file (default: ~/.rmon/config.toml). It declares:

• Which data sources to connect to (type, address, signal definitions)
• Default storage policy

See docs/agent-spec.md for the full configuration reference.