Dashboards & Navigation

The FreeSDN UI is a single-page React application. Every page shares a persistent sidebar and top bar that give you site context, search, alerts, and notifications without leaving your current view. This guide walks through that chrome, the main dashboard, and the entry points into each module.

Global layout

When you log in you land on the dashboard. The page wraps in two persistent elements:

Sidebar - left-hand navigation, collapsible to 72 px icons or expanded to 256 px. On mobile it becomes a full-width drawer.
Top bar - site selector on the left, command palette trigger in the centre, and status/settings controls on the right.

A Skip to content link is always the first focusable element (keyboard / screen-reader users: press Tab immediately after page load).

If a page crashes, the sidebar and top bar stay visible and the error boundary resets automatically when you navigate away.

Site selector

The site selector is the most important context control in the app. It sits at the left edge of the top bar. Every query on every page respects the value you choose here.

Choice	Meaning
All Sites	Global view - aggregate data across the whole organisation. Some nav items (Topology, Discovery) are hidden in this mode.
A specific site	Scoped view - data filtered to that site. Global-only pages (Users, Roles, Organisations) are hidden.

Each site entry shows a coloured health dot:

Dot	Meaning
Green	All devices online
Yellow	Some devices offline
Red	Critical state or fewer than 50 % of devices online
Grey	No devices registered

The dropdown also shows device count and offline count. Type to filter by name, city, or country. Footer link goes to /sites/.

Keyboard shortcut: Ctrl+Shift+S (Windows/Linux) or Cmd+Shift+S (macOS) opens the site-selector dropdown from anywhere.

Command palette

Press Ctrl+K (or Cmd+K on macOS) from anywhere in the authenticated app to open the command palette. It searches all sidebar navigation entries from a single shared source of truth - the same list that drives the sidebar.

Press ? inside the palette to see all keyboard shortcuts. The g prefix shortcuts (for example g h for Dashboard or g d for Devices) are available globally when authenticated.

Top bar controls

From left to right on the right side of the top bar:

Control	What it does
WebSocket status pill	Shows live or offline. Click when offline to trigger a reconnect. All real-time updates - scan progress, camera events, device state changes - depend on this connection.
Language switcher	Toggle UI language (English, Spanish, Chinese; others removed).
Theme toggle	Light / dark / system.
Notifications bell	In-app notification drawer (see below).
User menu	Profile, change password, settings, logout.

Notifications drawer

Click the bell to open the drawer. It has two tabs: Active (unread/pending) and Archive.

Unread items show a badge count on the bell icon.
Click Mark all read to clear the badge without opening each item.
Click a notification row to navigate to its linked resource.
Use Load more to page through older entries.
The drawer is backed by GET /notifications/in-app (list) and POST /notifications/in-app/mark (mark read/dismissed).

The user menu lets you update your email, change your password, and view your MFA status. Your display name is shown read-only. The Profile dialog shows your current MFA status and an Enable/Manage button, but clicking it navigates to /settings/security - see the note below regarding MFA management.

To delete your account: open the user menu → Profile → Delete Account, then type DELETE to confirm. This action is irreversible.

Alerts badge

The sidebar Alerts item carries a live badge aggregating:

Firing alert-rule alerts
Correlation incidents
Security events

Click the badge number pill (or hover over the Alerts item to reveal the settings icon) to open the dropdown and:

Filter by source (rule alerts / incidents / security events)
Set a minimum severity threshold
Mark all reviewed (clears the badge)

The count resets when you acknowledge or resolve the underlying items on the /alerts/ page.

Main dashboard

Route: / or /dashboard

The dashboard is the landing page after login. It is a drag-and-drop widget grid (powered by dnd-kit) showing live stats pulled from the API. The default widget set (shown on first login) includes:

Network Traffic - aggregate upload / download over the last 24 h
Active Alerts - open alerts across all configured rules
Device Status - online / offline / warning device counts
Network Health - latency, throughput, packet loss, and uptime
Quick Actions - shortcuts for discovery, backups, and provisioning
Camera Overview - live thumbnails of your most recent cameras
Recent Activity - stream of recent alerts and notable events

Additional widgets are available via the Customize picker, grouped by category (Overview, Performance, Security, Network, System): Site Health Map, Incident Overview, Top CPU Consumers, Top Memory Consumers, Port Status, Security Posture, Audit Activity, Wi-Fi Band Mix, Top SSIDs, Manufacturer Mix, PoE Power Budget, and System Status.

Click Customize to add, remove, or rearrange widgets. Click Reset to restore the default layout. The dashboard honours the global site filter - switch to a specific site to scope the numbers.

The sidebar is organised into sections. Items with a moduleId gate are hidden automatically when that module is disabled for your organisation. Items marked global only appear when “All Sites” is selected; items marked site only appear when a specific site is selected.

Overview

Item	Route	Notes
Dashboard	`/`	Always visible.
Sites	`/sites/`	Global only.
Health	`/health/`	5-tab health dashboard (Overview, Devices, Alerts & SLA, Infrastructure, Score Info).
Topology	`/topology/`	Site only. Interactive network topology (xyflow) with zoom, minimap, layout algorithms, PNG export.

Network (requires Network module)

Item	Route
Network Overview	`/network/`
Devices	`/devices/`
Switches	`/switches/`
Access Points	`/access-points/`
VLANs	`/vlans/`
WiFi Networks	`/wifi/`
Clients	`/network/clients/`
PoE	`/poe/`
VPN	`/vpn/`
Firewall	`/firewall/`
Discovery	`/discovery/` (site only)

Cameras (requires Cameras module)

Item	Route
Cameras	`/cameras/`
Camera Wall	`/cameras/wall/`
NVRs	`/cameras/nvrs/`
Multi-Playback	`/cameras/playback/`

VoIP (requires VoIP module)

Item	Route
Fleet Overview	`/voip/`
PBX Systems	`/voip/pbx/`
Phones	`/voip/phones/`
Extensions	`/voip/extensions/`
Call History	`/voip/calls/`
Voicemail	`/voip/voicemail/`
Phone Templates	`/voip/templates/`
Phone Discovery	`/voip/discovery/`

Infrastructure

Item	Route	Notes
Hypervisor	`/hypervisor/`	Requires Hypervisor module + a Proxmox controller.
Storage	`/storage/`	Read-only TrueNAS health dashboard. Requires a TrueNAS controller registered.
Backups	`/backups/`	Requires Backup module.
Access Control	`/access/`	Placeholder page, no functional UI.

Operations

Item	Route
Alerts	`/alerts/`
Incidents	`/incidents/`
Observability	`/collector/`
Log Explorer	`/collector/logs/`
System Logs	`/logs/`
Analytics	`/analytics/`
SLA	`/sla/`
Bulk Operations	`/bulk-operations/`
Device Lifecycle	`/lifecycle/`
Reconciliation	`/reconciliation/`
Firmware	`/firmware/`
Gateway sub-pages	`/gateway/*` (see Firewall & Gateway)

Automation

Item	Route
Fabric	`/fabric/`
Automation Rules	`/automation/`
Alert Rules	`/alert-rules/`
Notification Providers	`/notification-providers/` (global only)
Webhooks	`/webhooks/`
Integrations	`/integrations/`
Config Templates	`/templates/`
Site Groups	`/groups/`
AI Assistant	`/ai/` (requires AI module)

Administration

Item	Route	Permission required
Controllers	`/controllers/`	-
Credentials	`/credentials/`	`settings:read`
Agents	`/agents/`	-
Agent Downloads	`/agents/downloads/`	-
Agent Releases	`/agents/releases/`	`agent:admin`
Users	`/users/` (global only)	`user:read`
Roles	`/roles/` (global only)	`role:read`
Organisations	`/organizations/` (global only)	`organization:read`
Security Audit	`/security/`	`audit:read`
Plugins	`/plugins/`	`settings:admin`
Marketplace	`/marketplace/`	`settings:admin`
Drivers	`/drivers/` (global only)	-

Health dashboard

Route: /health/

The health dashboard gives a scored, multi-dimension picture of your infrastructure. It has five tabs:

Tab	Contents
Overview	Health score gauges, module health grid, top issues list, site ranking.
Devices	Per-device health table with status, last-seen, and health indicators.
Alerts & SLA	Firing alerts, SLA card, breach summary.
Infrastructure	WAN status, Valkey, database, worker health panels.
Score Info	Explanation of how the score is calculated.

The overview tab aggregates signals from all enabled modules. Use the site selector to focus the score on one site or keep “All Sites” for an org-wide picture.

Alerts console

Route: /alerts/

The alerts console is the central place to review and act on everything that needs attention. It has four deep-link tabs:

Tab	Route	Contents
Alerts	`/alerts/`	Threshold / pattern / anomaly rule alerts.
Rules	`/alerts/rules/`	Alert rule configuration - see also `/alert-rules/`.
Incidents	`/alerts/incidents/`	Correlation incidents with assignment.
Security	`/alerts/security/`	Security events (failed logins, IP blocks, anomalies).

All four support free-text search, severity filtering, status filtering, and bulk actions (acknowledge, resolve, suppress, mark all read).

The detailed security event history and audit log are at /security/ (requires audit:read).

Analytics

Route: /analytics/

Analytics pulls fleet-wide and site-scoped metrics from /api/v1/analytics/dashboard/enterprise. Tabs:

Tab	What you see
Overview	Top-level KPIs.
Insights	Anomaly and trend callouts.
WiFi	SSID utilisation, channel distribution, RF health trends.
Clients	Client count trends, top clients, roaming events.
Traffic	Interface throughput, top talkers.

Use the time-range selector (1 day / 1 week / 1 month) and the site selector together to narrow the scope.

Cross-site comparison at /analytics/sites-comparison/ ranks every site side by side and calls out the worst performers. Backed by GET /api/v1/analytics/sites/comparison.

Log explorer and system logs

