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
14 Commits
Author SHA1 Message Date
hermes ea077a10a0 docs: comprehensive prod map — add all stacks, zombie, ephemeral
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.
2026-08-27 18:12:03 +00:00
hermes 463da2e48b docs: add Mermaid variant for simplified flow diagram
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.
2026-08-27 18:04:55 +00:00
hermes cb285a5461 docs: 4-column layout (internet / ingress-egress / stacks / internal-nets)
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
2026-08-27 17:59:49 +00:00
hermes 67797c8e7d docs: split networks into 3 columns (external/egress/internal)
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.
2026-08-27 17:49:55 +00:00
hermes 3e68768a22 docs: change arrows from pod-pod to node-network
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).
2026-08-27 17:36:32 +00:00
hermes 23bb1e8a70 docs: bring back Client + Tailscale + Keenetic in left column
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.
2026-08-27 17:32:47 +00:00
hermes 8dc466ced3 docs: rewrite diagram as 2-column (networks left, stacks right)
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).
2026-08-27 17:29:12 +00:00
hermes df1b2ce715 docs: add lan network + numbered host circles + reachability
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.
2026-08-27 17:08:18 +00:00
hermes d500dc04cc docs: drop 8 unused diagram variants
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)
2026-08-27 17:08:18 +00:00
hermes 8672f0db37 docs: add ascii variant and refresh README
- 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
2026-08-27 12:08:33 +00:00
hermes cd1956aaeb docs: add adaptive SVG (prefers-color-scheme light/dark)
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.
2026-08-27 12:08:33 +00:00
hermes e8fa7e8be4 docs: add svg-sized, svg-inline, svg-object variants
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.
2026-08-27 12:08:33 +00:00
hermes 7dab6c89ad docs: add svg-embedded variant (markdown referencing standalone.svg)
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.
2026-08-27 12:03:50 +00:00
hermes 793908ae14 docs: add production architecture diagram in three formats
- 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
2026-08-27 11:57:44 +00:00