Skip to content

docs: add protocol architecture and connection lifecycle guides#5

Open
charantejguniganti wants to merge 1 commit into
seetadev:masterfrom
charantejguniganti:docs/architecture-guides
Open

docs: add protocol architecture and connection lifecycle guides#5
charantejguniganti wants to merge 1 commit into
seetadev:masterfrom
charantejguniganti:docs/architecture-guides

Conversation

@charantejguniganti
Copy link
Copy Markdown

Summary

This PR introduces a new architecture-focused documentation section aimed at improving contributor onboarding and providing a systems-level understanding of how libp2p protocols interact together.

While the repository contains detailed protocol specifications, understanding the overall networking stack currently requires navigating across many independent documents. This PR adds centralized architectural references that connect the transport, security, multiplexing, discovery, and application layers into a cohesive learning flow.

The documentation focuses on:

  • protocol layering
  • connection upgrade lifecycle
  • transport/security/multiplexer relationships
  • protocol negotiation flow
  • peer discovery and application protocol interactions

Changes Included

New Documentation

docs/architecture/
├── protocol-stack-overview.md
└── connection-upgrade-flow.md

Added Content

  • libp2p protocol stack overview with layered architecture diagrams
  • transport vs security vs multiplexing explanations
  • TCP + Noise + Yamux workflow walkthrough
  • QUIC integrated architecture explanation
  • multistream-select negotiation overview
  • connection upgrade lifecycle walkthrough
  • Mermaid sequence diagrams for TCP, QUIC, and WebRTC flows
  • comparison tables (e.g. TCP vs QUIC RTT costs)

README Updates

  • Added an "Architecture Guides" section to improve discoverability
  • Added links to the new documentation pages from the specification index

Why This Helps

This improves:

  • contributor onboarding for DMP/C4GT participants and new contributors
  • architectural discoverability across the specs repository
  • protocol relationship understanding for implementors
  • implementation learning flow for developers new to libp2p
  • navigation across protocol specifications

Design Goals

The documentation intentionally focuses on:

  • additive improvements without modifying existing specifications
  • cross-spec understanding and navigation
  • visual learning via Mermaid diagrams and layered architecture views
  • implementation-oriented explanations
  • maintainable and extensible documentation structure

Future Extensions

Potential follow-up additions could include:

  • transport/security compatibility matrices
  • Relay and DCUtR interaction flows
  • Identify → DHT → PubSub walkthroughs
  • implementation support references across Go/Rust/JS/Python
  • interactive architecture maps

Notes

This PR does not introduce protocol or semantic changes.
It is intended purely as an educational and onboarding-focused documentation enhancement.

@charantejguniganti
Copy link
Copy Markdown
Author

charantejguniganti commented May 8, 2026

[DMP 2026]: Gossipsub 1.4 Large Message Handling, Specification PR and Candidate Recommendation #1

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