Talkyard architecture & internals — a visual reference

This is the landing page for a short series of reference topics that map out how a stock Talkyard install fits together: the containers it runs, the networks they sit on, the state they persist, and the path a single page request travels from the browser to the database and back. Everything here describes stock Talkyard as of v1.2026.003, drawn from the running server and its compose files, then adversarially fact-checked against the source.

Each companion topic is built around Mermaid diagrams that render client-side in the browser. Rather than prose walls, the goal is a picture you can scan — container roles and versions, network subnets and their internal/public flags, named volumes and docker secrets, the backup pipeline, and the render-cache chain — with just enough text to explain the key nodes and edges. Note that the deployment shown is deliberately generic: your own ingress, TLS termination, and reverse-proxy choices sit in front of what's described here and vary per install.

The three companion topics:

• Deployment topology: containers, networks & traffic — the seven service containers (web, app, cache, rdb, search, rendr, egressp) plus the one-shot backup job, what software and version each runs, the five compose networks with their 172.26.{1..5}.0/24 subnets and internal-vs-public flags, and who talks to whom at runtime.
• State: volumes, secrets & the backup pipeline — the named volumes and docker secrets each container mounts, and how the stock talkyard-backup image dumps the database (pg_dumpall), archives uploads, and optionally GPG-encrypts the result at rest as a profiles: [backup] one-shot.
• Request lifecycle: how a page renders — one page request traced end to end: the in-JVM memory cache, the Postgres page_html cache and its content-hash / stale-serve-then-re-render behaviour, per-user volatile JSON, upload auth subrequests, and how live updates arrive over the WebSocket.

Cross-links:

• Deployment topology: containers, networks & traffic
• State: volumes, secrets & the backup pipeline
• Request lifecycle: how a page renders

(Staff can also see a deployment-specific companion, “This deployment”, in the Staff area.)