my-homelab-configs/docs/architecture.md

Architecture Overview

(Note: Since this is an HTML file, click the link below to open it in your browser)

👉 Open Interactive Architecture Diagram

System Design

This homelab utilizes a hybrid architecture combining a high-performance K8s cluster for scalable workloads and a stable Docker-Compose/Host environment for core infrastructure services.

1. The Edge Path (OCI \rightarrow LAN)

Traffic enters via the OCI Edge bridge to minimize exposure of the home IP and provide low-latency caching.

• Ingress: Nginx handles TLS termination and HTTP/2.
• Routing: HAProxy manages L7 routing to the internal mesh.
• Caching: Varnish/Squid provides an edge cache for static content.
• Transport: A Tailscale mesh tunnel connects the OCI Edge to the internal homelab LAN.

2. The Core Infrastructure (LAN)

The internal network is centered around a Debian control-plane and a mix of ARM64 worker nodes.

• Host Services: Core GitOps (Gitea), Dashboard (Heimdall), and Local AI (Ollama) run directly on the Debian host for maximum reliability.
• K8s Cluster: Managed via jeannie (OpenTofu + ArgoCD).
  • Ingress: Traefik provides L7 routing via MetalLB.
  • Workloads: Segmented into Web Apps (PHP, Static) and Platform Services (ArgoCD, Prometheus).
  • Workers: A mix of Pimox-virtualized VMs and Raspberry Pi nodes.
• Storage: Local persistence is managed via OpenEBS Hostpath.

3. AI Integration Flow

AI capabilities are decoupled from the K8s lifecycle to utilize host-level GPU/CPU resources efficiently.

• API Layer: Ollama runs as a host service.
• Consumption: K8s-based applications communicate with the Ollama API over the internal LAN.
• Memory: Redis (transitioning to Valkey) provides a translation and session cache for AI-driven web features.