Dashboard Overview
FreeSDN opens to the Dashboard (/dashboard). Everything you do starts here: pick a site, find a module, and act on live data. This page explains the chrome that surrounds every page - the sidebar, the top bar, the Site selector - so you know where things are before you open the first module.
What the dashboard shows you
Section titled “What the dashboard shows you”The landing page is a customizable widget grid. Widgets cover:
- Sites - count and overall health
- Controllers - registered network/firewall/hypervisor controllers
- Devices - total managed and offline counts
- Cameras - feed count, online ratio
- Additional metric tiles you can add, remove, and drag to reposition
All data is API-driven. The grid re-fetches automatically and respects the global Site filter (see below), so scoping to a specific site narrows every widget to that site’s devices.
Use the Customize button (top-right of the dashboard) to enter drag-and-drop edit mode, and Reset to restore the default layout.
Global layout
Section titled “Global layout”Every page inside the application shares the same chrome: a collapsible left sidebar and a persistent top bar. A per-route error boundary keeps the sidebar and top bar visible even if a page component crashes.
Top bar
Section titled “Top bar”| Control | Location | What it does |
|---|---|---|
| Hamburger | Far left (mobile only) | Opens the sidebar drawer |
| Site Selector | Left of center | Scopes all pages to one site - the most important control in the app |
| Search / Command Palette | Center | Opens the command palette (also Ctrl+K / Cmd+K) |
| WebSocket status pill | Right cluster | Green = live; click to reconnect when offline |
| Language switcher | Right cluster | Switches the UI language (English, Spanish, Chinese) |
| Theme toggle | Right cluster | Cycles between light, dark, and system |
| Notifications bell | Right cluster | Opens the in-app notification drawer |
| User menu | Far right | Profile, change password, settings, logout |
Sidebar
Section titled “Sidebar”The sidebar collapses to 72 px (icons only) or expands to 256 px. On screens narrower than lg it becomes a drawer opened by the hamburger. A text filter at the top searches nav items live; the same data feeds the command palette.
After you visit five or more distinct routes, a Recent rail appears above the sections with your last-visited pages.
The footer holds a Settings link and the collapse toggle.
Global Site selector
Section titled “Global Site selector”The Site selector is the master scope control for the entire application. It lives in the top bar and its selection persists across browser sessions (stored in localStorage).
Two modes:
- All Sites - global view. Pages that aggregate across sites (Sites list, Users, Organizations, Notification Providers) are only available here. Some pages hide or redirect when you switch to All Sites.
- A specific site - every page filters to that site. The sidebar reveals site-only items (Topology, Discovery) and hides global-only items.
Each site in the dropdown shows a health dot:
| Dot color | Meaning |
|---|---|
| Gray | No devices registered |
| Green | All devices online |
| Yellow | Some devices offline |
| Red | Critical issues or fewer than 50 % of devices online |
The dropdown also shows the device count and offline count for each site. Type to search by name, city, or country. Manage Sites at the bottom navigates to /sites/.
Keyboard shortcut: Ctrl+Shift+S (Windows/Linux) or Cmd+Shift+S (macOS) toggles the dropdown open and closed.
Command palette and keyboard shortcuts
Section titled “Command palette and keyboard shortcuts”Press Ctrl+K (Cmd+K on macOS) to open the command palette. It searches every nav item - modules, admin pages, settings - and navigates directly.
Press ? inside the palette for a shortcut cheatsheet. g-prefixed shortcuts (e.g., g then h for Dashboard) are active anywhere in the app while you are logged in.
Sidebar navigation sections
Section titled “Sidebar navigation sections”The sidebar groups pages into eight sections. Items are hidden automatically when a module is disabled for your organization or when the site context is wrong (global vs. site-scoped). You will only see items your role permits.
Overview
Section titled “Overview”| Link | Route | Notes |
|---|---|---|
| Dashboard | / | The widget grid landing page |
| Sites | /sites/ | Global only - visible in “All Sites” mode |
| Health | /health/ | Platform health dashboard (5 tabs) |
| Topology | /topology/ | Site only - interactive xyflow network map |
Network
Section titled “Network”Gated by the Network module. Includes switch port management, VLANs, access points, Wi-Fi SSIDs, clients, PoE, VPN, and firewall. Discovery (/discovery/) is site-only.
Cameras
Section titled “Cameras”Gated by the Video Surveillance module. Includes the camera grid, Camera Wall, NVRs, multi-camera synchronized playback, event review, and daily reports.
Gated by the VoIP & Telephony module. Includes phone fleet, PBX systems, extensions, call history, voicemail, provisioning templates, and VoIP discovery.
Infrastructure
Section titled “Infrastructure”| Link | Route | Module gate | Notes |
|---|---|---|---|
| Hypervisor | /hypervisor/ | hypervisor | Proxmox VE cluster management |
| Storage | /storage/ | None | Read-only TrueNAS health dashboard |
| Backups | /backups/ | backup | Config snapshot schedule + restore |
| Access Control | /access/ | access_control | Beta, off by default |
Operations
Section titled “Operations”Covers alert management (/alerts/), incidents (/incidents/), Observability / log collection (/collector/), log explorer (/collector/logs/), system audit logs (/logs/), analytics (/analytics/), SLA policies (/sla/), bulk operations (/bulk-operations/), device lifecycle (/lifecycle/), config reconciliation (/reconciliation/), and firmware lifecycle (/firmware/).
The Gateway controller-side feature pages (VPN, routing, firewall, diagnostics, hotspot, profiles, pending changes) also appear here when the Firewall module is enabled.
Automation
Section titled “Automation”| Link | Route | Notes |
|---|---|---|
| Fabric | /fabric/ | Universal app-interconnect visual builder |
| Automation Rules | /automation/ | CRUD rules + execution history |
| Alert Rules | /alert-rules/ | Threshold / pattern / anomaly alert engine |
| Notification Providers | /notification-providers/ | Global only |
| Webhooks | /webhooks/ | Webhook CRUD + delivery history |
| Integrations | /integrations/ | Guided typed integrations (n8n, Slack, PagerDuty) |
| Config Templates | /templates/ | Scope-based config template hierarchy |
| Site Groups | /groups/ | Org → Site Group → Sites and Device Groups |
| AI Assistant | /ai/ | Gated by the AI module |
Administration
Section titled “Administration”| Link | Route | Notes |
|---|---|---|
| Controllers | /controllers/ | Add/test/sync/delete network, firewall, and hypervisor controllers |
| Credentials | /credentials/ | Encrypted credential vault |
| Agents | /agents/ | Remote site agent management + scan dispatch |
| Agent Downloads | /agents/downloads/ | Windows/macOS/Linux installer links |
| Agent Releases | /agents/releases/ | Upload/manage agent binaries (gated agent:admin) |
| Users | /users/ | Global only; requires org_admin or super_admin role |
| Roles | /roles/ | Role + permission matrix; global only |
| Organizations | /organizations/ | Tenant management; global only |
| Security Audit | /security/ | Security events, audit logs, failed logins, IP blocks; gated audit:read |
| Plugins | /plugins/ | Manage installed third-party plugins; requires org_admin role (or plugins.admin permission); install requires super_admin |
| Marketplace | /marketplace/ | Browse and install Ed25519-signed plugins; install gated to super_admin |
| Drivers | /drivers/ | Read-only adapter/driver registry; global only |
Per-user profile and account controls
Section titled “Per-user profile and account controls”Click your name or avatar in the top-right user menu to access:
- Profile dialog - edit display name and username via
PATCH /auth/me(fields:full_name,username,language). Email can only be changed by an administrator viaPATCH /users/{id}- self-service email change is not available to regular users. - Change Password - enforces the platform password policy (12-character minimum, uppercase, lowercase, digit, special character)
- Delete Account - destructive; requires typing
DELETEto confirm - Settings - opens
/settings/ - Logout
MFA status appears in the profile dialog. Per-user TOTP setup and backup-code management are not available in Settings. The Enable / Manage button in the profile dialog navigates to /settings/security, but that route currently redirects to /settings/general rather than a functional MFA management page. The Settings to SSO tab (/settings/sso) covers organization-level identity-provider configuration, not per-user TOTP.
Theme and appearance
Section titled “Theme and appearance”The theme toggle in the top bar switches between light, dark, and system (follows OS preference). For persistent preference and accent-color presets, go to Settings → Appearance (/settings/appearance). You can also disable route-transition animations there if you prefer a faster feel.
Module enablement and what you see
Section titled “Module enablement and what you see”Every module-gated nav item disappears when the module is disabled for your organization. The page itself also enforces this via ModuleGuard: navigating directly to a disabled module’s URL shows a “Module Disabled” notice rather than an error.
Enable or disable modules at Settings → Modules (/settings/modules/). The setup wizard also lets you choose which modules to activate during first-run.
Notifications
Section titled “Notifications”The bell icon in the top bar opens the notification drawer. It has two tabs:
- Active - unread notifications with mark-as-read, dismiss, and a “Load more” paginator
- Archive - previously dismissed notifications
Clicking a notification navigates to its linked page. Mark all read clears the unread badge. Notification delivery channels and severity thresholds are managed at Settings → Notifications.
The sidebar Alerts item carries its own badge aggregating security events, firing alert rules, and open incidents. The badge dropdown lets you filter by source and minimum severity, and offers a “mark all reviewed” action.
Next steps
Section titled “Next steps”- First time here? Follow the Quick Start guide to run the setup wizard and register your first controller.
- Add a site - go to
/sites/and create a site, then use the Site selector to scope to it. - Enable modules - visit
/settings/modules/to turn on the features your deployment needs. - Explore a module - choose a section in the sidebar and open the relevant module reference page in Modules.
- Register agents - for L2/L3 network discovery, see the Agent guide.
- Automate workflows - see Automation & Fabric to wire events to actions.