# gregluffy/homelabinfo architecture

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

- Interactive diagram: https://gitdiagram.com/gregluffy/homelabinfo
- Repository: https://github.com/gregluffy/homelabinfo

## Overview

1. **Repository shape**
   - This is a three-part homelab management system: a **web dashboard**, a **central API/backend**, and a separate **agent** that can run on remote hosts.
   - The default deployment is Docker-based, but the architecture supports both a single-machine “hub + local agent” setup and a distributed “hub + many agents” setup.

2. **Frontend subsystem**
   - `frontend/` is a **Next.js** app using the App Router.
   - Its main pages are the **landing/home view**, **login**, **initial setup**, **network view**, and **topology view**.
   - UI components are split into dashboard cards, topology graph rendering, settings/agent modals, and auth helpers. The frontend is mostly a presentation layer that pulls data from the backend via `apiFetch`.

3. **Backend subsystem**
   - `backend/` is an **ASP.NET Core API** that acts as the central control plane.
   - Controllers are organized by domain: **authentication**, **agents**, **scanner**, and **settings**.
   - `Program.cs` and `AuthMiddleware` define the request pipeline, with optional auth guarding the API when enabled.

4. **Persistence boundary**
   - The backend uses **Entity Framework Core** with **SQLite** for storage.
   - Core persisted entities include:
     - `NetworkDevice` for discovered LAN devices
     - `VmAgent` for registered remote agents
     - `User` for login accounts
     - `AppSetting` for stored configuration
   - Migrations show the schema evolving to support agents, coordinates for topology placement, application settings, and users.

5. **Network discovery pipeline**
   - `NetworkScannerService` performs active network discovery and status tracking.
   - `DhcpListenerService` listens for DHCP activity so new devices can be detected quickly when they join the network.
   - `WebhookNotificationService` sends notifications when new clients are seen, making discovery event-driven rather than purely polling-based.

6. **Authentication and setup flow**
   - Auth is **optional** and disabled by default to preserve existing deployments.
   - When enabled, the system uses a first-run **setup page** to create the initial user.
   - Passwords are hashed with **PBKDF2-SHA256**, and tokens are issued as **JWTs** via `JwtService`.
   - `CryptographyService` handles secret/key-related crypto behavior, and `AuthMiddleware` enforces access control.

7. **Agent subsystem**
   - `agent/` is a standalone **.NET** service for remote telemetry collection, especially Docker/container visibility on non-hub machines.
   - `DockerService` and `MetricsService` suggest the agent queries the local Docker environment and packages runtime metrics into `MetricsDto`.
   - The agent connects back to the hub API using environment configuration such as `API_URL` and `HUB_PUBLIC_KEY`, which implies a trust/registration boundary between agent and hub.

8. **Data flow across the system**
   - Discovery data flows from the **host network** into the backend scanner/listener, then into SQLite, and from there into the dashboard views.
   - Agent telemetry flows from remote machines into the hub, where it becomes part of the centralized inventory/monitoring picture.
   - The frontend never talks directly to scanners or agents; it reads through the backend API.

9. **Deployment and infrastructure boundaries**
   - Docker Compose is the primary deployment mechanism, with separate compose files for:
     - unified hub+agent
     - hub only
     - agent only
   - The backend requires `network_mode: host` for accurate LAN scanning, because discovery depends on seeing real broadcast/ARP traffic on the host network stack.
   - This is a key architectural constraint: the scanner is tightly coupled to the host’s networking context and is not meant to run behind Docker bridge isolation.

10. **Operational model**
   - The backend is the system of record for devices, agents, settings, and users.
   - The frontend is a browser-based control surface for viewing topology, network state, and agent/container summaries.
   - The agent extends the system beyond the hub host, enabling distributed visibility across multiple servers or VMs while keeping the hub as the central UI and persistence layer.

