# Explanation Template (Diátaxis: Understanding-Oriented)

**Purpose:** Help users understand concepts, architecture, and the "why" behind decisions.

**When to use:**
- Architecture documentation
- Conceptual overviews
- Background knowledge
- Design decisions (ADRs)
- "How it works" content

## Format

```mdx
---
title: Understanding [Concept]
description: Deep dive into [topic] and how it works
contentType: explanation
---

## Overview

Why this matters: 2-3 sentences explaining the importance of understanding this concept.

## Background / Context

What problem does this solve? What existed before?

## How It Works

### High-Level Architecture

```mermaid
flowchart TB
    subgraph Client[Browser]
        UI[User Interface]
    end
    
    subgraph Server[Backend]
        API[API Layer]
        Logic[Business Logic]
        DB[(Database)]
    end
    
    UI --> API
    API --> Logic
    Logic --> DB
```

### Key Components

| Component | Responsibility | Location |
|-----------|----------------|----------|
| Component A | Does X | `src/a/` |
| Component B | Does Y | `src/b/` |
| Component C | Does Z | `src/c/` |

### The Flow

1. **Step 1**: What happens first and why
2. **Step 2**: What happens next
3. **Step 3**: Final result

### Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant System
    participant External
    
    User->>System: Action
    System->>External: Request
    External-->>System: Response
    System-->>User: Result
```

## Key Concepts

### Concept A

Explanation of the concept with examples.

<Tip>
Key insight or mental model to help understanding.
</Tip>

### Concept B

Another important concept.

### Concept C

Third concept with its relationships to A and B.

## Design Decisions

### Why [Decision X]?

**Context:** What situation led to this decision?

**Decision:** What we decided.

**Rationale:** Why this approach over alternatives.

**Trade-offs:**
- ✅ Benefit 1
- ✅ Benefit 2
- ⚠️ Trade-off 1
- ⚠️ Trade-off 2

### Alternatives Considered

| Option | Pros | Cons | Why Not |
|--------|------|------|---------|
| Option A | Fast | Complex | Too much overhead |
| Option B (chosen) | Simple, maintainable | Slower | Best balance |

## When to Use

| Scenario | Recommendation |
|----------|----------------|
| Scenario A | Use this approach |
| Scenario B | Consider alternative |
| Scenario C | Not recommended |

## Common Misconceptions

<Warning>
**Misconception:** [Common wrong belief]

**Reality:** [Correct understanding]
</Warning>

## Deeper Dive

For those who want to understand more:

- [Technical detail 1]
- [Technical detail 2]
- [Edge cases]

## Related

<CardGroup cols={2}>
  <Card title="Tutorial" href="/tutorial">
    Learn by building with this concept
  </Card>
  <Card title="How-To Guide" href="/how-to">
    Practical tasks using this concept
  </Card>
  <Card title="Reference" href="/reference">
    Complete API reference
  </Card>
</CardGroup>
```

## Guidelines

- **Focus on understanding** - Explain the "why", not just the "what"
- **Use analogies** - Relate to familiar concepts
- **Provide context** - Historical background helps understanding
- **Show relationships** - How concepts connect to each other
- **Address misconceptions** - Clear up common confusion
- **Use diagrams liberally** - Visual aids help comprehension
- **Link to practical content** - Connect to tutorials and how-tos

## Diátaxis Principles for Explanation

| Principle | Application |
|-----------|-------------|
| Understanding-oriented | Focus on comprehension |
| Conceptual | Abstract from specifics |
| Reflective | Encourage thinking |
| Connected | Show relationships |
| Contextual | Provide background |

## Mermaid Diagrams for Explanations

### Architecture Diagram

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        A[Web App]
        B[Mobile App]
    end
    subgraph Services["Service Layer"]
        C[Auth Service]
        D[API Gateway]
    end
    subgraph Data["Data Layer"]
        E[(Database)]
        F[(Cache)]
    end
    A --> D
    B --> D
    D --> C
    D --> E
    D --> F
```

### Data Flow Diagram

```mermaid
flowchart LR
    A[Request] --> B[Validate]
    B --> C{Valid?}
    C -->|Yes| D[Process]
    C -->|No| E[Error]
    D --> F[Response]
    E --> F
```

### Entity Relationship

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
```

### State Machine

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Pending: submit
    Pending --> Approved: approve
    Pending --> Rejected: reject
    Approved --> Published: publish
    Rejected --> Draft: revise
    Published --> [*]
```

## ADR (Architecture Decision Record) Format

```mdx
---
title: "ADR-001: [Decision Title]"
description: Architecture decision record for [topic]
contentType: explanation
---

## Status

Accepted | Proposed | Deprecated | Superseded by ADR-XXX

## Context

What situation led to this decision?

## Decision

What did we decide?

## Rationale

Why this approach over alternatives?

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Trade-off 1
- Trade-off 2

### Neutral
- Change 1
- Change 2

## Alternatives Considered

### Option A: [Name]
- Pros: ...
- Cons: ...
- Why not: ...

### Option B: [Name] (Chosen)
- Pros: ...
- Cons: ...
- Why chosen: ...

## Related Decisions

- [ADR-002](/decisions/002)
- [ADR-003](/decisions/003)
```
