Learn

Step 2: Architecture Explanation

## Architecture Deep Dive

In this codebase, we follow [pattern name].

┌─────────────┐ │ Component │ ← UI layer, handles display └─────┬───────┘ │ uses ┌─────▼───────┐ │ Hook │ ← Logic layer, manages state └─────┬───────┘ │ calls ┌─────▼───────┐ │ Service │ ← Data layer, API calls └─────────────┘

**Why this pattern?**
[Explanation of benefits]

Step 3: Incremental Implementation with Teaching

For each piece of code:

## Step N: [What we're doing]

**The concept:**
[Explain the pattern/concept being used]

**Why this approach:**
[Explain the decision]

**The code:**
```typescript
// This creates a [thing] that [does what]
// We use [pattern] because [reason]
export const myFunction = () => {
  // First, we [action] to [achieve goal]
  const result = doSomething();

  // Then we [action] because [reason]
  return transform(result);
};

What just happened:

1. We created [thing]
2. It does [action]
3. This enables [capability]

Try it yourself:

• What would happen if we [changed X]?
• How would you add [feature Y]?

### Step 4: Common Patterns

When using a pattern, explain it:

```markdown
## Pattern: [Pattern Name]

**What it is:**
[One sentence explanation]

**When to use it:**
- Situation 1
- Situation 2

**Example in our code:**
```typescript
// Here's how we apply [pattern]
const example = ...;

Alternatives considered:

• [Alternative] - didn't use because [reason]

### Step 5: Gotchas and Best Practices

```markdown
## Watch Out For

**Common mistake #1:**
```typescript
// ❌ Don't do this
const bad = wrongApproach();

// ✓ Do this instead
const good = correctApproach();

Why: [Explanation]

Common mistake #2: [...]

### Step 6: Summary and Next Steps

```markdown
## What You Learned

1. **[Concept 1]:** [Brief explanation]
2. **[Concept 2]:** [Brief explanation]
3. **[Concept 3]:** [Brief explanation]

## Practice Exercises

1. Try adding [feature] using the same pattern
2. What would you change if [scenario]?
3. How does this connect to [related concept]?

## Further Reading

- [Link or reference 1]
- [Link or reference 2]

Teaching Style Guidelines

Do:

• Explain WHY before HOW
• Use analogies for complex concepts
• Show wrong approaches and why they're wrong
• Build complexity incrementally
• Ask thought-provoking questions
• Connect to broader patterns

Don't:

• Dump code without explanation
• Assume prior knowledge
• Skip over "obvious" concepts
• Use jargon without defining it
• Rush through complex topics

Output Format

──── /learn ────
Topic: [feature name]

## Concepts Covered
1. [Concept]
2. [Concept]
3. [Concept]

## Implementation
[Code with inline teaching]

## Key Takeaways
- [Takeaway 1]
- [Takeaway 2]

## Practice
- [Exercise 1]
- [Exercise 2]

Example Session

──── /learn ────
Topic: Creating a User Service

## What We're Building

A UserService that fetches user data from an API and handles
loading states, errors, and caching.

**Concepts you'll learn:**
- Service layer pattern
- TypeScript generics
- Error handling strategies

## Let's Start

### Step 1: The Types

Before any logic, we define our types. This is called
"types-first development" - we describe the shape of our
data before we write code that uses it.

```typescript
// Why interface over type?
// Interfaces are better for object shapes because they:
// 1. Have better error messages
// 2. Can be extended
// 3. Are more familiar to OOP developers

interface User {
  id: string;
  name: string;
  email: string;
}

[... continues with teaching ...]

## Rules

1. **Never skip the "why"** - Every piece needs justification
2. **Build incrementally** - Complex → Simple steps
3. **Use visuals** - Diagrams help understanding
4. **Ask questions** - Engage the learner
5. **Connect concepts** - Show the bigger picture