Publish sanitized current homelab architecture

2026-09-08 21:47:41 +00:00
commit cc35523888
13 changed files with 901 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,141 @@
+# Architecture
+
+## Topology
+
+```mermaid
+flowchart TB
+    Internet((Internet))
+    Edge[Authenticated tunnel gateway]
+    SSO[Identity and SSO]
+    Proxy[Internal reverse proxy]
+
+    subgraph Home[Segmented home network]
+        subgraph Primary[Primary application host]
+            Apps[Household and productivity apps]
+            Data[Shared databases and caches]
+            Media[Media, photos, and documents]
+            Observe[Monitoring and dashboards]
+            AI[Always-on AI and search]
+        end
+
+        subgraph Storage[Storage and ingestion host]
+            Pool[Bulk ZFS storage]
+            Arr[Media automation and download pipeline]
+            Sync[File synchronization and backups]
+            Remote[Remote-support relay]
+        end
+
+        subgraph Resilience[Offline and resilience host]
+            Offline[Offline knowledge and education]
+            HomeAuto[Home automation VM]
+            Games[Game-server control plane]
+            Secondary[Backup DNS and local AI]
+            Agents[Automation and agent services]
+        end
+
+        Workstation[GPU operator workstation]
+        EdgeNode[Low-power weather and radio node]
+    end
+
+    Internet --> Edge --> Proxy
+    Proxy --> SSO
+    SSO --> Apps
+    Apps --> Data
+    Apps --> Pool
+    Media --> Pool
+    Arr --> Pool
+    Observe --> Apps
+    AI -. optional heavy jobs .-> Workstation
+    Secondary -. resilient local path .-> AI
+    Agents --> Apps
+    Sync --> Workstation
+    EdgeNode --> Agents
+    Remote -. private overlay .-> Workstation
+```
+
+## Host responsibilities
+
+### Primary application host
+
+The primary host carries the application plane:
+
+- shared PostgreSQL, MariaDB, and Redis
+- identity, SSO, ingress routing, and tunnel clients
+- media front ends, photo management, and document management
+- dashboards, monitoring, metrics, logs, and notifications
+- household applications and workflow automation
+- light-tier model serving, search, RAG, and vector storage
+- self-hosted development and administration tools
+
+The host is intentionally not the only copy of storage, DNS, or offline knowledge.
+
+### Storage and ingestion host
+
+The storage host owns the large-capacity data plane and workloads that benefit from data locality:
+
+- ZFS-backed bulk datasets
+- media acquisition, organization, and post-processing
+- synchronized document storage with versioning
+- backup targets and retained application data
+- private remote-support rendezvous and relay
+- selected CPU-only inference utilities
+- a secondary DNS replica
+
+### Offline and resilience host
+
+The resilience host is designed to remain useful when public services are unavailable:
+
+- offline reference libraries and educational content
+- local notes and browser utilities
+- local model and vector services
+- agent memory and household helper applications
+- Home Assistant running in a dedicated virtual machine
+- game-server management
+- mesh-radio observation
+- a secondary DNS replica
+
+### GPU workstation
+
+The workstation provides high-performance GPU capacity for interactive or heavy jobs. Routine background tasks must continue when it is asleep or offline.
+
+### Low-power edge node
+
+The edge node handles always-on weather and mesh-radio functions close to the attached hardware. It reports upstream but is not part of the main application failure domain.
+
+## Request flows
+
+### External application request
+
+```text
+client → tunnel gateway → internal reverse proxy → SSO policy → application
+```
+
+The tunnel endpoint is the only public routing layer. Application containers do not require direct inbound router exposure.
+
+### Internal application request
+
+```text
+trusted client → internal DNS → application or reverse proxy → service
+```
+
+### AI request
+
+```text
+application → model gateway → always-on local model
+                            ↘ optional GPU workstation
+```
+
+### Storage request
+
+```text
+application host → authenticated network storage mount → storage dataset
+```
+
+## Failure-domain rules
+
+1. Losing the GPU workstation must not stop routine automation.
+2. Losing public DNS must not be confused with losing the private DNS zone.
+3. Losing the primary application host must not destroy bulk datasets or backups.
+4. A tunnel or SSO failure must not expose an application directly.
+5. The offline host must retain useful local content without WAN access.
+6. Changes to storage, networking, identity, and databases require explicit rollback points.