Diagram maintenance

Keep infrastructure diagrams current as first-class documentation, not as one-off screenshots.

Current diagrams

swarm-infrastructure.html — full Atlas/Hermes + n8n + agentmon + local AI/search/voice topology.

When to update an existing diagram

Update the relevant diagram in the same change set when you change any of these:

service topology, ports, or container names
monitoring or alerting paths
n8n workflow architecture
Hermes/Atlas routing or gateway responsibilities
local AI/search/voice endpoints
OpenVINO NPU live/prototype status, ports, or safety gates (:18810, :18816, :18817, :18818, :18819, :18820, optional :18829)
Obsidian/RAG data flow
OpenClaw/VM operational mode
ownership/source-of-truth paths for a component

When to create a new diagram

Create a new focused diagram when the existing overview would become too dense. Good candidates:

n8n workflow family or alerting-only diagram
agentmon internals: collectors → NATS → processor → Postgres → query/UI
Obsidian/RAG automation pipeline
local AI routing: Hermes/LiteLLM/llama.cpp/Ollama/provider boundaries
OpenVINO NPU assistant sidecars, with live baseline and approved/not-live prototype lanes separated
messaging/channel routing: Telegram/Discord/email → Hermes/n8n/alerts
disaster recovery / backup topology

Style rules

Prefer standalone .html files with inline SVG so they render offline in any browser.
Keep the source file committed alongside the docs; do not rely on generated screenshots as the only artifact.
Link diagrams from the nearest README or operational doc.
Keep labels operational: service name, port, responsibility, and data direction.
Avoid secrets, credential names that imply secret values, private tokens, raw webhook URLs, or sensitive sample payloads.
Do not imply live Atlas/Hermes/RAG routing to an OpenVINO NPU prototype unless a reviewed implementation actually enabled it; label approved prototypes as not live or approval required.
If a raw export or live config was used to build the diagram, commit only the sanitized diagram/docs, not the raw sensitive source.

Verification before committing

# Check the files are valid text and do not contain obvious secret markers
python - <<'PY'
from pathlib import Path
for p in Path('docs').glob('*.html'):
    text = p.read_text()
    hits = [s for s in ['api_key', 'token', 'password', 'Authorization', 'Bearer ', 'secret'] if s.lower() in text.lower()]
    print(p, hits)
PY

# Inspect targeted diff only
git diff --stat -- docs README.md

After editing diagrams, commit with a docs-focused message, for example:

git add docs/*.md docs/*.html README.md
git commit -m "docs: update swarm infrastructure diagrams"

2.8 KiB Raw Permalink Blame History