Route	Purpose
`/collector/logs/`	Log explorer - search and filter raw syslog, SNMP trap, and NetFlow records ingested by the Observability module. Supports time-range picker, filter bar, expandable row detail, and CSV export.
`/logs/`	System logs - unified chronological stream of audit events and security events generated by the platform itself (not device telemetry). Tabs: Overview (KPIs, charts, needs-attention) and All Logs (search, filters, live tail, export).
`/security/`	Security audit - focused view of security events, failed logins, blocked IPs, and anomaly detections. Requires `audit:read`.

Observability (Collector)

Route: /collector/

The Observability page shows the status of the three passive listener services:

SNMP trap receiver (UDP)
Syslog receiver (RFC 3164 / 5424, UDP)
NetFlow receiver (v5 / v9, UDP)

Each service card shows running/stopped status, event counts, and error rate. The live event stream displays the last 50 received events in real time. The config panel lets you change listen ports and enable/disable each receiver without restarting the container.

Fabric cockpit

Route: /fabric/

Fabric is FreeSDN’s universal app-interconnect: any event source can drive any operation target, across modules, without writing code. The Fabric page is a visual builder where you:

Browse the catalog - event sources and operation targets contributed by all enabled modules and installed plugins, each tagged with their tier (native vs plugin).
Author Connections - a source event triggers a step chain that can call operations, send notifications, write to webhooks, or invoke AI tools.
Monitor run history - see which connections fired, what they did, and whether each step succeeded.

Writes through Fabric always go through the standard staged dual-gate. Operations marked with a lock icon require explicit operator sign-off before they touch a live device.

The catalog is also available directly at GET /api/v1/fabric/catalog. FreeSDN ships an n8n community node (n8n-nodes-freesdn) if you prefer to author flows in n8n rather than the built-in builder.

Settings

Route: /settings/ (redirects to /settings/general/)

Requires settings:read. The settings area uses a left-sidebar tab layout. Valid tabs:

Tab	Contents
`general`	Org name, description, timezone, date format, language.
`appearance`	Theme (light / dark / system), accent colour presets, animation toggle.
`sso`	OIDC and LDAP identity-provider CRUD. (SAML is disabled - 501-gated.)
`api-keys`	Create, view, and revoke scoped API keys. The full key is shown only once at creation.
`oauth2-apps`	Register OAuth 2.0 applications for the auth-code flow.
`ai`	Configure OpenAI, Anthropic, and Ollama providers: API keys, base URLs, default models, and connectivity test.
`notifications`	Severity thresholds, quiet hours, per-category × per-channel subscription matrix, digest settings.
`modules`	Enable or disable modules per organisation. Links to per-module detail pages.
`system`	Live infrastructure health: platform and library versions, PostgreSQL, Valkey, Celery workers, uptime, route and adapter counts.

Permission gates summary

The table below summarises which pages require explicit permissions beyond being authenticated. Most pages only require the user to have a role with access to the relevant module.

Route prefix	Minimum permission
`/organizations/*`	`organization:read`
`/users/`	`user:read`
`/roles/`	`role:read`
`/settings/*`, `/credentials/`	`settings:read`
`/plugins/`, `/marketplace/`	`settings:admin`
`/bulk-operations/`	`device:update`
`/security/`	`audit:read`
`/agents/releases/`	`agent:admin`

If you land on /unauthorized/, your role does not have the required permission. Contact your org admin or super_admin to adjust your role assignment.

Common workflows

Investigate an alert end-to-end

Notice the badge count on Alerts in the sidebar.
Go to /alerts/ and filter by Critical severity.
Click the alert row to open the detail dialog - note the device, site, and triggering metric.
Use the site selector to scope to that site.
Navigate to the relevant module page (for example /switches/ for a port-down alert).
Locate the device, open its detail page, and check the Logs tab for correlated events.
Take remedial action (reboot, re-enable port, etc.) from the device detail page.
Return to /alerts/ and Resolve the alert.

Check infrastructure health before a maintenance window

Go to /health/ and review the overall score.
Switch to the Infrastructure tab to confirm Valkey, database, and worker status.
Switch to the Alerts & SLA tab to confirm no active SLA breaches.
Open /analytics/ → Traffic tab and note baseline throughput.
Open /logs/ to confirm no recent anomalous events.

Find a device quickly

Press Ctrl+K to open the command palette and navigate to any top-level page. Recently visited nav sections appear at the top when the input is empty. To find a specific device by hostname or IP, go to /devices/ and use the search toolbar.

Review what changes are pending before pushing to a controller

Go to /gateway/pending/. This page aggregates all staged writes across VPN, firmware, profiles, firewall, and WiFi - everything that has been authored in the UI but not yet pushed to the live controller. Discard any changes you do not want, then apply the rest.

Honesty caveats

Next steps

Sites & Controllers - set up sites and register your first controller.
Devices & Discovery - run your first discovery scan and adopt devices.
Network Management - switches, VLANs, access points, and wireless.
Firewall & Gateway - rules, NAT, VPN, and gateway orchestration.
Alerts & Automation - configure alert rules, Fabric connections, and notification providers.