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	Offline knowledge, game servers, and standalone local services
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 web / 2222 SSH) — self-hosted git; internal SSH remote uses ssh://git@10.5.1.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.1.6:2222/<owner>/<repo>.git); GitHub remote uses SSH key (/root/.ssh/id_gitea)