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; PD remains the shared light tier, while Rocinante is an opportunistic heavy tier when the PC is online
- **Honcho** — memory/deriver stack on N.O.M.A.D. using local Ollama first so PD outages do not cascade into MeshMonitor/database incidents
- **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](../planning/PD_FUTURE_STATE_ARCHITECTURE.md) for the full target-state plan and [pd-future-state-topology.html](pd-future-state-topology.html) for the visual operator map.