Skip to content

docs: add an animated LNURL-pay flow diagram to the project page - #39

Merged
Chemaclass merged 1 commit into
mainfrom
docs/flow-diagram
Aug 1, 2026
Merged

docs: add an animated LNURL-pay flow diagram to the project page#39
Chemaclass merged 1 commit into
mainfrom
docs/flow-diagram

Conversation

@Chemaclass

Copy link
Copy Markdown
Contributor

Summary

Adds two graphics to the project page so a reader can see how a Lightning Address works
instead of parsing four paragraphs about it.

Address anatomy

A static figure that makes the central point: a Lightning Address is not new protocol.
bob@example.com splits into the domain you control and a well-known path, which join
into the URL a wallet opens — the URL this library answers.

Payment flow

A seven-step sequence diagram between the payer's wallet, your domain (highlighted as
"this library") and your node:

  1. GET /.well-known/lnurlp/bob
  2. pay params — min, max, callback
  3. GET /bob?amount=2000
  4. POST /api/v1/payments to your backend
  5. bolt11 invoice back
  6. { "pr": "lnbc20n1p…" } to the wallet
  7. the wallet pays the invoice over Lightning

A packet travels along the active arrow, the step is described underneath in plain
language, and the surrounding copy calls out which steps the library answers and that the
sats never pass through it.

Behaviour

  • Autoplays only while the diagram is in the viewport (IntersectionObserver), stops when
    the tab is hidden.
  • ‹ / Pause / › plus numbered step buttons; any manual interaction stops autoplay for
    good.
  • Under prefers-reduced-motion: reduce autoplay is off and the packet does not animate —
    the diagram still works as a manual stepper.
  • No external assets: inline SVG, inline CSS, ~90 lines of vanilla JS. Works with the same
    light/dark handling as the rest of the page.

Verification

Rendered headless (Chrome) in both colour schemes and at narrow widths:

  • light and dark palettes both check out, including the teal/amber pairing in the figures
  • no horizontal overflow: scrollWidth == clientWidth, no offending elements
  • inline <code> now wraps (overflow-wrap: anywhere) so long URLs cannot push the page
    sideways on a phone

Also adds the CHANGELOG entry for the Pages site, which #38 did not include.

Test plan

  • HTML well-formed, script passes node --check, 7 captions ↔ 7 diagram steps
  • composer test-all unaffected and green
  • Pages deployment renders the new section after merge

Two graphics replace the prose walkthrough on the landing page:

- an address-anatomy figure showing that bob@example.com is just a domain and
  a path, i.e. plain HTTPS
- a seven-step sequence diagram between the payer's wallet, this library and
  your node, with a travelling packet, per-step captions and prev/pause/next
  controls

The animation autoplays only while the diagram is on screen, stops when the
tab is hidden, and is off by default under prefers-reduced-motion, where the
diagram still works as a static stepper. No external assets.
@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Aug 1, 2026
@Chemaclass Chemaclass self-assigned this Aug 1, 2026
@Chemaclass
Chemaclass merged commit c3ee8ee into main Aug 1, 2026
8 checks passed
@Chemaclass
Chemaclass deleted the docs/flow-diagram branch August 1, 2026 23:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant