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
- 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 
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.
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Что в PR
Удалён SVG-вариант диаграммы (4-колоночный layout был слишком noisy для IP-уровня деталей). Оставлен только Mermaid.
Зачем
Mermaid читается за 5 секунд. SVG требовал 30+ секунд на разбор. Для high-level prod map этого достаточно — для деталей по IP есть команды в README, которые можно дёрнуть при необходимости.
Review checklist
Связанные
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: 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.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.