# 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

- **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.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`)