docs: document how the portal, Triage and Backoffice work together

[mirrec]

The problem

Nobody has a full picture of what the system does today. A portal issue passes through three apps: the portal, the Triage Zammad and a municipality's Backoffice Zammad. They are connected by jobs, webhooks, Zammad triggers, core workflows and schedulers, and several of those pieces live only in the Zammad databases. Questions like "what does Triage set on a praise", "what happens when the volunteer asks for a supplement", or "how does a Backoffice note get to the portal" need code archaeology every time. That makes it hard to plan the integration tests, to see which parts have no tests, and to spot broken or unhandled flows.

Solution

A docs/how-it-works/ folder that maps every user flow and every sync, kept in the repo so it changes together with the code:

• README.md: index and how to keep it true.
• 01–10: one file per area (overview and system map, issue lifecycle, submission and triage, resolution, praise, comment routing, Backoffice connector, onboarding, emails, scheduled work). Each has Mermaid diagrams and file:line references.
• coverage.md: flow × test matrix from a fresh bin/rails test:all (582 runs, 77.9% lines, 58.2% branches), plus the team's planned integration scenarios mapped to what exists.
• glossary.md: the terms used across the docs and the apps.
• An Open issues table at the end of each affected file. It links the known problems in that flow to issues in the private ops repo (epic slovensko-digital/ops#1349: 29 issues with severity, category, evidence, diagrams and a proposed fix). Dead code, setup and security are separate issues there (#1317, #1318, #1319).

The main README.md links to it from a new "How it works" section and from "Connect new Backoffice instance", which also warns that the snippet fails for municipalities created by activate_basic, and how to fix it.

Everything marked (observed) was clicked through on 2026-10-15 with all three apps running locally (Rajec connected as a PRO municipality). The rest comes from reading the code. Each fix should get its own PR, which updates the affected section and removes the issue's row. This PR changes no behaviour.

The problems to look at first:

• slovensko-digital/ops#1320: a ticket from a municipality without a 700 routing rule stays in Triage Incoming, which no volunteer can see.
• slovensko-digital/ops#1321: an RS reassign or refer shows up twice on the portal and is mailed twice.
• slovensko-digital/ops#1326: Backoffice subtasks are lost after a deploy. The tech account can't access "Podúlohy" until a 15-minute scheduler runs, and the scheduler is reset on every restart.
• slovensko-digital/ops#1327: sync jobs give up after about 6 minutes, and nothing reconciles what they dropped.
• slovensko-digital/ops#1323: "supplementing a rejected issue" from the planned test list has no flow behind it.

The flow docs describe only what happens and why. How to run a Backoffice locally next to the portal and Triage, including the .env overrides the Backoffice sample needs and the 127.0.0.1:8081 cookie workaround, is a new "Local Backoffice" section in the main README.md.

To keep the docs true, CLAUDE.md now maps code paths to the doc file each one should update, and the PR template has a "Checklist" section with a docs checkbox. The Triage and Backoffice repos get a matching CLAUDE.md in slovensko-digital/ops-triage-zammad#126 and slovensko-digital/ops-backoffice-saas#85.

Verify: read the files on GitHub. All 16 Mermaid diagrams were checked with Mermaid's parser and render in the file view.

Demo

Not applicable, this is documentation only. The diagrams render directly in GitHub's view of docs/how-it-works/.

Checklist

• docs/how-it-works/ is updated, or this PR changes no flow (job, webhook, Triage or Backoffice trigger, issue state, email, scheduled job)