# Diagram maintenance

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

## Current diagrams

- [`swarm-infrastructure.html`](./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

```bash
# 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:

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