ngit-grasp/docs/explanation

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

---

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
• 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.