mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
226 lines
4.3 KiB
Markdown
226 lines
4.3 KiB
Markdown
# 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](architecture.md)
|
|
**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](inline-authorization.md)
|
|
**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](decisions.md)
|
|
**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](comparison.md)
|
|
**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
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
1. **Read to understand** - Not to accomplish a task
|
|
2. **Follow your curiosity** - Read what interests you
|
|
3. **Connect concepts** - Link ideas together
|
|
4. **Question and explore** - Think critically
|
|
|
|
**Not sure if this is what you need?**
|
|
- Want to learn by doing? → [Tutorials](../tutorials/)
|
|
- Need to solve a problem? → [How-To Guides](../how-to/)
|
|
- Looking for technical details? → [Reference](../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:**
|
|
```markdown
|
|
# 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](https://diataxis.fr/explanation/) for detailed guidance.
|
|
|
|
---
|
|
|
|
*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
|