code-explainer

What this skill does

# Code Explainer Skill

Explain complex code to team members in clear, understandable terms for effective knowledge sharing and onboarding.

## Instructions

You are a technical communication expert. When invoked:

1. **Analyze Code**:
   - Understand the code's purpose and functionality
   - Identify key algorithms and patterns
   - Recognize language-specific idioms
   - Map dependencies and relationships
   - Detect potential confusion points

2. **Create Explanations**:
   - Start with high-level overview
   - Break down into logical sections
   - Explain step-by-step execution flow
   - Use analogies and real-world examples
   - Include visual diagrams when helpful

3. **Adapt to Audience**:
   - **Junior Developers**: Detailed explanations, avoid jargon
   - **Mid-Level Developers**: Focus on patterns and design
   - **Senior Developers**: Architectural decisions and trade-offs
   - **Non-Technical Stakeholders**: Business impact and functionality

4. **Add Context**:
   - Why code was written this way
   - Common pitfalls and gotchas
   - Performance considerations
   - Security implications
   - Best practices demonstrated

5. **Enable Learning**:
   - Suggest related concepts to study
   - Link to documentation
   - Provide practice exercises
   - Point out improvement opportunities

## Explanation Formats

### High-Level Overview Template

```markdown
# What This Code Does

## Purpose
This module handles user authentication using JWT (JSON Web Tokens). When a user logs in, it verifies their credentials and returns a token they can use for subsequent requests.

## Key Responsibilities
1. Validates user credentials (email/password)
2. Generates secure JWT tokens
3. Manages token expiration and refresh
4. Protects routes requiring authentication

## How It Fits Into The System
```
┌─────────┐     Login Request      ┌──────────────┐
│ Client  │ ──────────────────────> │ Auth Service │
│         │                         │  (This Code) │
│         │ <────────────────────── │              │
└─────────┘     JWT Token          └──────────────┘
                                           │
                                           │ Verify Credentials
                                           ▼
                                    ┌──────────┐
                                    │ Database │
                                    └──────────┘
```

## Files Involved
- `AuthService.js` - Main authentication logic
- `TokenManager.js` - JWT generation and validation
- `UserRepository.js` - Database queries
- `authMiddleware.js` - Route protection
```

### Step-by-Step Walkthrough Template

```markdown
# Code Walkthrough: User Login Flow

## The Code
```javascript
async function login(email, password) {
  const user = await User.findOne({ email });
  if (!user) {
    throw new Error('User not found');
  }

  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) {
    throw new Error('Invalid password');
  }

  const token = jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );

  return { token, user: { id: user.id, email: user.email } };
}
```

## Step-by-Step Breakdown

### Step 1: Find User
```javascript
const user = await User.findOne({ email });
```

**What it does**: Searches the database for a user with the provided email address.

**Technical details**:
- `await` pauses execution until the database responds
- `findOne()` returns the first matching user or `null` if none found
- Database query: `SELECT * FROM users WHERE email = ?`

**Why this way**: We use email as the lookup key because it's unique and what users remember.

---

### Step 2: Check if User Exists
```javascript
if (!user) {
  throw new Error('User not found');
}
```

**What it does**: If no user was found, stop here and report an error.

**Security note**: In production, you might want to use the same error message for both "user not found" and "wrong password" to prevent email enumeration attacks.

**What happens**: The error is caught by the caller, typically returning HTTP 401 Unauthorized.

---

### Step 3: Verify Password
```javascript
const isValid = await bcrypt.compare(password, user.passwordHash);
```

**What it does**: Compares the plain-text password with the hashed password stored in the database.

**How bcrypt works**:
1. Takes the user's input password
2. Applies the same hashing algorithm used during registration
3. Compares the result with the stored hash
4. Returns `true` if they match, `false` otherwise

**Why bcrypt**:
- Passwords are never stored in plain text
- bcrypt is designed to be slow (prevents brute-force attacks)
- Includes salt automatically (prevents rainbow table attacks)

**Real-world analogy**: It's like having a one-way mirror. You can create a reflection (hash), but you can't reverse it to see the original. To verify, you create a new reflection and check if they match.

---

### Step 4: Check Password Validity
```javascript
if (!isValid) {
  throw new Error('Invalid password');
}
```

**What it does**: If the password doesn't match, reject the login attempt.

**Security consideration**: We wait until AFTER the bcrypt comparison before rejecting. This prevents timing attacks that could distinguish between "user not found" and "wrong password".

---

### Step 5: Generate JWT Token
```javascript
const token = jwt.sign(
  { userId: user.id, role: user.role },
  process.env.JWT_SECRET,
  { expiresIn: '1h' }
);
```

**What it does**: Creates a signed token the user can use to prove their identity.

**Breaking it down**:
- **Payload** `{ userId: user.id, role: user.role }`: Information encoded in the token
- **Secret** `process.env.JWT_SECRET`: Private key used to sign the token
- **Options** `{ expiresIn: '1h' }`: Token is valid for 1 hour

**JWT Structure**:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoidXNlciJ9.signature
│              Header               │           Payload              │ Signature │
```

**Real-world analogy**: Like a concert wristband - shows who you are, when it was issued, and when it expires. The signature proves it wasn't forged.

---

### Step 6: Return Success
```javascript
return {
  token,
  user: { id: user.id, email: user.email }
};
```

**What it does**: Sends back the token and basic user info.

**Why not return everything**:
- Security: Never send password hashes to the client
- Performance: Only send data the client needs
- Privacy: Don't expose sensitive user information

**Client will**:
1. Store the token (usually in localStorage or httpOnly cookie)
2. Include it in future requests: `Authorization: Bearer <token>`
3. Display user info in the UI
```

### Visual Explanation Template

```markdown
# Understanding the Middleware Pipeline

## Code Overview
```javascript
app.use(logger);
app.use(authenticate);
app.use(authorize('admin'));
app.use('/api/users', userRouter);
```

## Request Flow Diagram

```
HTTP Request: GET /api/users/123
        │
        ▼
┌───────────────────┐
│  1. Logger        │ ──> Logs request details
│  middleware       │     (timestamp, method, URL)
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│  2. Authenticate  │ ──> Verifies JWT token
│  middleware       │     Sets req.user if valid
└─────────┬─────────┘
          │
          ├─── ❌ No token? → 401 Unauthorized
          │
          ▼
┌───────────────────┐
│  3. Authorize     │ ──> Checks user.role === 'admin'
│  middleware       │
└─────────┬─────────┘
          │
          ├─── ❌ Not admin? → 403 Forbidden
          │
          ▼
┌───────────────────┐
│  4. User Router   │ ──> Handles GET /123
│  Route Handler    │     Returns user data
└─────────┬─────────┘
          │
          ▼
   HTTP Response: 200 OK
   { "id": 123, "name": "John" }
```

## Real-World Analogy

Think of middleware as airport security checkpoints:

1. **Logger**: Check-in desk - records who's passing through
2. **Authenticate**: ID ver