# pouzor/homelable architecture

> Architecture diagram of the GitHub repository pouzor/homelable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pouzor/homelable
- Repository: https://github.com/pouzor/homelable

## Overview

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.

Main entry points: [`backend/app/api/routes`](https://github.com/pouzor/homelable/tree/main/backend/app/api/routes) (Routes), [`frontend/src/App.tsx`](https://github.com/pouzor/homelable/blob/main/frontend/src/App.tsx) (UI app), [`docker-compose.yml`](https://github.com/pouzor/homelable/blob/main/docker-compose.yml) (Compose stack), [`backend/app/services`](https://github.com/pouzor/homelable/tree/main/backend/app/services) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_backend_main["API app<br/>FastAPI entry<br/>[main.py]"]
  node_backend_routes["Routes<br/>HTTP boundaries"]
  node_backend_core["Core<br/>config/security/scheduler"]
  node_backend_db[("Database<br/>ORM persistence")]
  node_backend_services["Services"]
  node_backend_scan_data["Signatures<br/>fingerprint data"]
end

subgraph group_frontend["Frontend App"]
  node_frontend_app["UI app<br/>React entry<br/>[App.tsx]"]
  node_frontend_canvas["Canvas<br/>editor surface"]
  node_frontend_panels["Panels<br/>editor chrome"]
  node_frontend_modals["Modals<br/>edit dialogs"]
  node_frontend_zigbee["Zigbee import<br/>import UI"]
  node_frontend_stores["Stores<br/>client state"]
  node_frontend_utils["Transforms<br/>export/import utils"]
end

subgraph group_mcp["MCP Server"]
  node_mcp_main["MCP app<br/>MCP entry<br/>[main.py]"]
  node_mcp_tools["Tools<br/>AI actions<br/>[tools.py]"]
  node_mcp_client["Backend client<br/>internal API client<br/>[backend_client.py]"]
end

subgraph group_ops["Deployment & Tools"]
  node_deploy_frontend["Frontend image<br/>container build"]
  node_deploy_backend["Backend image<br/>container build<br/>[Dockerfile.backend]"]
  node_deploy_compose["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_ops_scripts["Scripts<br/>ops tooling"]
end

node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"calls"| node_backend_services
node_backend_routes -->|"reads/writes"| node_backend_db
node_backend_services -->|"stores state"| node_backend_db
node_backend_services -->|"fingerprints"| node_backend_scan_data
node_backend_main -->|"configures"| node_backend_core
node_frontend_app -->|"renders"| node_frontend_canvas
node_frontend_app -->|"composes"| node_frontend_panels
node_frontend_app -->|"opens"| node_frontend_modals
node_frontend_app -->|"binds"| node_frontend_stores
node_frontend_app -->|"uses"| node_frontend_utils
node_frontend_modals -->|"includes"| node_frontend_zigbee
node_frontend_canvas -->|"API calls"| node_backend_routes
node_frontend_modals -->|"API calls"| node_backend_routes
node_frontend_stores -->|"derives data"| node_frontend_utils
node_mcp_main -->|"registers"| node_mcp_tools
node_mcp_tools -->|"delegates"| node_mcp_client
node_mcp_client -->|"internal API"| node_backend_routes
node_deploy_compose -->|"orchestrates"| node_deploy_backend
node_deploy_compose -->|"orchestrates"| node_deploy_frontend
node_deploy_compose -->|"orchestrates"| node_mcp_main
node_ops_scripts -->|"supports"| node_deploy_compose
node_ops_scripts -->|"runs"| node_backend_services

click node_backend_main "https://github.com/pouzor/homelable/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/pouzor/homelable/tree/main/backend/app/api/routes"
click node_backend_core "https://github.com/pouzor/homelable/tree/main/backend/app/core"
click node_backend_db "https://github.com/pouzor/homelable/tree/main/backend/app/db"
click node_backend_services "https://github.com/pouzor/homelable/tree/main/backend/app/services"
click node_backend_scan_data "https://github.com/pouzor/homelable/blob/main/backend/app/data/service_signatures.json"
click node_frontend_app "https://github.com/pouzor/homelable/blob/main/frontend/src/App.tsx"
click node_frontend_canvas "https://github.com/pouzor/homelable/tree/main/frontend/src/components/canvas"
click node_frontend_panels "https://github.com/pouzor/homelable/tree/main/frontend/src/components/panels"
click node_frontend_modals "https://github.com/pouzor/homelable/tree/main/frontend/src/components/modals"
click node_frontend_zigbee "https://github.com/pouzor/homelable/blob/main/frontend/src/components/zigbee/ZigbeeImportModal.tsx"
click node_frontend_stores "https://github.com/pouzor/homelable/tree/main/frontend/src/stores"
click node_frontend_utils "https://github.com/pouzor/homelable/tree/main/frontend/src/utils"
click node_mcp_main "https://github.com/pouzor/homelable/blob/main/mcp/app/main.py"
click node_mcp_tools "https://github.com/pouzor/homelable/blob/main/mcp/app/tools.py"
click node_mcp_client "https://github.com/pouzor/homelable/blob/main/mcp/app/backend_client.py"
click node_deploy_frontend "https://github.com/pouzor/homelable/blob/main/Dockerfile.frontend"
click node_deploy_backend "https://github.com/pouzor/homelable/blob/main/Dockerfile.backend"
click node_deploy_compose "https://github.com/pouzor/homelable/blob/main/docker-compose.yml"
click node_ops_scripts "https://github.com/pouzor/homelable/tree/main/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_routes,node_backend_core,node_backend_db,node_backend_services,node_backend_scan_data toneBlue
class node_frontend_app,node_frontend_canvas,node_frontend_panels,node_frontend_modals,node_frontend_zigbee,node_frontend_stores,node_frontend_utils toneAmber
class node_mcp_main,node_mcp_tools,node_mcp_client toneMint
class node_deploy_frontend,node_deploy_backend,node_deploy_compose,node_ops_scripts toneRose
```

## Components

### Backend API

Python FastAPI service for canvas data, discovery, status, and imports.

- [API app](https://github.com/pouzor/homelable/blob/main/backend/app/main.py): FastAPI entry · Bootstraps the backend service and mounts API routes. · `backend/app/main.py`
- [Routes](https://github.com/pouzor/homelable/tree/main/backend/app/api/routes): HTTP boundaries · Route groups for auth, canvas, nodes, edges, designs, scan, status, stats, settings, liveview, and zigbee. · `backend/app/api/routes`
- [Core](https://github.com/pouzor/homelable/tree/main/backend/app/core): config/security/scheduler · Shared backend configuration, security, and scheduling primitives. · `backend/app/core`
- [Database](https://github.com/pouzor/homelable/tree/main/backend/app/db): ORM persistence · Central database module and models for canvas state and operational data. · `backend/app/db`
- [Services](https://github.com/pouzor/homelable/tree/main/backend/app/services): domain services · Scanner, fingerprinting, status checks, and Zigbee import logic. · `backend/app/services`
- [Signatures](https://github.com/pouzor/homelable/blob/main/backend/app/data/service_signatures.json): fingerprint data · Service signature catalog used to identify discovered services. · `backend/app/data/service_signatures.json`

### Frontend App

React/Vite client for editing, viewing, and exporting diagrams.

- [UI app](https://github.com/pouzor/homelable/blob/main/frontend/src/App.tsx): React entry · Bootstraps the client application and top-level layout. · `frontend/src/App.tsx`
- [Canvas](https://github.com/pouzor/homelable/tree/main/frontend/src/components/canvas): editor surface · Interactive diagram canvas, nodes, edges, and search. · `frontend/src/components/canvas`
- [Panels](https://github.com/pouzor/homelable/tree/main/frontend/src/components/panels): editor chrome · Sidebar, toolbar, and detail panel surrounding the canvas. · `frontend/src/components/panels`
- [Modals](https://github.com/pouzor/homelable/tree/main/frontend/src/components/modals): edit dialogs · Dialogs for node, edge, design, scan, settings, export, and imports. · `frontend/src/components/modals`
- [Zigbee import](https://github.com/pouzor/homelable/blob/main/frontend/src/components/zigbee/ZigbeeImportModal.tsx): import UI · UI flow for importing Zigbee2MQTT topology into the canvas. · `frontend/src/components/zigbee/ZigbeeImportModal.tsx`
- [Stores](https://github.com/pouzor/homelable/tree/main/frontend/src/stores): client state · Auth, canvas, design, and theme stores that coordinate editor state. · `frontend/src/stores`
- [Transforms](https://github.com/pouzor/homelable/tree/main/frontend/src/utils): export/import utils · Serialization, layout, export, icon/color selection, and import helpers. · `frontend/src/utils`

### MCP Server

Separate Python process for AI tooling over the backend.

- [MCP app](https://github.com/pouzor/homelable/blob/main/mcp/app/main.py): MCP entry · Starts the MCP server process for AI clients. · `mcp/app/main.py`
- [Tools](https://github.com/pouzor/homelable/blob/main/mcp/app/tools.py): AI actions · Tool handlers that expose backend reads and writes to MCP clients. · `mcp/app/tools.py`
- [Backend client](https://github.com/pouzor/homelable/blob/main/mcp/app/backend_client.py): internal API client · Authenticated client used by MCP to call the backend service. · `mcp/app/backend_client.py`

### Deployment & Tools

Container, install, CI, and operational scripts.

- [Frontend image](https://github.com/pouzor/homelable/blob/main/Dockerfile.frontend): container build · Docker build definition for the frontend runtime. · `Dockerfile.frontend`
- [Backend image](https://github.com/pouzor/homelable/blob/main/Dockerfile.backend): container build · Docker build definition for the backend runtime. · `Dockerfile.backend`
- [Compose stack](https://github.com/pouzor/homelable/blob/main/docker-compose.yml): deployment · Standalone, prebuilt, CI, and default compose variants. · `docker-compose.yml`
- [Scripts](https://github.com/pouzor/homelable/tree/main/scripts): ops tooling · Install, scan, verification, and security helper scripts. · `scripts`

## Connections

- API app → Routes: mounts · The app wires the route groups into the service.
- Routes → Services: calls · HTTP endpoints delegate to scanner, status, and Zigbee services.
- Routes → Database: reads/writes · Routes persist canvas, devices, scans, settings, and designs.
- Services → Database: stores state · Discovery, status, and import services update shared persistence.
- Services → Signatures: fingerprints · Scanner fingerprinting uses the signature catalog.
- API app → Core: configures · Application startup depends on backend config, security, and scheduling.
- UI app → Canvas: renders · The app centers on the interactive canvas editor.
- UI app → Panels: composes · Panels provide the main editor controls and information views.
- UI app → Modals: opens · User actions flow into editing, scan, export, and settings dialogs.
- UI app → Stores: binds · Global client state coordinates editor behavior.
- UI app → Transforms: uses · The UI relies on transforms for serialization and export.
- Modals → Zigbee import: includes · Zigbee import is one of the specialized modal flows.
- Canvas → Routes: API calls · The editor loads, edits, scans, and syncs diagram state through the backend.
- Modals → Routes: API calls · Dialogs trigger canvas, scan, status, design, and Zigbee endpoints.
- Stores → Transforms: derives data · Stores use utility helpers for normalized canvas and theme state.
- MCP app → Tools: registers · The MCP process exposes its tool surface through the tool handlers.
- Tools → Backend client: delegates · Tools use the backend client for authenticated service calls.
- Backend client → Routes: internal API · MCP talks to the backend over a dedicated service boundary.
- Compose stack → Backend image: orchestrates · Compose variants include the backend service image.
- Compose stack → Frontend image: orchestrates · Compose variants include the frontend service image.
- Compose stack → MCP app: orchestrates · Some deployment modes run the MCP service alongside the app.
- Scripts → Compose stack: supports · Scripts assist install, scan, and verification workflows around deployment.
- Scripts → Services: runs · Operational scripts invoke scanning and security-related backend behavior.