William Valentin
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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
|
|
- 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
|
|
- 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.
|
|
- 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"
|
|
```
|