The route from a click to a tube map is drawn, twice

[turner]

Sequence and interaction diagrams for the seqtubemap pipeline, in Markdown and HTML.

The route crosses two repositories, three processes and five file formats, and
until now it was only readable by following it through the source. These
documents draw it end to end: a right-click on a node in pgb, through the
eligibility gate that has to live in the client because the API answers an
unknown minigraphnode with 200, through /seqtubemap — format validation,
the walk-checked cache, gbz extraction, the tabix walk lookup, vg convert -g
and vg view -j, the PCLAI lookup — into the spawned Node render, and back out
as a band payload the viewer reads without a regular expression.

What is in them

• Architecture overview: every participant, and the one seam that matters —
  everything above BandCollector computes numbers, everything below encodes
  them.
• An end-to-end sequence, then five detail sequences: the click becoming a URL,
  the region becoming vg JSON, the vg JSON becoming band data, the layout
  passes inside createTubeMap, and the bytes becoming a picture again.
• The band grammar — six numbers and a strand id — and why six is enough.
• The two sinks, side by side, with the payload's byte layout.
• The measured stage timings from docs/perf/, on one shared scale.
• The invariants the route rests on, each pointed at the file that holds it.

Two documents, one subject

docs/seqtubemap-interaction.md carries the diagrams as Mermaid, in the shape
of pgb's annotation-track-interaction.md, so the two repositories describe
themselves the same way.

docs/seqtubemap-interaction.html redraws them as ruled lifeline charts —
dashed lifelines, solid arrows for calls and dashed for returns, the client
half and the server half in the two colours docs/tube-map-pipeline.html
already uses. It reuses that document's type and palette so the three HTML docs
in docs/ read as a family. Published at
https://claude.ai/code/artifact/ca74cc4a-c68c-452a-9682-3c8480705b36

Vocabulary throughout is CONTEXT.md's: node, segment, strand,
band, pivot strand, region.

Not verified in this branch

Two claims are carried over from the source they document rather than re-run
here: that pathnumoption's presence is what returns 369 strands instead of
46 (pgb's finding, recorded in pangenomeURL.ts), and that the
band-thickness and dense-strand-id invariants throw in band-data.mjs — read
from the code and its tests' descriptions, not executed.

Documentation only. No code changes, no test changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_015wyakF7DEbvddMqaL9kSB6