docs: add production architecture diagram in three formats (mermaid, svg, html) #10

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

Что в PR

Четыре варианта одной диаграммы продакшна:

Файл Формат Как смотреть
docs/architecture/mermaid.md Markdown + Mermaid Gitea PR preview, любой MD-рендерер
docs/architecture/svg-embedded.md Markdown со ссылкой на SVG Gitea рендерит SVG как <img>
docs/architecture/standalone.svg Raw SVG открыть в браузере / вставить в README / в slack
docs/architecture/standalone.html HTML с inline SVG, dark theme открыть в браузере, есть summary cards
docs/architecture/README.md Описание всех вариантов + TODO Gitea

Технический факт

Проверил через POST /api/v1/markdown что Gitea 1.27 рендерит ![arch](standalone.svg) как:

<a href=".../src/standalone.svg">
  <img src=".../media/standalone.svg" alt="arch" loading="lazy"/>
</a>

То есть SVG-embedded вариант точно работает в preview.

Что на диаграмме

  • 2 swarm nodes (odroid manager, xu4 worker)
  • 7 stacks на odroid: gitea, hermes, hermes_infra, immich, brencher, brencher2, gmail_mcp, torrserv_proxy
  • External: Keenetic (DNS + Let's Encrypt), Tailscale (subnet router), Client
  • Dead component: nginx_nginx (Replicas=0)
  • Deploy flow: brencher → стеки (dashed rose arrows)

Snapshot 2026-08-27, sources: docker_socket_proxy + gitea admin API + gitea_server logs.

Известные TODO

  1. endpoint.Ports у gitea_server пустое, но ingress маршрутизирует.
  2. xu4 worker пуст в снапшоте.
  3. nginx_nginx Replicas=0 — dead, overlay-сеть nginx_ingress жива.
  4. Tailscale роль — subnet router, не MagicDNS.
  5. Дополнительные уровни (networks, secrets, deploy flow) — после выбора формата.

Review checklist

  • Открыть mermaid.md в Gitea preview — рендерится ли Mermaid?
  • Открыть svg-embedded.md в Gitea preview — видна ли SVG-картинка?
  • Открыть standalone.svg в браузере — все надписи видны?
  • Открыть standalone.html в браузере — summary cards ок?
  • Решить какой формат оставить (или все четыре)
## Что в PR Четыре варианта одной диаграммы продакшна: | Файл | Формат | Как смотреть | |---|---|---| | `docs/architecture/mermaid.md` | Markdown + Mermaid | Gitea PR preview, любой MD-рендерер | | `docs/architecture/svg-embedded.md` | Markdown со ссылкой на SVG | Gitea рендерит SVG как `<img>` | | `docs/architecture/standalone.svg` | Raw SVG | открыть в браузере / вставить в README / в slack | | `docs/architecture/standalone.html` | HTML с inline SVG, dark theme | открыть в браузере, есть summary cards | | `docs/architecture/README.md` | Описание всех вариантов + TODO | Gitea | ## Технический факт Проверил через `POST /api/v1/markdown` что Gitea 1.27 рендерит `![arch](standalone.svg)` как: ```html <a href=".../src/standalone.svg"> <img src=".../media/standalone.svg" alt="arch" loading="lazy"/> </a> ``` То есть SVG-embedded вариант **точно работает** в preview. ## Что на диаграмме - 2 swarm nodes (odroid manager, xu4 worker) - 7 stacks на odroid: gitea, hermes, hermes_infra, immich, brencher, brencher2, gmail_mcp, torrserv_proxy - External: Keenetic (DNS + Let's Encrypt), Tailscale (subnet router), Client - Dead component: nginx_nginx (Replicas=0) - Deploy flow: brencher → стеки (dashed rose arrows) Snapshot 2026-08-27, sources: `docker_socket_proxy` + gitea admin API + gitea_server logs. ## Известные TODO 1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует. 2. `xu4` worker пуст в снапшоте. 3. `nginx_nginx` Replicas=0 — dead, overlay-сеть `nginx_ingress` жива. 4. Tailscale роль — subnet router, не MagicDNS. 5. Дополнительные уровни (networks, secrets, deploy flow) — после выбора формата. ## Review checklist - [ ] Открыть `mermaid.md` в Gitea preview — рендерится ли Mermaid? - [ ] Открыть `svg-embedded.md` в Gitea preview — видна ли SVG-картинка? - [ ] Открыть `standalone.svg` в браузере — все надписи видны? - [ ] Открыть `standalone.html` в браузере — summary cards ок? - [ ] Решить какой формат оставить (или все четыре)
hermes added 1 commit 2026-08-27 13:58:23 +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
hermes added 1 commit 2026-08-27 14:03:56 +02:00
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.
hermes added 3 commits 2026-08-27 14:08:50 +02:00
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
hermes added 2 commits 2026-08-27 19:08:33 +02:00
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.
hermes added 1 commit 2026-08-27 19:29:19 +02:00
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).
hermes added 1 commit 2026-08-27 19:32:52 +02:00
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.
hermes added 1 commit 2026-08-27 19:36:38 +02:00
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).
hermes added 1 commit 2026-08-27 19:50:01 +02:00
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.
hermes added 1 commit 2026-08-27 19:59:54 +02:00
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
hermes added 1 commit 2026-08-27 20:05:02 +02:00
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.
hermes added 1 commit 2026-08-27 20:12:09 +02:00
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.
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:hermes-docs/architecture-diagram
git checkout hermes-docs/architecture-diagram
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#10