# porta0922/monitorv3 architecture

> Architecture diagram of the GitHub repository porta0922/monitorv3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/porta0922/monitorv3
- Repository: https://github.com/porta0922/monitorv3

## Overview

1. **System shape**
   - This repo is a distributed monitoring platform with three runtime pieces: a Rust endpoint agent, a Rust backend server, and a React/TypeScript dashboard.
   - The core architectural pattern is: **capture on endpoint → publish to RabbitMQ → persist in PostgreSQL/TimescaleDB → query via HTTP/WebSocket from the dashboard**.

2. **Endpoint agent boundary**
   - The `agent/` crate is responsible for local data collection on Windows, Linux, and macOS.
   - It tracks active application/use state, keyboard and mouse activity, USB events, Wi‑Fi events, installed software inventory, and process/security signals.
   - The Windows design supports a **hybrid mode**: a system service plus a user-session component so it can capture both background and foreground activity.

3. **Agent internal subsystems**
   - The agent is split into focused modules: `input_tracking`, `keystroke_tracker`, `usb_detection`, `usb_file_copy_detection`, `wifi_detection`, `inventory`, `monitoring`, `osquery_runner`, `process_protection`, `offline_cache`, `rabbitmq_publisher`, and `device_id`.
   - `device_id` provides stable endpoint identity; `process_protection` keeps the agent harder to terminate; `offline_cache` stores events locally in SQLite when the network or broker is unavailable.
   - `osquery_runner` is the security-scan engine, but it is optional and silent if osquery is absent.

4. **Event transport layer**
   - The agent publishes telemetry to RabbitMQ using the `monitoring` topic exchange.
   - The backend consumes domain-specific queues for activity, heartbeat, USB, inventory, Wi‑Fi, and security data.
   - This decouples endpoint collection from server persistence and allows the agent to keep running even when the backend is temporarily unreachable.

5. **Backend server boundary**
   - The `server/` crate is the central integration layer: it exposes HTTP APIs, consumes RabbitMQ, and writes to the database.
   - `api.rs` and `ws.rs` serve client traffic; `rabbitmq_consumer.rs` ingests broker messages; `postgres_db.rs` and `db.rs` handle persistence access.
   - `auth.rs`, `whitelist.rs`, and `config.rs` define the control plane around access, allowed clients/devices, and runtime settings.

6. **Persistence layer**
   - PostgreSQL/TimescaleDB is the primary durable store, with schema created by the SQL migrations under `migrations/`.
   - The database holds the device catalog, logs, hourly aggregates, USB/Wi‑Fi history, and the security event tables introduced by later migrations.
   - TimescaleDB matters here because the workload is largely time-series telemetry and historical rollups.

7. **Security analytics flow**
   - Security findings come from two places: osquery-based detections mapped to MITRE ATT&CK and USB-copy detection based on recently written files on removable drives.
   - These findings are published as security events, deduplicated, persisted, and then exposed through `/api/security` and `/api/security/summary`.
   - The agent can also fetch an osquery policy from the server, so security scan frequency can be centrally controlled per fleet.

8. **Real-time delivery to the UI**
   - The server’s WebSocket layer provides live activity delivery, which is what powers the dashboard’s streaming views.
   - The dashboard’s `useActivityStream` hook and live tables are the main consumers of this path, complementing the REST API for historical data.

9. **Dashboard architecture**
   - `dashboard/` is a Vite + React + TypeScript SPA with feature pages for dashboard, activity, alerts, devices, inventory, metrics, security, heatmaps, and USB.
   - It uses a small API client plus feature-specific hooks (`useOverview`, `useTopApps`, `useAuth`, `useActivityStream`) instead of direct server coupling in components.
   - This makes the UI a thin presentation layer over the server’s REST and WebSocket interfaces.

10. **Deployment and runtime environments**
   - `docker-compose.yml` provisions the local infrastructure stack, including RabbitMQ and PostgreSQL/TimescaleDB, so the agent/server separation can be run consistently.
   - The repo also includes OS-specific install scripts in `deploy/` and Dockerfiles for the server and dashboard, reflecting that the agent is meant to be deployed onto endpoints, not just containers.
   - Windows install scripts support service-based installation, user-task installation, or the hybrid mode described in the README.

11. **Cross-cutting boundary: offline resilience**
   - The agent’s SQLite offline cache is the main resilience mechanism: it buffers telemetry when broker connectivity is lost and later replays it.
   - This means the architecture tolerates intermittent connectivity at the edge without losing local endpoint data, while still preserving the server as the system of record.

