BFF Proxy Architecture
Architecture Overview: The BFF Proxy
The Unifi Dashboard utilizes a Backend-for-Frontend (BFF) pattern. Instead of the browser communicating directly with the UniFi API, all requests are routed through a lightweight Node.js/Express intermediary. This architectural choice addresses two critical challenges in modern web development: security and cross-origin resource sharing (CORS).
Why use a BFF?
- Security (Secret Management): UniFi API keys are sensitive credentials. By using a BFF, the API key is stored securely on the server (via environment variables) and never exposed to the client side. The browser only sees your local dashboard URL, keeping your UniFi infrastructure credentials private.
- CORS Bypass: The UniFi API often enforces strict Cross-Origin Resource Sharing (CORS) policies that prevent browser-based JavaScript from making direct requests. The BFF acts as a proxy, performing server-to-server communication with UniFi and returning the data to the frontend seamlessly.
- Request Simplification: The server handles the header injection (such as
X-API-KEY) and error mapping, allowing the frontend to remain a simple, logic-light "Vanilla JS" application.
Proxy Endpoints
The BFF exposes a clean REST interface for the frontend. All proxy routes are prefixed with /api.
| Endpoint | Method | Description |
| :--- | :--- | :--- |
| /api/sites | GET | Retrieves a list of all sites managed by the UniFi controller. |
| /api/sites/:siteId/devices | GET | Fetches device status (APs, Switches, Gateways) for a specific site. |
| /api/sites/:siteId/clients | GET | Fetches the current active client list for a specific site. |
Usage Example
To fetch data within the application, the frontend makes a standard fetch call to the local relative path:
// The BFF handles the API key and UniFi URL internally
const response = await fetch('/api/sites');
const sites = await response.json();
Configuration & Environment
The BFF is configured via environment variables, typically managed through a .env file or Docker environment settings. This ensures that the application remains portable across different environments without modifying the source code.
| Variable | Description | Requirement |
| :--- | :--- | :--- |
| UNIFI_API_KEY | Your UniFi Personal Access Token or API Key. | Required |
| UNIFI_API_URL | The base URL for your UniFi Network API (e.g., https://host.com/proxy/network/integration/v1). | Required |
| PORT | The port the dashboard server will run on (Default: 3000). | Optional |
Server-Side Validation
Upon startup, the BFF performs a health check on these variables. If the UNIFI_API_KEY or UNIFI_API_URL is missing, the process will log a descriptive error and exit to prevent silent failures.
Deployment Considerations
When deploying via Docker, the BFF and the frontend are bundled into a single container. The Express server serves the static assets (index.html, app.js, style.css) while simultaneously acting as the API proxy. This results in a zero-configuration experience for the browser, as the frontend automatically knows to reach out to the same host for its data requirements.