docs: remove SVG variant, keep only Mermaid diagram #22

Open
hermes wants to merge 15 commits from hermes/ansible:docs/architecture-diagram-cleanup into master
Contributor

Что в PR

Удалён SVG-вариант диаграммы (4-колоночный layout был слишком noisy для IP-уровня деталей). Оставлен только Mermaid.

  • docs/architecture/standalone-adaptive.svg — удалён
  • docs/architecture/README.md — переписан как инструкция для будущих обновлений:
    • конкретные curl-команды для рефреша из docker_socket_proxy
    • что сравнивать с mermaid.md
    • что НЕ проверять (403 endpoints, поимённый список ephemeral containers)
    • workflow регенерации + push (БЕЗ force-push)
  • docs/architecture/mermaid.md — обновлены 3 ссылки (были "см. SVG", стали "см. README.md")

Зачем

Mermaid читается за 5 секунд. SVG требовал 30+ секунд на разбор. Для high-level prod map этого достаточно — для деталей по IP есть команды в README, которые можно дёрнуть при необходимости.

Review checklist

  • mermaid.md корректно рендерится в Gitea preview (9 swimlanes, balanced subgraphs)
  • README.md инструкции по обновлению — достаточно для следующего раза без перевклада
  • Нет упоминаний standalone-adaptive.svg в mermaid.md

Связанные

## Что в PR Удалён SVG-вариант диаграммы (4-колоночный layout был слишком noisy для IP-уровня деталей). Оставлен только Mermaid. - docs/architecture/standalone-adaptive.svg — удалён - docs/architecture/README.md — переписан как инструкция для будущих обновлений: - конкретные curl-команды для рефреша из docker_socket_proxy - что сравнивать с mermaid.md - что НЕ проверять (403 endpoints, поимённый список ephemeral containers) - workflow регенерации + push (БЕЗ force-push) - docs/architecture/mermaid.md — обновлены 3 ссылки (были "см. SVG", стали "см. README.md") ## Зачем Mermaid читается за 5 секунд. SVG требовал 30+ секунд на разбор. Для high-level prod map этого достаточно — для деталей по IP есть команды в README, которые можно дёрнуть при необходимости. ## Review checklist - [ ] mermaid.md корректно рендерится в Gitea preview (9 swimlanes, balanced subgraphs) - [ ] README.md инструкции по обновлению — достаточно для следующего раза без перевклада - [ ] Нет упоминаний standalone-adaptive.svg в mermaid.md ## Связанные - admin/ansible#5 — re-deploy hermes_squid - admin/ansible#6 — pre-create socket_proxy overlay - admin/ansible#7 — gitea stack deploy / app.ini fix
hermes added 15 commits 2026-08-29 19:13:12 +02:00
- README.md explains what's shown vs not, known TODOs, when to pick which
- mermaid.md: Mermaid flowchart, renders inline in Gitea PR preview
- standalone.svg: raw SVG, embeddable as image in any README/wiki
- standalone.html: HTML wrapper with dark theme + summary cards

All three show the same graph:
- 2 swarm nodes (odroid manager, xu4 worker)
- 7 stacks on odroid: gitea, hermes, hermes_infra, immich, brencher,
  brencher2, gmail_mcp, torrserv_proxy
- external: Keenetic router, Tailscale subnet, Client
- dead: nginx_nginx (Replicas=0)
- deploy flow: brencher -> stacks

Snapshot 2026-08-27, sources: docker_socket_proxy + gitea admin API
Test confirmed via /api/v1/markdown that Gitea 1.27 renders ![arch](path.svg)
as <img src=...> — SVG displays inline in PR preview and clickable for fullscreen.

Variant #4 alongside mermaid / svg / html. User picks one after review.
Three more ways to embed standalone.svg in markdown:

