How gregluffy/homelabinfo works
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: Program.cs Program · AgentsController.cs Controllers · apiFetch.ts API Client · AppDbContext.cs SQLite Store
Components 19
Frontend
Next.js dashboard and UI flow
- Home · Landing and overview entry point
frontend/src/app/page.tsx - Login · Authentication screen
frontend/src/app/login/page.tsx - Setup · First-run user creation flow
frontend/src/app/setup/page.tsx - Network · Device and status view
frontend/src/app/network/page.tsx - Topology · Topology visualization view
frontend/src/app/topology/page.tsx - API Client · Browser-side backend access wrapper
frontend/src/lib/apiFetch.ts - Auth State · Session and auth context
frontend/src/lib/authContext.ts - Graph UI · Renders network topology graph
frontend/src/components/NetworkTopologyGraph.tsx - Settings UI · Agent and settings dialogs
frontend/src/components/SettingsModal.tsx
Backend
ASP.NET Core control plane and persistence
- Program · API bootstrap and middleware pipeline
backend/Program.cs - Auth Middleware · Optional request guarding
backend/Middleware/AuthMiddleware.cs - Controllers · Auth, agents, scanner, and settings endpoints
backend/Controllers/AgentsController.cs - Scanner · LAN discovery, DHCP listening, notifications
backend/Services/NetworkScannerService.cs - Auth Services · JWT, password hashing, secret handling
backend/Services/JwtService.cs - SQLite Store · EF Core persistence boundary
backend/Data/AppDbContext.cs
Agent
Remote telemetry service
- Agent Host · Standalone .NET agent entry point
agent/Program.cs - Docker Probe · Local Docker environment inspection
agent/Services/DockerService.cs - Metrics · Packages runtime telemetry payloads
agent/Services/MetricsService.cs
Deployment
Docker Compose and container wiring
- Compose Stack · Hub-only, agent-only, and unified deployments
docker-compose.yml
Connections 21
- 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