docs: document Hermes Atlas architecture diagram

swarm-common/obsidian-vault/will/will-shared-zap/Atlas/Hermes Atlas Architecture Diagram.md

@@ -0,0 +1,155 @@
+---
+title: Hermes / Atlas Architecture Diagram
+type: architecture-note
+created: 2026-05-29
+tags:
+  - hermes
+  - atlas
+  - architecture
+  - homelab
+  - docker
+  - kubernetes
+---
+
+# Hermes / Atlas Architecture Diagram
+
+A vector architecture diagram was created for the current Hermes/Atlas agent setup, host Docker/systemd AI services, AgentMon stack, and k0s Kubernetes homelab services.
+
+## Primary artifacts
+
+- SVG vector source: `/home/will/diagrams/hermes-atlas-architecture.svg`
+- High-resolution PNG export: `/home/will/diagrams/hermes-atlas-architecture-6400.png`
+- HTML presentation page: `/home/will/hermes-atlas-architecture.html`
+- Maintenance README: `/home/will/diagrams/README-hermes-atlas-architecture.md`
+- SVG extraction script: `/home/will/diagrams/extract-svg.py`
+
+## Why SVG
+
+The diagram is kept as standalone SVG so it can be:
+
+- scaled without resolution loss,
+- edited later in Inkscape, Figma, Illustrator, VS Code, or a browser-aware SVG editor,
+- exported to PNG at any resolution,
+- updated from the HTML presentation page when the layout changes.
+
+## Current coverage
+
+### Hermes / Atlas agent plane
+
+- Telegram, Discord, email, and local UI entrypoints.
+- Default Hermes gateway process.
+- Hermes state/context layer: `state.db`, sessions, memory, skills, config, auth pools.
+- Kanban dispatcher configured inside the gateway.
+- Specialist profiles including engineer, reviewer, orchestrator, researcher/writer, ops, and glm-simple.
+- Cron jobs and webhook subscriptions.
+- n8n/webhook producers for reminders, diary nudges, medication reminders, and Pi run results.
+
+### Host AI / automation plane
+
+- Docker Compose services under `/home/will/lab/swarm`:
+  - Brave Search MCP `:18802`
+  - SearXNG `:18803`
+  - Whisper GPU `:18801`
+  - Whisper CPU `:18811`
+  - Kokoro TTS `:18805`
+  - n8n `:18808`
+  - LiteLLM defined on `:18804`, but not running in the captured snapshot
+- User systemd services:
+  - `llama-server.service` on `:18806`
+  - `ollama.service` on `:18807`
+- AgentMon:
+  - ingest `:8080`
+  - query API `:8081`
+  - UI `:8082`
+  - Postgres and NATS backing services
+
+### k0s Kubernetes plane
+
+- Cluster: `k0s-cluster`
+- Nodes:
+  - `pi50` control-plane, `192.168.153.210`
+  - `pi51` worker, `192.168.153.206`
+  - `pi3` worker, `192.168.153.184`
+- Main layers:
+  - ArgoCD GitOps
+  - MetalLB
+  - HAProxy, nginx, and Traefik ingress
+  - Tailscale exposure
+  - atlas-control
+  - gitea
+  - minio
+  - home-assistant
+  - monitoring
+  - pihole2
+  - plex
+  - tools
+  - backup stores
+
+## Refresh workflow
+
+For simple edits, edit the SVG directly:
+
+```bash
+inkscape /home/will/diagrams/hermes-atlas-architecture.svg
+```
+
+For larger layout/content edits, edit the HTML page and regenerate the SVG:
+
+```bash
+$EDITOR /home/will/hermes-atlas-architecture.html
+/home/will/diagrams/extract-svg.py
+```
+
+To export a fresh high-resolution PNG from the SVG:
+
+```bash
+chromium --headless --disable-gpu --no-sandbox --hide-scrollbars \
+  --window-size=3200,2240 \
+  --force-device-scale-factor=2 \
+  --screenshot=/home/will/diagrams/hermes-atlas-architecture-6400.png \
+  file:///home/will/diagrams/hermes-atlas-architecture.svg
+```
+
+## Refresh checklist
+
+When updating the diagram from live infrastructure, re-check:
+
+- Hermes profile roster and gateway status.
+- Active Kanban worker processes.
+- Cron jobs and webhook subscriptions.
+- `/home/will/lab/swarm/docker-compose.yaml` services and currently running containers.
+- User systemd service units for local model endpoints.
+- AgentMon containers and exposed ports.
+- k0s nodes, load balancer services, ArgoCD app sync/health status, and selected namespaces.
+- Deliberate dormant or degraded states, such as OpenClaw remaining dormant or LiteLLM being defined but not running.
+
+## Source commands used
+
+The initial diagram was based on live read-only checks:
+
+```bash
+docker ps
+cd /home/will/lab/swarm && docker compose config --services
+cd /home/will/lab/swarm && make ps
+systemctl --user is-active llama-server.service ollama.service llama-swap.service
+systemctl --user cat llama-server.service
+systemctl --user cat ollama.service
+ss -ltnp
+hermes profile list
+hermes cron list
+hermes webhook list
+kubectl config get-contexts
+kubectl get nodes -o wide
+kubectl get ns
+kubectl get svc -A --field-selector spec.type=LoadBalancer -o wide
+kubectl get applications -n argocd
+kubectl get deploy,sts,ds,pods,svc,ingress -n <namespace>
+```
+
+Secrets were intentionally omitted.
+
+## Related
+
+- [[Atlas]]
+- [[Hermes]]
+- [[Inbox/Inbox]]