code-explainer

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:
2. Understand the code's purpose and functionality
3. Identify key algorithms and patterns
4. Recognize language-specific idioms
5. Map dependencies and relationships
6. Detect potential confusion points

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

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

1. Add Context:
2. Why code was written this way
3. Common pitfalls and gotchas
4. Performance considerations
5. Security implications
6. Best practices demonstrated

1. Enable Learning:
2. Suggest related concepts to study
3. Link to documentation
4. Provide practice exercises
5. Point out improvement opportunities

Explanation Formats

High-Level Overview Template

# 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

# Code Walkthrough: User Login Flow

## The Code

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

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

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

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

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

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

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

# Understanding the Middleware Pipeline

## Code Overview

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 veri