Skip to content

docs(architecture): scaffold animated Protocol Reference section#2949

Open
chefsale wants to merge 44 commits into
masterfrom
docs/protocol-reference-skeleton
Open

docs(architecture): scaffold animated Protocol Reference section#2949
chefsale wants to merge 44 commits into
masterfrom
docs/protocol-reference-skeleton

Conversation

@chefsale

Copy link
Copy Markdown
Member

What

Starts a new Protocol Reference under architecture/protocol/ — an implementation-level guide aimed at someone building an independent Calimero node from scratch. It's organised around the life of one operation (birth → convergence) rather than crate by crate.

This is a walking skeleton / template-setter, not the full reference. It establishes the structure, voice, and diagram style so the remaining chapters can be filled in consistently.

Contents

  • protocol/index.html — section landing page: the one core idea, an animated life-of-an-operation sequence diagram, the four writing principles, and the 10-chapter TOC with draft/planned status chips.
  • protocol/concepts.html — Chapter 1 (Concepts & Scopes): defines the scope abstraction (the replication/encryption/membership/convergence domain) with an animated scope-tree diagram.
  • seq-diagram.js + styles.css — the step-cascade animated-SVG engine, extracted out of sequence-diagrams.html into shared assets so every page reuses it. Data-driven sequence diagrams + a prefers-reduced-motion fallback.
  • nav.js — registers the new section and tidies two auto-generated PR-title nav labels into clean names.

How to preview

⚠️ GitHub Pages here only deploys from master (pages.yml), so this PR has no auto preview URL. To view locally:

cd architecture && python3 -m http.server 8000
# open http://localhost:8000/protocol/

Notes / follow-ups

  • All diagrams are animated SVG (no mermaid), matching the existing docs style.
  • Before merging to master, we should fence architecture/protocol/** out of the doc auto-update bot so hand-authored pages aren't clobbered.
  • Next chapters to author: 3 (Operations & the DAG) + 4 (Projection & root hash).

🤖 Generated with Claude Code

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant