truenas-stacks/docs/architecture/ARCHITECTURE_OVERVIEW.md

Architecture Overview

Current live homelab stack plus the planned direction for the upgraded PD platform.

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 for general internet name resolution 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 sync model: PD (10.5.30.8) is the authoritative Technitium source, and root cron on PD runs /mnt/docker-ssd/docker/compose/technitium-pilot/bin/sync_backup_nodes.sh every 15 minutes to rsync the live config to N.O.M.A.D. (10.5.30.9) and Serenity (10.5.30.10), restart those backup stacks, and verify both private and public DNS answers
• Current DNS caveats: 9.9.9.9 preserves public DNS continuity but is not an authoritative substitute for the internal home.paccoco.com zone; same-host macvlan tests are also misleading, so resolver verification must come from an off-host client or peer host
• 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)

Planned Direction — upgraded PD + Serenity retirement

• PD stays on bare-metal TrueNAS Scale and becomes the long-term production center of gravity for storage, Docker, shared databases, media, identity, monitoring, and the primary DNS source node.
• PD may also host cybersecurity VMs, but only inside a dedicated lab VLAN / policy lane with default-deny access into production.
• N.O.M.A.D. remains the trusted secondary lane for offline knowledge, game hosting, and the backup Technitium resolver.
• Rocinante becomes optional if PD receives the 4090; otherwise it stays the heavy inference specialist.
• Serenity is transitional: as long as it owns the storage, qBittorrent/ARR locality can remain there; once PD directly owns the storage, that path-locality argument flips and the remaining torrent/media-ingest stack should move to PD before Serenity is retired.
• See ../planning/PD_FUTURE_STATE_ARCHITECTURE.md for the full target-state plan and pd-future-state-topology.html for the visual operator map.