Product design, React interface, Node.js BFF, IPC integration, service hardening, tests, and delivery automation.
Project case study
Working integration · Active developmentReact · Node.js · Express · SSE · Unix IPC
Focal Control Center
A browser-based operations console that makes FocalDesk health, services, sessions, displays, GPU state, and logs visible—without turning the browser into an unrestricted desktop control plane.
Responsive operations UI, read-oriented REST surface, live event stream, validated Unix-socket transport, and simulator.
Runs against the authenticated FocalDesk telemetry socket or switches safely to simulated data for isolated development.
The challenge
Expose useful operations data without exposing desktop authority.
A desktop control center needs enough context to explain what is happening across the compositor, session, rendering, credentials, notifications, and AI services. A browser, however, is the wrong place to receive raw privileged IPC or arbitrary command execution.
Focal Control Center puts a deliberately narrow backend-for-frontend between those worlds. The BFF subscribes to a private diagnostics socket, validates every snapshot, exposes a small read-oriented API, and pushes updates to the React interface through one-way Server-Sent Events.
System design
A narrow bridge from trusted IPC to a browser-safe view.
The browser never connects to FocalDesk services directly. The Express BFF owns transport, validation, transformation, reconnect behavior, static delivery, and response security headers.
BrowserReact dashboardResponsive operations UI
REST + SSERead-oriented
Safety boundaryExpress BFFValidate · reshape · stream
FocalDesk v1Unix socket
Desktop servicefocaldesk-serverAuthenticated telemetry
No raw desktop IPC
The adapter accepts only versioned, schema-valid snapshot envelopes and never forwards raw socket frames to the client.
One-way event streaming
SSE delivers snapshots and logs with heartbeats while avoiding a general browser-to-service command channel.
Safe simulator fallback
When the socket is unavailable, realistic local telemetry keeps UI work unblocked while the adapter continues trying to reconnect.
Engineering decisions
Keep the interface useful and the authority intentionally small.
The architecture favors an observable, testable data path over a broad administration API. Every added capability must fit the same local, validated, least-authority model.
A BFF instead of direct service calls
- Constraint
- FocalDesk IPC types and transport details should not become a public browser contract.
- Decision
- Expose focused health, overview, service, log, configuration, and stream endpoints from a small Express process.
- Tradeoff
- The BFF is another process to package and supervise, but it isolates protocol change and keeps privileged transport out of the UI.
Schemas at both boundaries
- Constraint
- Both browser input and service telemetry can be malformed, oversized, stale, or outside expected ranges.
- Decision
- Use strict Zod schemas, bounded arrays and strings, allowlisted preferences, capped JSON bodies, and versioned envelopes.
- Tradeoff
- Protocol evolution requires coordinated schema updates, but unexpected data cannot silently become trusted UI state.
One production process
- Constraint
- The packaged console needs a predictable local origin, simple service lifecycle, and no development proxy.
- Decision
- Build the React application with Vite and serve its static output and API from the same compressed Express server.
- Tradeoff
- The BFF serves frontend assets as well as data, but deployment becomes one loopback-only user service.
A constrained systemd user unit
- Constraint
- A diagnostics process should not inherit broad filesystem or privilege access merely because it runs inside a desktop session.
- Decision
- Bind to loopback and use
NoNewPrivileges, private temporary storage, strict system protection, read-only home access, and a restrictive umask. - Tradeoff
- The service requires an explicit installation path and socket allowance, but its operating boundary is visible and reviewable.
Engineering deep dive
Live telemetry survives a missing or restarting desktop service.
At startup, the adapter checks for the private control-center socket. If available, it sends one versioned subscription request and consumes newline-delimited snapshots. If the connection closes, it returns to simulation and schedules a reconnect instead of leaving the dashboard frozen or crashing the web process.
The React client first loads a complete overview, then opens one SSE stream for snapshots and log events. Connection state remains visible as “Live” or “Demo data,” so fallback behavior is explicit to the user.
Request a bounded snapshot interval.
The adapter sends a FocalDesk v1 subscription envelope over the local Unix socket.
Accept only complete known telemetry shapes.
System, health, metrics, session, display, GPU, service, log, AI, and credential fields are range- and size-checked.
Translate snapshots into browser events.
The BFF sends named SSE events and heartbeats, then removes listeners when a client disconnects.
Fall back visibly and reconnect automatically.
The simulator maintains a useful interface during service development without pretending that its data is live.
Repository evidence · August 2026
Small surfaces make the boundary easier to test and review.
The current implementation stays intentionally compact. The figures below describe explicit limits and automation visible in the source, not estimates of future functionality.
Health, overview, services, filtered logs, configuration read/write, and the live SSE stream.
Browser requests are capped before strict configuration validation is applied.
Oversized newline-delimited frames are discarded before their contents can reach the browser.
CI builds and runs four server/adapter tests; CodeQL analyzes JavaScript on changes and weekly.
Where it stands
A focused diagnostics surface, not a remote shell.
The console is useful today for understanding a local FocalDesk session. Its limitations are part of the security design: it reports service health without exposing secrets or accepting arbitrary system actions.
Implemented
- System, session, display, GPU, and service overview
- Searchable, level-filtered live logs
- Real-time snapshots and log events over SSE
- Authenticated FocalDesk diagnostics socket integration
- Simulator fallback with automatic reconnect
- Strict telemetry and preference validation
- Responsive interface and hardened user service
Deliberately excluded or bounded
- No shell-command execution endpoint
- No raw IPC frames exposed to the browser
- No browser-to-service general command channel
- No credential names or secret values in telemetry
- Configuration limited to allowlisted console preferences
- Loopback-only HTTP server by default
Go deeper
Read the integration and security details.
The repository documents local development, production installation, IPC envelopes, API routes, hardening, and automated checks.