# ivelytechnologies/se_ively_edge architecture

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

- Interactive diagram: https://gitdiagram.com/ivelytechnologies/se_ively_edge
- Repository: https://github.com/ivelytechnologies/se_ively_edge

## Overview

Ively Edge SmartEye provisions a camera-connected edge device, then discovers cameras, generates MediaMTX paths, and runs persistent FFmpeg workers that publish streams for local viewing and cloud/AI access. The agent supervises stream health, exposes device health, and reports status to the cloud over WebSocket; WireGuard, OTA, diagnostics, and encrypted credentials provide supporting capabilities. Relationships below use README statements and SOURCE INDEX references; unsampled implementation details are omitted where their wiring is not established.

Main entry points: [`agent/main.py`](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/main.py) (Agent runtime), [`agent/camera/pipeline.py`](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/pipeline.py) (Camera config pipeline), [`agent/camera/worker_reload.py`](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/worker_reload.py) (Worker reload), [`agent/camera/discover.py`](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/discover.py) (Camera discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Provisioning and discovery"]
  node_provision_ui["Provision UI<br/>[main.py]"]
  node_discovery["Camera discovery<br/>[discover.py]"]
  node_onvif["ONVIF scanning<br/>[onvif_scan.py]"]
  node_camera_config["Camera config pipeline<br/>[pipeline.py]"]
  node_config["Device configuration<br/>[config.py]"]
end

subgraph group_streaming["Camera streaming"]
  node_mtx_writer["MediaMTX config writer<br/>[mediamtx_writer.py]"]
  node_mediamtx["MediaMTX"]
  node_worker_reload["Worker reload<br/>[worker_reload.py]"]
  node_camera_workers["FFmpeg camera workers<br/>[camera_worker.py]"]
  node_recovery["Stream recovery<br/>[stream_recovery.py]"]
end

subgraph group_operations["Agent operations"]
  node_agent_main["Agent runtime<br/>[main.py]"]
  node_health["Health API<br/>[health.py]"]
  node_metrics[("Metrics collection<br/>[metrics.py]")]
  node_watchdog["Watchdog<br/>[watchdog.py]"]
end

subgraph group_connectivity["Cloud and security"]
  node_ws["Cloud WebSocket<br/>[ws_client.py]"]
  node_commands["Cloud command dispatch<br/>[commands.py]"]
  node_wireguard["WireGuard tunnel<br/>[client.py]"]
  node_wg_keys["WireGuard keys<br/>[keys.py]"]
  node_vault["Credential vault<br/>[vault.py]"]
  node_ota["OTA updater<br/>[updater.py]"]
end

node_operator(("Device operator"))
node_cameras["IP cameras / NVR"]
node_cloud["Ively cloud"]

node_operator -->|"submits setup"| node_provision_ui
node_provision_ui -->|"registers device"| node_cloud
node_provision_ui -->|"applies camera config"| node_camera_config
node_provision_ui -->|"scans cameras"| node_discovery
node_cameras -->|"provides camera feeds"| node_discovery
node_discovery -->|"uses ONVIF scan"| node_onvif
node_discovery -->|"provides camera list"| node_camera_config
node_camera_config -->|"generates paths"| node_mtx_writer
node_camera_config -->|"uses settings"| node_config
node_camera_config -->|"restarts service"| node_mediamtx
node_worker_reload -->|"generates worker configs"| node_mtx_writer
node_worker_reload -->|"replaces workers"| node_camera_workers
node_worker_reload -->|"restarts service"| node_mediamtx
node_camera_workers -->|"publishes streams"| node_mediamtx
node_agent_main -->|"starts workers"| node_worker_reload
node_agent_main -->|"runs recovery loop"| node_recovery
node_agent_main -->|"collects metrics"| node_metrics
node_agent_main -->|"starts watchdog"| node_watchdog
node_agent_main -->|"starts health server"| node_health
node_agent_main -->|"starts cloud connection"| node_ws
node_recovery -->|"checks and restarts"| node_camera_workers
node_recovery -->|"checks path readiness"| node_mediamtx
node_health -->|"routes reload requests"| node_worker_reload
node_health -->|"reads metrics"| node_metrics
node_ws -->|"sends heartbeat"| node_cloud
node_ws -->|"dispatches commands"| node_commands
node_commands -->|"provisions tunnel"| node_wireguard
node_commands -->|"runs updates"| node_ota
node_wireguard -->|"loads keypair"| node_wg_keys
node_mtx_writer -->|"decrypts credentials"| node_vault
node_watchdog -->|"rediscovers cameras"| node_discovery
node_watchdog -->|"checks tunnel"| node_wireguard

click node_provision_ui "https://github.com/ivelytechnologies/se_ively_edge/blob/main/provision-ui/main.py"
click node_discovery "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/discover.py"
click node_onvif "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/onvif_scan.py"
click node_camera_config "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/pipeline.py"
click node_config "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/config.py"
click node_mtx_writer "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/mediamtx_writer.py"
click node_worker_reload "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/worker_reload.py"
click node_camera_workers "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/camera_worker.py"
click node_recovery "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/stream_recovery.py"
click node_agent_main "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/main.py"
click node_health "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/health.py"
click node_metrics "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/metrics.py"
click node_watchdog "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/watchdog.py"
click node_ws "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/ws_client.py"
click node_commands "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/commands.py"
click node_wireguard "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/wireguard/client.py"
click node_wg_keys "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/wireguard/keys.py"
click node_vault "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/security/vault.py"
click node_ota "https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/ota/updater.py"

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_provision_ui,node_discovery,node_onvif,node_camera_config,node_config toneBlue
class node_mtx_writer,node_mediamtx,node_worker_reload,node_camera_workers,node_recovery toneAmber
class node_agent_main,node_health,node_metrics,node_watchdog toneMint
class node_ws,node_commands,node_wireguard,node_wg_keys,node_vault,node_ota toneRose
class node_operator,node_cameras,node_cloud toneIndigo
```

## Components

### Provisioning and discovery

- [Provision UI](https://github.com/ivelytechnologies/se_ively_edge/blob/main/provision-ui/main.py): `provision-ui/main.py`
- [Camera discovery](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/discover.py): `agent/camera/discover.py`
- [ONVIF scanning](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/onvif_scan.py): `agent/camera/onvif_scan.py`
- [Camera config pipeline](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/pipeline.py): `agent/camera/pipeline.py`
- [Device configuration](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/config.py): `agent/config.py`

### Camera streaming

- [MediaMTX config writer](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/mediamtx_writer.py): `agent/camera/mediamtx_writer.py`
- **MediaMTX**
- [Worker reload](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/worker_reload.py): `agent/camera/worker_reload.py`
- [FFmpeg camera workers](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/camera_worker.py): `agent/camera/camera_worker.py`
- [Stream recovery](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/camera/stream_recovery.py): `agent/camera/stream_recovery.py`

### Agent operations

- [Agent runtime](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/main.py): `agent/main.py`
- [Health API](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/health.py): `agent/health.py`
- [Metrics collection](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/metrics.py): `agent/metrics.py`
- [Watchdog](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/watchdog.py): `agent/watchdog.py`

### Cloud and security

- [Cloud WebSocket](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/ws_client.py): `agent/ws_client.py`
- [Cloud command dispatch](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/commands.py): `agent/commands.py`
- [WireGuard tunnel](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/wireguard/client.py): `agent/wireguard/client.py`
- [WireGuard keys](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/wireguard/keys.py): `agent/wireguard/keys.py`
- [Credential vault](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/security/vault.py): `agent/security/vault.py`
- [OTA updater](https://github.com/ivelytechnologies/se_ively_edge/blob/main/agent/ota/updater.py): `agent/ota/updater.py`

### Other components

- **Device operator**
- **IP cameras / NVR**
- **Ively cloud**

## Connections

- Device operator → Provision UI: submits setup (evidence: `README.md`)
- Provision UI → Ively cloud: registers device (evidence: `README.md`)
- Provision UI → Camera config pipeline: applies camera config (evidence: `provision-ui/main.py`)
- Provision UI → Camera discovery: scans cameras (evidence: `provision-ui/main.py`)
- IP cameras / NVR → Camera discovery: provides camera feeds (evidence: `README.md`)
- Camera discovery → ONVIF scanning: uses ONVIF scan (evidence: `agent/camera/discover.py`)
- Camera discovery → Camera config pipeline: provides camera list (evidence: `agent/camera/discover.py`)
- Camera config pipeline → MediaMTX config writer: generates paths (evidence: `agent/camera/pipeline.py`)
- Camera config pipeline → Device configuration: uses settings (evidence: `agent/camera/pipeline.py`)
- Camera config pipeline → MediaMTX: restarts service (evidence: `agent/camera/pipeline.py`)
- Worker reload → MediaMTX config writer: generates worker configs (evidence: `agent/camera/worker_reload.py`)
- Worker reload → FFmpeg camera workers: replaces workers (evidence: `agent/camera/worker_reload.py`)
- Worker reload → MediaMTX: restarts service (evidence: `agent/camera/worker_reload.py`)
- FFmpeg camera workers → MediaMTX: publishes streams (evidence: `README.md`)
- Agent runtime → Worker reload: starts workers (evidence: `agent/main.py`)
- Agent runtime → Stream recovery: runs recovery loop (evidence: `agent/main.py`)
- Agent runtime → Metrics collection: collects metrics (evidence: `agent/main.py`)
- Agent runtime → Watchdog: starts watchdog (evidence: `agent/main.py`)
- Agent runtime → Health API: starts health server (evidence: `agent/main.py`)
- Agent runtime → Cloud WebSocket: starts cloud connection (evidence: `agent/main.py`)
- Stream recovery → FFmpeg camera workers: checks and restarts (evidence: `agent/camera/stream_recovery.py`)
- Stream recovery → MediaMTX: checks path readiness (evidence: `agent/camera/stream_recovery.py`)
- Health API → Worker reload: routes reload requests (evidence: `agent/health.py`)
- Health API → Metrics collection: reads metrics (evidence: `agent/health.py`)
- Cloud WebSocket → Ively cloud: sends heartbeat (evidence: `README.md`)
- Cloud WebSocket → Cloud command dispatch: dispatches commands (evidence: `agent/ws_client.py`)
- Cloud command dispatch → WireGuard tunnel: provisions tunnel (evidence: `agent/commands.py`)
- Cloud command dispatch → OTA updater: runs updates (evidence: `agent/commands.py`)
- WireGuard tunnel → WireGuard keys: loads keypair (evidence: `agent/wireguard/client.py`)
- MediaMTX config writer → Credential vault: decrypts credentials (evidence: `agent/camera/mediamtx_writer.py`)
- Watchdog → Camera discovery: rediscovers cameras (evidence: `agent/watchdog.py`)
- Watchdog → WireGuard tunnel: checks tunnel (evidence: `agent/watchdog.py`)