12. **Common model alignment**
   - The root-level `shared_types.rs` suggests shared DTOs or event schemas used to keep agent, server, and dashboard aligned on payload structure.
   - That shared contract is important because the system moves typed telemetry across process, network, and storage boundaries.

Main entry points: [`agent/src/main.rs`](https://github.com/porta0922/monitorv3/blob/main/agent/src/main.rs) (Agent entry), [`agent/src/rabbitmq_publisher.rs`](https://github.com/porta0922/monitorv3/blob/main/agent/src/rabbitmq_publisher.rs) (Broker publish), [`server/src/main.rs`](https://github.com/porta0922/monitorv3/blob/main/server/src/main.rs) (Server entry), [`server/src/rabbitmq_consumer.rs`](https://github.com/porta0922/monitorv3/blob/main/server/src/rabbitmq_consumer.rs) (Broker consume)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_endpoint["Endpoint agent"]
  node_agent_main(("Agent entry<br/>rust binary<br/>[main.rs]"))
  node_device_id["Device ID<br/>identity<br/>[device_id.rs]"]
  node_input_tracking["Input tracking<br/>telemetry<br/>[input_tracking.rs]"]
  node_inventory["Inventory<br/>asset scan<br/>[inventory.rs]"]
  node_usb_detection["USB events<br/>device telemetry<br/>[usb_detection.rs]"]
  node_usb_copy["USB copy<br/>security signal"]
  node_wifi_detection["Wi-Fi events<br/>telemetry<br/>[wifi_detection.rs]"]
  node_process_protection["Process guard<br/>resilience"]
  node_offline_cache[("Offline cache<br/>sqlite buffer<br/>[offline_cache.rs]")]
  node_osquery_runner["Osquery scan<br/>security scan<br/>[osquery_runner.rs]"]
  node_rabbitmq_publisher["Broker publish<br/>messaging"]
end

subgraph group_backend["Backend server"]
  node_server_main(("Server entry<br/>rust binary<br/>[main.rs]"))
  node_api["HTTP API<br/>rest<br/>[api.rs]"]
  node_ws["WebSocket<br/>realtime<br/>[ws.rs]"]
  node_rabbitmq_consumer["Broker consume<br/>ingest"]
  node_postgres_db[("Postgres store<br/>timeseries db<br/>[postgres_db.rs]")]
  node_auth["Auth & config<br/>control plane<br/>[auth.rs]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard_shell["Dashboard app<br/>spa shell<br/>[App.tsx]"]
  node_api_client["API client<br/>frontend api<br/>[client.ts]"]
  node_activity_stream["Live stream<br/>frontend hook"]
  node_feature_pages["Feature pages<br/>views<br/>[DashboardPage.tsx]"]
end

subgraph group_data["Persistence"]
  node_migrations["Migrations<br/>schema"]
end

subgraph group_ops["Deployment"]
  node_docker_compose["Compose stack<br/>runtime config<br/>[docker-compose.yml]"]
  node_deploy_scripts["Install scripts<br/>deployment"]
end

subgraph group_shared["Shared contract"]
  node_shared_types["Shared types<br/>contracts<br/>[shared_types.rs]"]
end

node_agent_main -->|"identity"| node_device_id
node_agent_main -->|"collects"| node_input_tracking
node_agent_main -->|"collects"| node_inventory
node_agent_main -->|"collects"| node_usb_detection
node_agent_main -->|"collects"| node_wifi_detection
node_agent_main -->|"hardens"| node_process_protection
node_agent_main -->|"buffers"| node_offline_cache
node_agent_main -->|"optional scan"| node_osquery_runner
node_input_tracking -->|"events"| node_rabbitmq_publisher
node_inventory -->|"events"| node_rabbitmq_publisher
node_usb_detection -->|"feeds"| node_usb_copy
node_usb_copy -->|"security events"| node_rabbitmq_publisher
node_wifi_detection -->|"events"| node_rabbitmq_publisher
node_offline_cache -->|"replay"| node_rabbitmq_publisher
node_rabbitmq_publisher -->|"monitoring exchange"| node_rabbitmq_consumer
node_rabbitmq_consumer -->|"persists"| node_postgres_db
node_server_main -->|"serves"| node_api
node_server_main -->|"streams"| node_ws
node_server_main -->|"ingests"| node_rabbitmq_consumer
node_server_main -->|"controls"| node_auth
node_api -->|"queries"| node_postgres_db
node_ws -->|"live feed"| node_rabbitmq_consumer
node_migrations -->|"schema"| node_postgres_db
node_shared_types -->|"contracts"| node_agent_main
node_shared_types -->|"contracts"| node_server_main
node_shared_types -->|"contracts"| node_dashboard_shell
node_dashboard_shell -->|"REST"| node_api_client
node_dashboard_shell -->|"realtime"| node_activity_stream
node_dashboard_shell -->|"routes"| node_feature_pages
node_activity_stream -->|"subscribes"| node_ws
node_api_client -->|"requests"| node_api
node_feature_pages -->|"data"| node_api_client
node_docker_compose -->|"infra"| node_rabbitmq_consumer
node_docker_compose -->|"infra"| node_postgres_db
node_deploy_scripts -->|"install"| node_agent_main

click node_agent_main "https://github.com/porta0922/monitorv3/blob/main/agent/src/main.rs"
click node_device_id "https://github.com/porta0922/monitorv3/blob/main/agent/src/device_id.rs"
click node_input_tracking "https://github.com/porta0922/monitorv3/blob/main/agent/src/input_tracking.rs"
click node_inventory "https://github.com/porta0922/monitorv3/blob/main/agent/src/inventory.rs"
click node_usb_detection "https://github.com/porta0922/monitorv3/blob/main/agent/src/usb_detection.rs"
click node_usb_copy "https://github.com/porta0922/monitorv3/blob/main/agent/src/usb_file_copy_detection.rs"
click node_wifi_detection "https://github.com/porta0922/monitorv3/blob/main/agent/src/wifi_detection.rs"
click node_process_protection "https://github.com/porta0922/monitorv3/blob/main/agent/src/process_protection.rs"
click node_offline_cache "https://github.com/porta0922/monitorv3/blob/main/agent/src/offline_cache.rs"
click node_osquery_runner "https://github.com/porta0922/monitorv3/blob/main/agent/src/osquery_runner.rs"
click node_rabbitmq_publisher "https://github.com/porta0922/monitorv3/blob/main/agent/src/rabbitmq_publisher.rs"
click node_server_main "https://github.com/porta0922/monitorv3/blob/main/server/src/main.rs"
click node_api "https://github.com/porta0922/monitorv3/blob/main/server/src/api.rs"
click node_ws "https://github.com/porta0922/monitorv3/blob/main/server/src/ws.rs"
click node_rabbitmq_consumer "https://github.com/porta0922/monitorv3/blob/main/server/src/rabbitmq_consumer.rs"
click node_postgres_db "https://github.com/porta0922/monitorv3/blob/main/server/src/postgres_db.rs"
click node_auth "https://github.com/porta0922/monitorv3/blob/main/server/src/auth.rs"
click node_migrations "https://github.com/porta0922/monitorv3/blob/main/migrations/001_init_schema.sql"
click node_shared_types "https://github.com/porta0922/monitorv3/blob/main/shared_types.rs"
click node_dashboard_shell "https://github.com/porta0922/monitorv3/blob/main/dashboard/src/App.tsx"
click node_api_client "https://github.com/porta0922/monitorv3/blob/main/dashboard/src/api/client.ts"
click node_activity_stream "https://github.com/porta0922/monitorv3/blob/main/dashboard/src/hooks/useActivityStream.ts"
click node_feature_pages "https://github.com/porta0922/monitorv3/blob/main/dashboard/src/pages/DashboardPage.tsx"
click node_docker_compose "https://github.com/porta0922/monitorv3/blob/main/docker-compose.yml"
click node_deploy_scripts "https://github.com/porta0922/monitorv3/blob/main/deploy/install-windows.bat"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_main,node_device_id,node_input_tracking,node_inventory,node_usb_detection,node_usb_copy,node_wifi_detection,node_process_protection,node_offline_cache,node_osquery_runner,node_rabbitmq_publisher toneBlue
class node_server_main,node_api,node_ws,node_rabbitmq_consumer,node_postgres_db,node_auth toneAmber
class node_dashboard_shell,node_api_client,node_activity_stream,node_feature_pages toneMint
class node_migrations toneRose
class node_docker_compose,node_deploy_scripts toneIndigo
class node_shared_types toneTeal
```

## Components

### Endpoint agent

Rust agent that collects local telemetry and security signals on managed devices.

- [Agent entry](https://github.com/porta0922/monitorv3/blob/main/agent/src/main.rs): rust binary · Initializes endpoint collection, resilience, and publishing on each device. · `agent/src/main.rs`
- [Device ID](https://github.com/porta0922/monitorv3/blob/main/agent/src/device_id.rs): identity · Generates stable endpoint identity for telemetry and device catalog matching. · `agent/src/device_id.rs`
- [Input tracking](https://github.com/porta0922/monitorv3/blob/main/agent/src/input_tracking.rs): telemetry · Captures active use state and keyboard/mouse activity. · `agent/src/input_tracking.rs`
- [Inventory](https://github.com/porta0922/monitorv3/blob/main/agent/src/inventory.rs): asset scan · Collects installed software and endpoint inventory data. · `agent/src/inventory.rs`
- [USB events](https://github.com/porta0922/monitorv3/blob/main/agent/src/usb_detection.rs): device telemetry · Detects removable media and USB-related activity. · `agent/src/usb_detection.rs`
- [USB copy](https://github.com/porta0922/monitorv3/blob/main/agent/src/usb_file_copy_detection.rs): security signal · Flags suspicious file writes to removable drives. · `agent/src/usb_file_copy_detection.rs`
- [Wi-Fi events](https://github.com/porta0922/monitorv3/blob/main/agent/src/wifi_detection.rs): telemetry · Tracks wireless network changes and connectivity events. · `agent/src/wifi_detection.rs`
- [Process guard](https://github.com/porta0922/monitorv3/blob/main/agent/src/process_protection.rs): resilience · Hardens the agent against termination and disruption. · `agent/src/process_protection.rs`
- [Offline cache](https://github.com/porta0922/monitorv3/blob/main/agent/src/offline_cache.rs): sqlite buffer · Stores telemetry locally when RabbitMQ is unavailable and replays later. · `agent/src/offline_cache.rs`
- [Osquery scan](https://github.com/porta0922/monitorv3/blob/main/agent/src/osquery_runner.rs): security scan · Optional policy-driven osquery execution for endpoint security findings. · `agent/src/osquery_runner.rs`
- [Broker publish](https://github.com/porta0922/monitorv3/blob/main/agent/src/rabbitmq_publisher.rs): messaging · Publishes endpoint telemetry to the monitoring exchange on RabbitMQ. · `agent/src/rabbitmq_publisher.rs`

### Backend server

Rust service that consumes broker events, persists them, and serves client APIs.

- [Server entry](https://github.com/porta0922/monitorv3/blob/main/server/src/main.rs): rust binary · Starts HTTP, WebSocket, broker consumption, and persistence services. · `server/src/main.rs`
- [HTTP API](https://github.com/porta0922/monitorv3/blob/main/server/src/api.rs): rest · Serves historical data, control-plane endpoints, and security queries. · `server/src/api.rs`
- [WebSocket](https://github.com/porta0922/monitorv3/blob/main/server/src/ws.rs): realtime · Streams live activity updates to dashboard clients. · `server/src/ws.rs`
- [Broker consume](https://github.com/porta0922/monitorv3/blob/main/server/src/rabbitmq_consumer.rs): ingest · Consumes domain queues for activity, inventory, USB, Wi-Fi, heartbeat, and security events. · `server/src/rabbitmq_consumer.rs`
- [Postgres store](https://github.com/porta0922/monitorv3/blob/main/server/src/postgres_db.rs): timeseries db · Database access layer for durable telemetry, aggregates, and security records. · `server/src/postgres_db.rs`
- [Auth & config](https://github.com/porta0922/monitorv3/blob/main/server/src/auth.rs): control plane · Handles authentication, whitelisting, and runtime settings for the server. · `server/src/auth.rs`

### Dashboard

React/TypeScript SPA for operators and live monitoring.

- [Dashboard app](https://github.com/porta0922/monitorv3/blob/main/dashboard/src/App.tsx): spa shell · React application shell and page composition for the operator UI. · `dashboard/src/App.tsx`
- [API client](https://github.com/porta0922/monitorv3/blob/main/dashboard/src/api/client.ts): frontend api · Thin client wrapper for REST calls into the server. · `dashboard/src/api/client.ts`
- [Live stream](https://github.com/porta0922/monitorv3/blob/main/dashboard/src/hooks/useActivityStream.ts): frontend hook · Consumes WebSocket activity updates for streaming views. · `dashboard/src/hooks/useActivityStream.ts`
- [Feature pages](https://github.com/porta0922/monitorv3/blob/main/dashboard/src/pages/DashboardPage.tsx): views · Pages for dashboard, activity, alerts, devices, inventory, metrics, security, heatmaps, and USB views. · `dashboard/src/pages/DashboardPage.tsx`

### Persistence

Database schema and migrations for time-series telemetry and security history.

- [Migrations](https://github.com/porta0922/monitorv3/blob/main/migrations/001_init_schema.sql): schema · Creates and evolves the PostgreSQL/TimescaleDB schema. · `migrations/001_init_schema.sql`

### Deployment

Local runtime and install artifacts for running the stack across environments.

- [Compose stack](https://github.com/porta0922/monitorv3/blob/main/docker-compose.yml): runtime config · Local infrastructure for RabbitMQ and PostgreSQL/TimescaleDB. · `docker-compose.yml`
- [Install scripts](https://github.com/porta0922/monitorv3/blob/main/deploy/install-windows.bat): deployment · OS-specific installation and diagnostic scripts for endpoint rollout. · `deploy/install-windows.bat`

### Shared contract

Common DTOs and event schemas used across the repo.

- [Shared types](https://github.com/porta0922/monitorv3/blob/main/shared_types.rs): contracts · Common DTOs and event schemas shared across agent, server, and dashboard. · `shared_types.rs`

## Connections

- Agent entry → Device ID: identity · Endpoint startup binds a stable device identity.
- Agent entry → Input tracking: collects · Main agent orchestrates local telemetry capture.
- Agent entry → Inventory: collects · Main agent orchestrates inventory discovery.
- Agent entry → USB events: collects · Main agent orchestrates USB monitoring.
- Agent entry → Wi-Fi events: collects · Main agent orchestrates Wi-Fi monitoring.
- Agent entry → Process guard: hardens · Startup enables process survivability measures.
- Agent entry → Offline cache: buffers · Telemetry can be staged locally when the broker is unavailable.
- Agent entry → Osquery scan: optional scan · Security scans run only when osquery is available.
- Input tracking → Broker publish: events · Captured activity is forwarded for publication.
- Inventory → Broker publish: events · Inventory snapshots are forwarded for publication.
- USB events → USB copy: feeds · USB activity informs suspicious copy detection.
- USB copy → Broker publish: security events · Removable-drive write findings are published as security telemetry.
- Wi-Fi events → Broker publish: events · Wi-Fi changes are forwarded for publication.
- Offline cache → Broker publish: replay · Buffered telemetry is replayed after connectivity returns.
- Broker publish → Broker consume: monitoring exchange · Endpoint telemetry crosses the broker boundary into server ingestion.
- Broker consume → Postgres store: persists · Consumed events are written to the database.
- Server entry → HTTP API: serves · Server entry exposes HTTP endpoints.
- Server entry → WebSocket: streams · Server entry exposes live updates over WebSocket.
- Server entry → Broker consume: ingests · Server starts broker consumers for domain queues.
- Server entry → Auth & config: controls · Server loads auth, whitelist, and runtime settings.
- HTTP API → Postgres store: queries · REST endpoints read historical and summary data.
- WebSocket → Broker consume: live feed · WebSocket delivery is backed by incoming activity events.
- Migrations → Postgres store: schema · Migrations define the durable tables used by the server.
- Shared types → Agent entry: contracts · Shared schemas keep telemetry payloads aligned.
- Shared types → Server entry: contracts · Shared schemas keep server ingestion and APIs aligned.
- Shared types → Dashboard app: contracts · Shared types keep the UI aligned with server payloads.
- Dashboard app → API client: REST · Pages and components call through the API client.
- Dashboard app → Live stream: realtime · Shell composes live activity views.
- Dashboard app → Feature pages: routes · The SPA is organized into feature pages.
- Live stream → WebSocket: subscribes · The hook consumes server WebSocket activity.
- API client → HTTP API: requests · Frontend REST calls target the HTTP API.
- Feature pages → API client: data · Feature pages load historical data through the client.
- Compose stack → Broker consume: infra · Local stack brings up broker-backed ingestion.
- Compose stack → Postgres store: infra · Local stack brings up the database used by the server.
- Install scripts → Agent entry: install · Deployment scripts install the endpoint agent on managed devices.