Architecture Overview

Purpose

This document serves as the canonical source of truth for the Home Lab platform. It defines what exists and why, establishing the fundamental principles that guide all architectural decisions.

The set of services and infrastructure components explicitly designed to be reachable from the public internet. This platform resides behind the Public Ingress and is subject to strict exposure policies.

Internal Platform

The core of the home lab, consisting of services reachable only from the local network (LAN) or via an authorized VPN connection. Access is defined by network presence and identity.

Trust Boundaries

Clear lines of demarcation between different security zones (Internet, LAN, VPN, Management). Every interaction across a boundary must be explicitly allowed and authenticated.

Platform Roles

The platform is composed of several stable roles that provide foundational services:

Connectivity: DNS, Ingress, and VPN.
Identity: Centralized authentication and SSO.
Persistence: Replicated storage and backups.
Operations: Monitoring, alerting, and change management.

Invariants

These rules are absolute and must not be violated by any implementation:

Internal Isolation: Internal services are never internet-routable. No direct NAT or port-forwarding to internal services is permitted.
Identity First: No service shall be exposed without an identity-aware proxy or native SSO integration unless explicitly justified in a Service Contract.
Source of Truth: The Git repository is the sole authority for the state of the platform. Manual “hot-fixes” are technical debt that must be codified immediately.
Data Durability: Critical data must exist in at least two physical locations at all times.

Non-Goals

Real-time global availability (HA is local/cluster-based, not geo-distributed).
Public hosting of third-party data.
Replacement of enterprise-grade cloud services for high-risk workloads.

Homelab Project