truenas-stacks/docs/architecture/ARCHITECTURE_OVERVIEW.md

Architecture Overview

Full homelab stack as of 2026-05-09. All 6 expansion phases are complete and deployed.

Servers

Server	OS	IP	Role
PlausibleDeniability (PD)	TrueNAS Scale 25.10.2.1	10.5.30.6	Primary Docker host — all compose stacks
Serenity	Unraid 7.2.4	10.5.30.5	NAS, ARR stack, CPU reranker
N.O.M.A.D.	Ubuntu 25.10	10.5.30.7	Offline knowledge, game servers, and standalone local services
Rocinante	(bare metal)	10.5.30.112	Heavy Ollama models (RTX 4090)

Network

• Management: 10.5.0.0/24
• Trusted: 10.5.1.0/24
• IoT: 10.5.10.0/24
• Cameras: 10.5.20.0/24
• Servers: 10.5.30.0/24
• Guest: 10.5.90.0/24
• Legacy quarantine: 192.168.1.0/24 (Old IoT)
• UniFi policy zones: Internal = Management + Trusted + Servers, Untrusted = IoT + Cameras + Old IoT, Hotspot = Guest
• Current custom firewall hardening: Allow Internal to Untrusted, Block Untrusted to Gateway Admin Surfaces, Allow Untrusted to DNS Resolver, Block Untrusted to Gateway Default Services, Allow Untrusted to Gateway DHCP, Allow Untrusted to Gateway mDNS, plus explicit public-DNS allows used for fallback
• Current DHCP DNS policy: Management, Trusted, Servers, IoT, Camera, and Old IoT advertise the Technitium trio 10.5.30.8, 10.5.30.9, and 10.5.30.10, followed by external fallback 9.9.9.9; Guest advertises 9.9.9.9 and 1.1.1.1
• Net effect: every non-guest lane now has three independent internal Technitium resolvers for both public DNS and the private home.paccoco.com zone, plus external fallback if all homelab resolvers are down; untrusted lanes still retain DNS, DHCP, and mDNS but no longer have general gateway access or UDM Pro admin-surface access
• Current DNS caveat: the backup Technitium nodes on N.O.M.A.D. (10.5.30.9) and Serenity (10.5.30.10) start from a cloned PD Technitium config, so future authoritative-zone changes on PD must be resynced or automated to keep all three nodes aligned
• Tailscale: Serenity reachable at 100.94.87.79
• NFS: Serenity exports /mnt/user/data and /mnt/user/immich → mounted on PD at /mnt/unraid/ via post-init script
• Docker networking: Cross-stack communication via named external networks (ai-services, ix-databases_shared-databases)

Stack Overview

Infrastructure Layer

• Homepage (3300) — dashboard / service index
• Uptime Kuma (3001) — monitoring and alerting
• Gotify (8443) — push notifications
• Gitea (3002 web / 2222 SSH) — self-hosted git; internal SSH remote uses ssh://git@10.5.30.6:2222/<owner>/<repo>.git
• Dockhand (3230) — Docker management UI

AI Layer

• LiteLLM (4000) — unified LLM proxy; routes to Ollama on PD (light) and Rocinante (heavy)
• OpenWebUI (8282) — chat UI with RAG, STT, and web search
• Qdrant (6333/6334) — vector database for RAG
• Whisper (8786 / 8787) — CPU speech-to-text on N.O.M.A.D. plus CUDA speech-to-text on Rocinante
• SearXNG (8888) — private web search backend
• Reranker (Serenity:9787) — TEI bge-reranker-v2-m3, CPU-only

Media Layer

• Plex (32400), Tautulli (8181), Audiobookshelf (13358), Calibre (8183), Seerr (5055) — all on PD
• ARR stack on Serenity (Sonarr, Radarr, Prowlarr, qBittorrent)

Productivity Layer

• Immich (2283) — photo management; library on Serenity NFS
• Paperless-NGX (8083) — document management; uses internal Tika + Gotenberg sidecars for Office/OpenDocument text extraction and conversion
• Karakeep (3100) — bookmarks / read-later
• n8n (5678) — workflow automation
• KitchenOwl (8086), DoneTick (2021) — household and task management

Smart Home Layer

• Home Assistant (8123) — home automation hub
• Kima Hub (3333) — custom IoT gateway

Monitoring Layer

• Grafana (3000) + Prometheus (9090) — metrics and dashboards
• MeshMonitor (8081) — network mesh visibility

Key Architectural Decisions

1. LiteLLM as unified proxy — all AI clients target LiteLLM; model routing is transparent to clients
2. Reranker on Serenity (CPU) — keeps reranking off the primary inference GPUs; CPU latency is acceptable for RAG reranking
3. External Docker networks — ai-services bridges all AI containers across compose files; ix-databases_shared-databases provides shared DB access
4. NFS for Immich — photo library lives on Serenity's large array; PD mounts on demand (not at boot)
5. TrueNAS manages Docker — never use systemctl restart docker on PD; use docker compose or docker restart for individual containers
6. Credential hygiene — Gitea pushes from PD/NOMAD use internal SSH (ssh://git@10.5.30.6:2222/<owner>/<repo>.git); GitHub remote uses SSH key (/root/.ssh/id_gitea)