Main entry points: [`backend/Program.cs`](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Program.cs) (Program), [`backend/Controllers/AgentsController.cs`](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Controllers/AgentsController.cs) (Controllers), [`frontend/src/lib/apiFetch.ts`](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/lib/apiFetch.ts) (API Client), [`backend/Data/AppDbContext.cs`](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Data/AppDbContext.cs) (SQLite Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_home["Home<br/>page<br/>[page.tsx]"]
  node_ui_login["Login<br/>page<br/>[page.tsx]"]
  node_ui_setup["Setup<br/>page<br/>[page.tsx]"]
  node_ui_network["Network<br/>page<br/>[page.tsx]"]
  node_ui_topology["Topology<br/>page<br/>[page.tsx]"]
  node_ui_api["API Client<br/>frontend lib<br/>[apiFetch.ts]"]
  node_ui_auth["Auth State<br/>frontend state<br/>[authContext.ts]"]
  node_ui_topology_graph["Graph UI"]
  node_ui_settings["Settings UI<br/>[SettingsModal.tsx]"]
end

subgraph group_backend["Backend"]
  node_api_program["Program<br/>api host<br/>[Program.cs]"]
  node_api_authmw["Auth Middleware<br/>[AuthMiddleware.cs]"]
  node_api_controllers["Controllers<br/>api endpoints"]
  node_api_scanner["Scanner"]
  node_api_crypto["Auth Services<br/>[JwtService.cs]"]
  node_api_data[("SQLite Store<br/>ef core db<br/>[AppDbContext.cs]")]
end

subgraph group_agent["Agent"]
  node_agent_program["Agent Host<br/>service host<br/>[Program.cs]"]
  node_agent_docker["Docker Probe<br/>[DockerService.cs]"]
  node_agent_metrics["Metrics<br/>[MetricsService.cs]"]
end

subgraph group_deploy["Deployment"]
  node_compose["Compose Stack<br/>deployment<br/>[docker-compose.yml]"]
end

node_ui_home -->|"loads data"| node_ui_api
node_ui_login -->|"session"| node_ui_auth
node_ui_setup -->|"bootstrap"| node_ui_auth
node_ui_network -->|"fetches"| node_ui_api
node_ui_topology -->|"renders"| node_ui_topology_graph
node_ui_settings -->|"mutates"| node_ui_api
node_ui_auth -->|"guards calls"| node_ui_api
node_api_program -->|"pipeline"| node_api_authmw
node_api_program -->|"routes"| node_api_controllers
node_api_controllers -->|"invokes"| node_api_scanner
node_api_controllers -->|"auth"| node_api_crypto
node_api_scanner -->|"stores"| node_api_data
node_api_crypto -->|"reads users"| node_api_data
node_api_program -->|"owns"| node_api_data
node_agent_program -->|"inspects"| node_agent_docker
node_agent_program -->|"collects"| node_agent_metrics
node_agent_metrics -->|"reports"| node_api_controllers
node_compose -->|"starts"| node_api_program
node_compose -->|"starts"| node_agent_program
node_compose -->|"serves"| node_ui_home
node_api_scanner -->|"persists"| node_api_data

click node_ui_home "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/page.tsx"
click node_ui_login "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/login/page.tsx"
click node_ui_setup "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/setup/page.tsx"
click node_ui_network "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/network/page.tsx"
click node_ui_topology "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/topology/page.tsx"
click node_ui_api "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/lib/apiFetch.ts"
click node_ui_auth "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/lib/authContext.ts"
click node_ui_topology_graph "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/components/NetworkTopologyGraph.tsx"
click node_ui_settings "https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/components/SettingsModal.tsx"
click node_api_program "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Program.cs"
click node_api_authmw "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Middleware/AuthMiddleware.cs"
click node_api_controllers "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Controllers/AgentsController.cs"
click node_api_scanner "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Services/NetworkScannerService.cs"
click node_api_crypto "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Services/JwtService.cs"
click node_api_data "https://github.com/gregluffy/homelabinfo/blob/develop/backend/Data/AppDbContext.cs"
click node_agent_program "https://github.com/gregluffy/homelabinfo/blob/develop/agent/Program.cs"
click node_agent_docker "https://github.com/gregluffy/homelabinfo/blob/develop/agent/Services/DockerService.cs"
click node_agent_metrics "https://github.com/gregluffy/homelabinfo/blob/develop/agent/Services/MetricsService.cs"
click node_compose "https://github.com/gregluffy/homelabinfo/blob/develop/docker-compose.yml"

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_ui_home,node_ui_login,node_ui_setup,node_ui_network,node_ui_topology,node_ui_api,node_ui_auth,node_ui_topology_graph,node_ui_settings toneBlue
class node_api_program,node_api_authmw,node_api_controllers,node_api_scanner,node_api_crypto,node_api_data toneAmber
class node_agent_program,node_agent_docker,node_agent_metrics toneMint
class node_compose toneRose
```

## Components

### Frontend

Next.js dashboard and UI flow

- [Home](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/page.tsx): page · Landing and overview entry point · `frontend/src/app/page.tsx`
- [Login](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/login/page.tsx): page · Authentication screen · `frontend/src/app/login/page.tsx`
- [Setup](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/setup/page.tsx): page · First-run user creation flow · `frontend/src/app/setup/page.tsx`
- [Network](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/network/page.tsx): page · Device and status view · `frontend/src/app/network/page.tsx`
- [Topology](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/app/topology/page.tsx): page · Topology visualization view · `frontend/src/app/topology/page.tsx`
- [API Client](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/lib/apiFetch.ts): frontend lib · Browser-side backend access wrapper · `frontend/src/lib/apiFetch.ts`
- [Auth State](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/lib/authContext.ts): frontend state · Session and auth context · `frontend/src/lib/authContext.ts`
- [Graph UI](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/components/NetworkTopologyGraph.tsx): Renders network topology graph · `frontend/src/components/NetworkTopologyGraph.tsx`
- [Settings UI](https://github.com/gregluffy/homelabinfo/blob/develop/frontend/src/components/SettingsModal.tsx): Agent and settings dialogs · `frontend/src/components/SettingsModal.tsx`

### Backend

ASP.NET Core control plane and persistence

- [Program](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Program.cs): api host · API bootstrap and middleware pipeline · `backend/Program.cs`
- [Auth Middleware](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Middleware/AuthMiddleware.cs): middleware · Optional request guarding · `backend/Middleware/AuthMiddleware.cs`
- [Controllers](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Controllers/AgentsController.cs): api endpoints · Auth, agents, scanner, and settings endpoints · `backend/Controllers/AgentsController.cs`
- [Scanner](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Services/NetworkScannerService.cs): service · LAN discovery, DHCP listening, notifications · `backend/Services/NetworkScannerService.cs`
- [Auth Services](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Services/JwtService.cs): service · JWT, password hashing, secret handling · `backend/Services/JwtService.cs`
- [SQLite Store](https://github.com/gregluffy/homelabinfo/blob/develop/backend/Data/AppDbContext.cs): ef core db · EF Core persistence boundary · `backend/Data/AppDbContext.cs`

### Agent

Remote telemetry service

- [Agent Host](https://github.com/gregluffy/homelabinfo/blob/develop/agent/Program.cs): service host · Standalone .NET agent entry point · `agent/Program.cs`
- [Docker Probe](https://github.com/gregluffy/homelabinfo/blob/develop/agent/Services/DockerService.cs): service · Local Docker environment inspection · `agent/Services/DockerService.cs`
- [Metrics](https://github.com/gregluffy/homelabinfo/blob/develop/agent/Services/MetricsService.cs): service · Packages runtime telemetry payloads · `agent/Services/MetricsService.cs`

### Deployment

Docker Compose and container wiring

- [Compose Stack](https://github.com/gregluffy/homelabinfo/blob/develop/docker-compose.yml): deployment · Hub-only, agent-only, and unified deployments · `docker-compose.yml`

## Connections

- Home → API Client: loads data · Home view reads dashboard data through the API client
- Login → Auth State: session · Login updates browser auth state
- Setup → Auth State: bootstrap · Initial setup creates the first authenticated user
- Network → API Client: fetches · Network page pulls devices and settings from backend
- Topology → Graph UI: renders · Topology page uses the graph component
- Settings UI → API Client: mutates · Settings and agent dialogs call backend endpoints
- Auth State → API Client: guards calls · Auth context shapes authenticated requests
- Program → Auth Middleware: pipeline · Program wires middleware into request handling
- Program → Controllers: routes · Program exposes domain controllers
- Controllers → Scanner: invokes · Scanner-related requests trigger discovery services
- Controllers → Auth Services: auth · Auth endpoints use JWT and password services
- Scanner → SQLite Store: stores · Discovery results persist to SQLite via EF Core
- Auth Services → SQLite Store: reads users · Auth services depend on persisted user records
- Program → SQLite Store: owns · Backend is system of record over the database
- Agent Host → Docker Probe: inspects · Agent probes local container state
- Agent Host → Metrics: collects · Agent assembles telemetry payloads
- Metrics → Controllers: reports · Agent telemetry is sent to hub API
- Compose Stack → Program: starts · Compose deploys the hub backend
- Compose Stack → Agent Host: starts · Compose deploys the standalone agent
- Compose Stack → Home: serves · Compose-backed stack includes the browser UI
- Scanner → SQLite Store: persists · Scanner updates device and topology records