Explanation
Understanding-oriented documentation - Concepts, design decisions, and the "why" behind ngit-grasp.
What Is Explanation?
Explanation documentation helps you understand concepts and design decisions, providing context and discussing alternatives.
Characteristics:
- ✅ Understanding-oriented (clarify concepts)
- ✅ Theoretical (ideas and design)
- ✅ Discuss alternatives
- ✅ Provide context and background
- ✅ Answer "why" questions
Not explanation:
- ❌ Step-by-step lessons (those are Tutorials)
- ❌ Problem-solving recipes (those are How-To)
- ❌ Technical specifications (those are Reference)
Available Explanation Documentation
Architecture Overview
Understand the system design and component interaction
Topics:
- Overall architecture
- Component responsibilities
- Data flows
- Technology choices
- Design patterns
Read when: You want to understand how ngit-grasp works as a system
Inline Authorization
Why we validate pushes inline instead of using Git hooks
Topics:
- The authorization problem
- Git hooks approach
- Inline approach
- Comparison and trade-offs
- Implementation details
Read when: You want to understand the core architectural decision
Design Decisions
Key architectural choices and their rationale
Topics:
- Inline authorization vs hooks
- Technology stack choices
- Storage design
- API design
- Performance considerations
Read when: You want to know why things are the way they are
Comparison with ngit-relay
How ngit-grasp differs from the reference implementation
Topics:
- Architecture comparison
- Component differences
- Trade-offs
- Migration path
- Compatibility
Read when: You're familiar with ngit-relay and want to understand differences
Purgatory Design
In-memory holding area for events awaiting git data
Topics:
- The "which arrives first?" problem
- Separate storage for state vs PR events
- Late binding for state events
- Bidirectional waiting for PR events
- Authorization during push
Read when: You want to understand how ngit-grasp handles out-of-order event/git data arrival
GRASP-02 Proactive Sync
Relay-to-relay synchronization for repository discovery
Topics:
- Negentropy-based event sync
- Repository announcement discovery
- Relay management and reconnection
- Layer 2 filtering
- Bootstrap and dynamic relay discovery
Read when: You want to understand how ngit-grasp discovers and syncs repositories across relays
GRASP-02 Purgatory Git Data Fetching
Proactive git data fetching from remote servers
Topics:
- Identifier-based batching
- Exponential backoff with fresh start
- Domain throttling (5 concurrent, 30/min)
- Debounced delays (3min user, 500ms sync)
- 30-minute expiry
- Mock-based testability
Read when: You want to understand how purgatory automatically fetches missing git data
Unified Git Data Sync
Shared processing for git push and purgatory sync paths
Topics:
- Why unify push and sync processing
- OID syncing to owner repos
- Ref alignment logic
- Event release from purgatory
- WebSocket notification
Read when: You want to understand how git data is processed consistently regardless of arrival method
Monitoring Overview
Prometheus metrics and observability
Topics:
- Metrics philosophy
- Connection tracking
- Git operation metrics
- Nostr event metrics
- Privacy considerations
Read when: You want to understand how to monitor ngit-grasp in production
Defensive Measures & Rate Limiting
Protection against abuse, spam, and denial-of-service attacks
Topics:
- Connection and subscription management
- Event publishing rate limits
- Content filtering (blacklists/whitelists)
- Event validation plugin system (WritePolicy/QueryPolicy)
- Relay health management (naughty list, exponential backoff)
- Privacy-preserving IP tracking
- Future enhancements (per-IP rate limiting)
Read when: You want to understand how ngit-grasp protects against abuse and what defensive features are available
GRASP-05 Archive Mode
Read-only mirroring of repositories
Topics:
- Archive whitelist configuration
- Archive-all mode
- Read-only mode defaults
- Use cases for backup/mirror relays
Read when: You want to understand how to run an archive/backup relay
Deletion Requests
Handling repository and event deletion
Topics:
- Deletion request architecture
- Delete disrespector concept
- Preventing left-pad scenarios
- Archival policies
Read when: You want to understand how ngit-grasp handles deletion events (planned feature)
Planned Explanation Documentation
GRASP Protocol Design
Status: 🔜 Planned
Topics:
- Why Nostr for Git?
- Authorization model
- Trust and verification
- Decentralization benefits
Storage Architecture
Status: 🔜 Planned
Topics:
- Why separate Git and Nostr storage?
- Indexing strategy
- Performance considerations
- Scaling approach
Testing Philosophy
Status: 🔜 Planned
Topics:
- Why test isolation?
- Integration vs unit tests
- Compliance testing approach
- Test-driven development
Performance Considerations
Status: 🔜 Planned
Topics:
- Async architecture
- Caching strategy
- Database choices
- Bottlenecks and solutions
How to Use Explanation Documentation
- Read to understand - Not to accomplish a task
- Follow your curiosity - Read what interests you
- Connect concepts - Link ideas together
- Question and explore - Think critically
Not sure if this is what you need?
- Want to learn by doing? → Tutorials
- Need to solve a problem? → How-To Guides
- Looking for technical details? → Reference
Contributing Explanation Documentation
When writing explanation:
DO:
- ✅ Discuss concepts and ideas
- ✅ Provide context and background
- ✅ Explain alternatives
- ✅ Use analogies and examples
- ✅ Connect to broader context
- ✅ Answer "why" questions
DON'T:
- ❌ Provide step-by-step instructions (link to Tutorials/How-To)
- ❌ List technical details (link to Reference)
- ❌ Assume you must be comprehensive
- ❌ Avoid opinions (explanation can be opinionated)
Template:
# Explanation: [Topic]
**Purpose:** [What concept/decision this explains]
**Audience:** [Who wants to understand this]
---
## The Problem/Question
[What are we trying to understand?]
---
## Background
[Context and history]
---
## Our Approach
[How we address it]
### Why This Works
[Explanation of benefits]
### Trade-offs
[What we gain and lose]
---
## Alternatives Considered
### [Alternative 1]
**Pros:**
- [Benefits]
**Cons:**
- [Drawbacks]
**Why we didn't choose it:**
[Reasoning]
---
## Conclusion
[Summary of understanding]
---
## Related Documentation
- [Links to relevant docs]
See Diátaxis: Explanation for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.