# elysia62/nodeflare architecture

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

- Interactive diagram: https://gitdiagram.com/elysia62/nodeflare
- Repository: https://github.com/elysia62/nodeflare

## Overview

NodeFlare is a self-hosted server monitoring and control panel. The core workflow runs from Agent metric collection and outbound reporting, through backend WebSocket ingestion and persistence, to live and historical dashboard views. Administrators also configure latency probes, alerts, remote commands, authentication, themes, and database operations. The graph reflects README capabilities; selected source excerpts support specific wiring, while unsampled subsystem links are limited to documented behavior and tree paths.

Main entry points: [`backend/src/routes/admin.rs`](https://github.com/elysia62/nodeflare/blob/main/backend/src/routes/admin.rs) (API routes), [`agent/src/main.rs`](https://github.com/elysia62/nodeflare/blob/main/agent/src/main.rs) (Agent runtime), [`backend/src/websocket/agent.rs`](https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/agent.rs) (Agent WebSocket), [`backend/src/main.rs`](https://github.com/elysia62/nodeflare/blob/main/backend/src/main.rs) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Monitoring Agent"]
  node_agent["Agent runtime<br/>[main.rs]"]
  node_metrics["System metrics<br/>[metrics.rs]"]
  node_probe["Latency probes<br/>[probe.rs]"]
  node_remote["Remote execution<br/>[remote.rs]"]
  node_livebatch["Live batching<br/>[live_batch.rs]"]
  node_sharedtelemetry["Telemetry types<br/>[telemetry.rs]"]
end

subgraph group_backend["Backend Services"]
  node_server["HTTP application<br/>[main.rs]"]
  node_wsagent["Agent WebSocket<br/>[agent.rs]"]
  node_ingest["Telemetry ingestion<br/>[ingest.rs]"]
  node_dashboardws["Dashboard WebSocket<br/>[dashboard.rs]"]
  node_routes["API routes<br/>[admin.rs]"]
  node_auth["Authentication<br/>[auth.rs]"]
  node_notify["Alerts and notices<br/>[notify.rs]"]
  node_backup["Backup and migration<br/>[backup.rs]"]
end

subgraph group_frontend["Web Dashboard"]
  node_frontendapp["Dashboard UI<br/>[App.tsx]"]
  node_provider["Application state<br/>[AppProvider.tsx]"]
  node_api["HTTP client<br/>[api.ts]"]
  node_admin["Admin console<br/>[adminRoutes.ts]"]
  node_latencyui["Latency views<br/>[useNodeLatency.ts]"]
end

subgraph group_state["Persistence"]
  node_database[("SQLite / PostgreSQL<br/>[mod.rs]")]
  node_ingestqueries["Ingest and history<br/>[ingest.rs]"]
  node_alertqueries["Alert queries<br/>[alerts.rs]"]
  node_latencyqueries["Latency queries<br/>[latency.rs]"]
end

subgraph group_integrations["External Services"]
  node_exchange["Exchange rates<br/>[exchange.rs]"]
end

node_operator(("Dashboard user"))
node_host(("Monitored host"))
node_telegram(("Telegram"))
node_turnstile(("Cloudflare Turnstile"))

node_host -->|"samples"| node_metrics
node_agent -->|"collects"| node_metrics
node_agent -->|"executes tasks"| node_probe
node_agent -->|"runs commands"| node_remote
node_metrics -->|"batches reports"| node_livebatch
node_agent -->|"reports outbound"| node_wsagent
node_wsagent -->|"passes batches"| node_ingest
node_ingest -->|"persists batches"| node_ingestqueries
node_ingestqueries -->|"writes telemetry"| node_database
node_wsagent -->|"sends config and tasks"| node_agent
node_wsagent -->|"dispatches tasks"| node_remote
node_agent -->|"returns probe results"| node_probe
node_operator -->|"views dashboard"| node_frontendapp
node_frontendapp -->|"uses state"| node_provider
node_provider -->|"loads data"| node_api
node_api -->|"calls API"| node_server
node_server -->|"dispatches requests"| node_routes
node_server -->|"accepts agent socket"| node_wsagent
node_server -->|"accepts dashboard socket"| node_dashboardws
node_dashboardws -->|"streams live updates"| node_frontendapp
node_frontendapp -->|"shows latency history"| node_latencyui
node_latencyui -->|"fetches history"| node_api
node_routes -->|"reads and writes"| node_database
node_routes -->|"manages rules"| node_alertqueries
node_routes -->|"manages tasks"| node_latencyqueries
node_wsagent -->|"loads probe tasks"| node_latencyqueries
node_notify -->|"reads alert state"| node_database
node_notify -.->|"sends notifications"| node_telegram
node_routes -->|"uses authentication"| node_auth
node_auth -.->|"verifies challenge"| node_turnstile
node_admin -->|"configures services"| node_api
node_routes -->|"handles data operations"| node_backup
node_backup -->|"backs up and migrates"| node_database
node_server -->|"refreshes rates"| node_exchange
node_exchange -->|"stores rates"| node_database
node_exchange -.->|"external rate source"| node_telegram
node_probe -->|"uses telemetry types"| node_sharedtelemetry

click node_agent "https://github.com/elysia62/nodeflare/blob/main/agent/src/main.rs"
click node_metrics "https://github.com/elysia62/nodeflare/blob/main/agent/src/metrics.rs"
click node_probe "https://github.com/elysia62/nodeflare/blob/main/agent/src/probe.rs"
click node_remote "https://github.com/elysia62/nodeflare/blob/main/agent/src/remote.rs"
click node_livebatch "https://github.com/elysia62/nodeflare/blob/main/agent/src/live_batch.rs"
click node_sharedtelemetry "https://github.com/elysia62/nodeflare/blob/main/shared/telemetry.rs"
click node_server "https://github.com/elysia62/nodeflare/blob/main/backend/src/main.rs"
click node_wsagent "https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/agent.rs"
click node_ingest "https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/ingest.rs"
click node_dashboardws "https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/dashboard.rs"
click node_routes "https://github.com/elysia62/nodeflare/blob/main/backend/src/routes/admin.rs"
click node_auth "https://github.com/elysia62/nodeflare/blob/main/backend/src/auth.rs"
click node_notify "https://github.com/elysia62/nodeflare/blob/main/backend/src/notify.rs"
click node_backup "https://github.com/elysia62/nodeflare/blob/main/backend/src/backup.rs"
click node_frontendapp "https://github.com/elysia62/nodeflare/blob/main/frontend/src/App.tsx"
click node_provider "https://github.com/elysia62/nodeflare/blob/main/frontend/src/AppProvider.tsx"
click node_api "https://github.com/elysia62/nodeflare/blob/main/frontend/src/api.ts"
click node_admin "https://github.com/elysia62/nodeflare/blob/main/frontend/src/adminRoutes.ts"
click node_latencyui "https://github.com/elysia62/nodeflare/blob/main/frontend/src/hooks/useNodeLatency.ts"
click node_database "https://github.com/elysia62/nodeflare/blob/main/backend/src/db/mod.rs"
click node_ingestqueries "https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/ingest.rs"
click node_alertqueries "https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/alerts.rs"
click node_latencyqueries "https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/latency.rs"
click node_exchange "https://github.com/elysia62/nodeflare/blob/main/backend/src/exchange.rs"

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,node_metrics,node_probe,node_remote,node_livebatch,node_sharedtelemetry,node_operator toneBlue
class node_server,node_wsagent,node_ingest,node_dashboardws,node_routes,node_auth,node_notify,node_backup toneAmber
class node_frontendapp,node_provider,node_api,node_admin,node_latencyui toneMint
class node_database,node_ingestqueries,node_alertqueries,node_latencyqueries toneRose
class node_exchange,node_host,node_telegram,node_turnstile toneIndigo
```

## Components

### Monitoring Agent

- [Agent runtime](https://github.com/elysia62/nodeflare/blob/main/agent/src/main.rs): `agent/src/main.rs`
- [System metrics](https://github.com/elysia62/nodeflare/blob/main/agent/src/metrics.rs): `agent/src/metrics.rs`
- [Latency probes](https://github.com/elysia62/nodeflare/blob/main/agent/src/probe.rs): `agent/src/probe.rs`
- [Remote execution](https://github.com/elysia62/nodeflare/blob/main/agent/src/remote.rs): `agent/src/remote.rs`
- [Live batching](https://github.com/elysia62/nodeflare/blob/main/agent/src/live_batch.rs): `agent/src/live_batch.rs`
- [Telemetry types](https://github.com/elysia62/nodeflare/blob/main/shared/telemetry.rs): `shared/telemetry.rs`

### Backend Services

- [HTTP application](https://github.com/elysia62/nodeflare/blob/main/backend/src/main.rs): `backend/src/main.rs`
- [Agent WebSocket](https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/agent.rs): `backend/src/websocket/agent.rs`
- [Telemetry ingestion](https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/ingest.rs): `backend/src/websocket/ingest.rs`
- [Dashboard WebSocket](https://github.com/elysia62/nodeflare/blob/main/backend/src/websocket/dashboard.rs): `backend/src/websocket/dashboard.rs`
- [API routes](https://github.com/elysia62/nodeflare/blob/main/backend/src/routes/admin.rs): `backend/src/routes/admin.rs`
- [Authentication](https://github.com/elysia62/nodeflare/blob/main/backend/src/auth.rs): `backend/src/auth.rs`
- [Alerts and notices](https://github.com/elysia62/nodeflare/blob/main/backend/src/notify.rs): `backend/src/notify.rs`
- [Backup and migration](https://github.com/elysia62/nodeflare/blob/main/backend/src/backup.rs): `backend/src/backup.rs`

### Web Dashboard

- [Dashboard UI](https://github.com/elysia62/nodeflare/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Application state](https://github.com/elysia62/nodeflare/blob/main/frontend/src/AppProvider.tsx): `frontend/src/AppProvider.tsx`
- [HTTP client](https://github.com/elysia62/nodeflare/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Admin console](https://github.com/elysia62/nodeflare/blob/main/frontend/src/adminRoutes.ts): `frontend/src/adminRoutes.ts`
- [Latency views](https://github.com/elysia62/nodeflare/blob/main/frontend/src/hooks/useNodeLatency.ts): `frontend/src/hooks/useNodeLatency.ts`

### Persistence

- [SQLite / PostgreSQL](https://github.com/elysia62/nodeflare/blob/main/backend/src/db/mod.rs): `backend/src/db/mod.rs`
- [Ingest and history](https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/ingest.rs): `backend/src/db/queries/ingest.rs`
- [Alert queries](https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/alerts.rs): `backend/src/db/queries/alerts.rs`
- [Latency queries](https://github.com/elysia62/nodeflare/blob/main/backend/src/db/queries/latency.rs): `backend/src/db/queries/latency.rs`

### External Services

- [Exchange rates](https://github.com/elysia62/nodeflare/blob/main/backend/src/exchange.rs): `backend/src/exchange.rs`

### Other components

- **Dashboard user**
- **Monitored host**
- **Telegram**
- **Cloudflare Turnstile**

## Connections

- Monitored host → System metrics: samples
- Agent runtime → System metrics: collects
- Agent runtime → Latency probes: executes tasks
- Agent runtime → Remote execution: runs commands
- System metrics → Live batching: batches reports
- Agent runtime → Agent WebSocket: reports outbound
- Agent WebSocket → Telemetry ingestion: passes batches
- Telemetry ingestion → Ingest and history: persists batches
- Ingest and history → SQLite / PostgreSQL: writes telemetry
- Agent WebSocket → Agent runtime: sends config and tasks
- Agent WebSocket → Remote execution: dispatches tasks
- Agent runtime → Latency probes: returns probe results
- Dashboard user → Dashboard UI: views dashboard
- Dashboard UI → Application state: uses state
- Application state → HTTP client: loads data
- HTTP client → HTTP application: calls API
- HTTP application → API routes: dispatches requests
- HTTP application → Agent WebSocket: accepts agent socket
- HTTP application → Dashboard WebSocket: accepts dashboard socket
- Dashboard WebSocket → Dashboard UI: streams live updates
- Dashboard UI → Latency views: shows latency history
- Latency views → HTTP client: fetches history
- API routes → SQLite / PostgreSQL: reads and writes
- API routes → Alert queries: manages rules
- API routes → Latency queries: manages tasks
- Agent WebSocket → Latency queries: loads probe tasks
- Alerts and notices → SQLite / PostgreSQL: reads alert state
- Alerts and notices → Telegram: sends notifications
- API routes → Authentication: uses authentication
- Authentication → Cloudflare Turnstile: verifies challenge
- Admin console → HTTP client: configures services
- API routes → Backup and migration: handles data operations
- Backup and migration → SQLite / PostgreSQL: backs up and migrates
- HTTP application → Exchange rates: refreshes rates
- Exchange rates → SQLite / PostgreSQL: stores rates
- Exchange rates → Telegram: external rate source
- Latency probes → Telemetry types: uses telemetry types