pouzor/homelable

1. System shape

Homelable is a three-part system: a Python backend API, a TypeScript/React frontend, and an optional MCP server for AI tooling. The backend is the authoritative source for canvas state, discovery results, node health, and Zigbee imports; the frontend is the interactive editor and viewer.

2. Backend API boundary

The backend is organized as a FastAPI-style service with route groups for auth, canvas, nodes, edges, designs, scan, status, stats, settings, liveview, and zigbee. That separation maps directly to the main product areas: editing the diagram, discovering devices, monitoring status, and serving read-only/public views.

3. Persistence layer

Backend persistence is centralized under backend/app/db, with ORM models and a database module. The stored domain appears to include nodes, edges, designs/themes, scan history, pending devices, settings, and Zigbee-related metadata. The canvas editor and operational features both read and write through this shared database.

4. Discovery pipeline

Network discovery is driven by the backend’s scanner service and the scan routes. The scanner runs nmap -sV --open against configured CIDR ranges, then uses a fingerprinting service backed by backend/app/data/service_signatures.json to identify services. Discovered devices are written into a Pending Devices queue rather than immediately merged into the canvas.

5. Scan-to-canvas workflow

The scan flow is asynchronous from the user’s perspective: the UI triggers a scan, the backend tracks it, and results appear in the frontend without restarting the service. Users then approve, hide, or ignore each pending device, which is the transition point from discovery data to permanent canvas objects.

6. Continuous status monitoring

Homelable has a separate health/status subsystem in status_checker plus a scheduler. This subsystem periodically checks nodes using methods like ping, TCP, HTTP/HTTPS, SSH, Prometheus, and /health, then stores and exposes the latest online/offline/unknown state. The frontend consumes this to color and annotate nodes on the canvas.

7. Zigbee import path

Zigbee support is handled as a distinct backend service and route group, with the UI providing an import modal. It connects to an MQTT broker, reads Zigbee2MQTT topology, classifies devices as coordinator/router/end device, and imports them onto the canvas with parent-child relationships and properties like LQI.

8. Frontend architecture

The frontend is a Vite-based React app with TypeScript, organized around a canvas editor, panels, modals, and stores. The main UI pieces are the canvas, sidebar, toolbar, detail panel, and multiple edit/import dialogs. State is split into dedicated stores for auth, canvas, design, and theme, which keeps the editor, dialogs, and export flows coordinated.

9. Client-side data transformations

A significant amount of presentation logic lives in the frontend utilities: serialization, export to PNG/Markdown/YAML, icon/color/theme selection, layout helpers, and import/export conversion. This means the frontend is not just rendering server data; it also shapes the diagram model, supports standalone design mode, and handles local export workflows.

10. Public/read-only surfaces

Two backend endpoints are intentionally exposed as limited read-only integrations: Live View for unauthenticated canvas viewing via a shared key, and stats/summary for gethomepage via an API key. These are separate from the authenticated editing API and are designed as narrow, controlled read-only boundaries.

11. MCP integration

The mcp service is a separate Python process that sits beside the backend. It authenticates AI clients with its own API key, then talks to the backend over an internal service key. Through this boundary it can read topology, list pending devices and scans, and also perform write actions like adding nodes/edges or triggering scans.

12. Deployment model

The repo is built for containerized deployment, with separate Dockerfiles for frontend and backend plus multiple compose variants, including standalone and prebuilt modes. There is also a bare-metal/LXC install path for the MCP service and a frontend-only mode for design/export use cases.

13. Operational tooling

CI and quality gates are split into Docker build/publish, quality, and security workflows. The presence of dedicated scripts for password hashing, scan execution, and install/verification indicates that runtime operations are intentionally supported outside the web UI as well.