# Architecture Overview

![Infrastructure Diagram](./architecture-diagram.html)
*(Note: Since this is an HTML file, click the link below to open it in your browser)*

[👉 Open Interactive Architecture Diagram](./architecture-diagram.html)

## 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.