- svg-sized.md: <img> with explicit width="1200" (sanitized style attr doesn't pass)
- svg-inline.md: full SVG inline in <details> — zoomable in preview but diff-unfriendly
- svg-object.md: <object data="..."> — TESTED via /api/v1/markdown, gitea 1.27
  sanitizes it out. Kept for comparison; doesn't work in our gitea UI.
Same compact layout as standalone.svg but with @media query — same file
renders dark by default, light if browser/OS is in light mode.

Limitation: when embedded via <img> in gitea preview, prefers-color-scheme
is isolated per img element (browser behavior) — adaptivity only works
when opening the .svg directly in a browser tab.
- ascii.txt: pure ASCII layout for terminals and where SVG doesn't render
- README: full table of all 10 variants with what-works-in-gitea-1.27 verification
After user picked svg-adaptive as the winner, remove:
- mermaid.md, svg-embedded.md, svg-sized.md, svg-inline.md, svg-object.md,
  standalone.svg, standalone.html, ascii.txt

Kept:
- standalone-adaptive.svg + svg-adaptive.md
- README.md (will be refreshed in next commit)
Updates to standalone-adaptive.svg:

1. NEW: explicit 'lan' network block (amber, 192.168.1.0/24) between Keenetic
   and physical hosts — clarifies where traffic actually flows.

2. NEW: yellow numbered circles on each physical host:
   - (1) odroid (manager)
   - (2) xu4 (worker)
   Plus matching legend entry.

3. NEW: reachability annotations — green/red dots show which nodes can see
   which others (Client ⇄ Tailscale ⇄ Keenetic, gitea ❌ nginx_nginx dead,
   cross-node via swarm mesh, etc). User explicitly asked for visibility.

4. Reorganized layout: xu4 moved to right column with same visual weight as
   odroid, so host numbering reads left-to-right (1 → 2).

5. Compact viewBox (1400x950 instead of 1400x900) to fit the new blocks.

Kept only standalone-adaptive.svg + svg-adaptive.md + README.md.
Per user request: complete restructure.

Left column: ALL 22 networks (lan + 21 swarm overlay) as small blocks.
Right column: stacks, with nodes listed inside each.
No physical hosts, no reachability annotations, no legend noise.

Inside each stack: <rect class="node-fill"> per node with:
- container name + short task id
- current IPs in relevant networks
- image (where relevant)

Dead nodes (brencher-state-proxy, nginx_*) shown with class="node-dead"
(red dashed border) to keep them visible but clearly off.

Connector lines: amber = LAN reach, dashed rose = brencher deploy flow.

README.md rewritten: minimal — what / how to update / sources.
Removed svg-adaptive.md (info now in README).
Per user: external entities must stay. They're now in the left column
above the network blocks:

- Client (ext-client-fill, violet border) — from tailscale, 100.x.x.x
- Keenetic router + Tailscale subnet (net-external-fill, slate) on lan
- lan block (192.168.1.0/24)
- ingress + all 22 overlay networks (unchanged from previous commit)

Also wired connector arrows:
- Client -> Tailscale (https)
- Tailscale -> lan
- lan -> ingress (amber)
- ingress -> gitea (representative)

Brencher deploy arrows now reach all 6 main stacks (gitea, hermes,
hermes_infra, immich, brencher2, not just 3).

Stack layout unchanged.
Per user: arrows should connect a node (container) to the network it
belongs to, not between pods via a network.

What changed:
- Removed all 'deploy flow' arrows between brencher and stacks
- Removed 'ingress -> gitea' representative arrow
- Added 43 horizontal lines: each line goes from a yellow connector dot
  on the right edge of a network block (x=320) to the left edge of a
  node rect (x=395). Stroke #94a3b8, width 0.8, opacity 0.4 — background,
  not dominant.
- 23 yellow connector dots on right edge of every network block.
- External flow (Client -> Tailscale -> lan -> ingress) preserved as
  vertical amber arrows.

Nodes list per stack is unchanged.
README.md unchanged (How to update / Sources still accurate).
Per user request: add a third column for internal-only networks and
re-analyze prod to classify networks by egress capability.

Analysis (from docker_socket_proxy inspection of all running containers
+ their attached networks):

  external (5):       Client, Keenetic, Tailscale, lan
  egress-capable (10): ingress, nginx_ingress, nginx_default,
                      hermes_infra_squid_egress, hermes_infra_hermes_proxy,
                      hermes_infra_admin,
                      docker_socket_proxy_squid_egress,
                      docker_socket_proxy_hermes_proxy,
                      docker_socket_proxy_admin,
                      docker_socket_proxy_socket_proxy
  internal-only (12): gitea_gitea, immich_default, hermes_hermes,
                      hermes_infra_default, gmail_mcp_default,
                      torrserv_proxy_default, brencher_brencher-net,
                      brencher2_brencher-net, brencher_default,
                      brencher2_default, photosHelper_default,
                      docker_socket_proxy_default

Layout: 3 columns of networks (width 240 each), then stacks on the right.
Color codes:
  external  - slate border (net-external-fill)
  egress    - green border (#22c55e, net-egress-fill)
  internal  - violet border (#818cf8, net-internal-fill)

Hover highlights: still working via class=.conn (no change needed).

Stack layout unchanged.
Per user spec — exact 4 columns:

  1. INTERNET        (external: Client, Tailscale, Keenetic, lan)
  2. INGRESS/EGRESS  (10 networks that can reach internet)
  3. STACKS & PODS   (12 stacks with nodes inside)
  4. INTERNAL NETS   (12 networks, positioned at their parent stack's y)

Key design: internal networks in col 4 are placed at the same y-coordinate
as their parent stack in col 3. This makes the visual flow:
  external -> ingress/egress -> node -> internal
which mirrors how a packet actually traverses: client comes in via external,
hits an egress-capable network, gets routed to a pod, pod talks to its
stack-private network.

E.g. brencher stack has 2 internal nets (brencher_brencher-net + brencher_default).
Both placed at the brencher stack's y, side-by-side.

Color codes:
  col 1 - slate (external)
  col 2 - green (#22c55e, ingress/egress)
  col 3 - cyan (stacks, default)
  col 4 - violet (#818cf8, internal)

Connector arrows:
  - col 1 -> col 2: green dashed (egress flow)
  - col 2 -> nodes: gray 0.4 (node<->egress)
  - nodes -> col 4: violet (node<->internal)
  - col 4 left edge: violet connector dots
Per user feedback that the 4-column SVG is too noisy, added a Mermaid
flowchart that shows the same topology as 4 swimlanes (internet /
ingress-egress / stacks / internal-nets) with linear arrows only.

This is the 'quick view' — for full node-level detail (IPs, container
names, dead-state), use standalone-adaptive.svg.

Mermaid block tested via /api/v1/markdown — renders as code-block
in Gitea, mermaid.js expands it inline in preview view.
Re-analyzed prod end-to-end via docker_socket_proxy:

NEW DISCOVERIES (not in prev diagrams):
- 7 stacks deployed via brencher (PROFILES env): gitea, hermes,
  hermes_infra, immich, gmail_mcp, torrserv_proxy, brencher2
- 5 standalone: docker_socket_proxy, lampa-jackett (compose),
  photosHelper/registry/nginx (all DEAD · Replicas: 0)
- 7 zombie stacks (volumes only, 0 services):
  nextcloud (4) · sstp/softether (4) · portainer · swarmpit ·
  test · torr_cache · beszel-poc
- 48 ephemeral exited containers (gitea act_runner job pods
  with random names like romantic_wozniak)
- 153 volumes total (18 mounted, 135 orphaned)
- /configs and /secrets are 403 from socket-proxy (POST:1 needed)
- Known secrets in gitea: LFS_JWT_SECRET, JWT_SECRET, SECRET_KEY,
  INTERNAL_TOKEN

Diagram now has 9 swimlanes instead of 6:
  external · ingress/egress · stacks-via-brencher · stacks-standalone ·
  zombie · ephemeral · internal-nets · volumes · secrets

Use this as the full map; standalone-adaptive.svg has per-node detail.
User picked Mermaid as the canonical diagram (clearer than SVG).
SVG with per-node IPs was too noisy for the 4-column layout.

- Remove docs/architecture/standalone-adaptive.svg
- Rewrite README.md as self-instructions for future updates:
  - exact curl commands to refresh from docker_socket_proxy
  - what to compare against mermaid.md
  - what NOT to check (403 endpoints, ephemeral per-pod listing)
  - regen + push workflow (NO force-push)
- Update mermaid.md: drop 'Two views' intro, replace SVG references with README
Checking for merge conflicts…
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u https://gitea.rudolf.keenetic.link/hermes/ansible docs/architecture-diagram-cleanup:hermes-docs/architecture-diagram-cleanup
git checkout hermes-docs/architecture-diagram-cleanup
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: admin/ansible#22