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.1.6	Primary Docker host — all compose stacks
Serenity	Unraid 7.2.4	10.5.1.5	NAS, ARR stack, CPU reranker
N.O.M.A.D.	Ubuntu 25.10	10.5.1.16	Light Ollama models, game servers
Rocinante	(bare metal)	10.5.1.112	Heavy Ollama models (RTX 4090)

Network

• LAN subnet: 10.5.1.0/24
• 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) — self-hosted git
• Dockhand (3230) — Docker management UI

AI Layer

• LiteLLM (4000) — unified LLM proxy; routes to Ollama on N.O.M.A.D. (light) and Rocinante (heavy)
• OpenWebUI (8282) — chat UI with RAG, STT, and web search
• Qdrant (6333/6334) — vector database for RAG
• Whisper (8786) — CUDA speech-to-text on PD's RTX 2080 Ti
• 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) — frees RTX 2080 Ti on PD exclusively for Whisper CUDA; CPU latency 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 remote uses HTTPS + credential store; GitHub remote uses SSH key (/root/.ssh/id_gitea)