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
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.
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 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: 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: 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 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).
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.
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)
- 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
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.
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.
Test confirmed via /api/v1/markdown that Gitea 1.27 renders 
as <img src=...> — SVG displays inline in PR preview and clickable for fullscreen.
Variant #4 alongside mermaid / svg / html. User picks one after review.
- 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