cargdev/codetyper.cli/explain

## Overview
[1-2 sentence summary of what this code does]
 
## Key Concepts
[List the main concepts someone needs to understand]
 
## How It Works
[Step-by-step explanation of the code flow]
 
## Code Walkthrough
[Annotated code snippets with explanations]
 
## Connections
[How this relates to other parts of the codebase]
 
## Summary
[Recap of the key points]

## Overview
 
The `debounce` function delays executing a function until a certain amount of time has passed since it was last called. Think of it like an elevator: it waits for people to stop entering before closing the doors.
 
## Key Concepts
 
- **Debouncing**: Grouping multiple rapid calls into one
- **Closures**: The returned function "remembers" the timer
- **setTimeout/clearTimeout**: JavaScript's timing mechanisms
 
## How It Works
 
1. User calls the debounced function
2. Previous timer (if any) is cancelled
3. New timer is set for the delay period
4. If no new calls come in, the original function executes
5. If a new call comes in, repeat from step 2
 
## Code Walkthrough
 
\`\`\`typescript
// src/utils/debounce.ts:5-20
 
export function debounce<T extends (...args: any[]) => any>(
  fn: T,           // The function to debounce
  delay: number    // How long to wait (ms)
): (...args: Parameters<T>) => void {
  let timeoutId: ReturnType<typeof setTimeout> | null = null;
 
  // Return a new function that wraps the original
  return (...args: Parameters<T>) => {
    // Cancel any pending execution
    if (timeoutId) {
      clearTimeout(timeoutId);
    }
 
    // Schedule new execution
    timeoutId = setTimeout(() => {
      fn(...args);      // Call original with latest args
      timeoutId = null; // Clean up
    }, delay);
  };
}
\`\`\`
 
## Connections
 
This utility is used by:
- `src/components/SearchInput.tsx:23` - Debounce search API calls
- `src/hooks/useWindowResize.ts:8` - Debounce resize handlers
 
## Summary
 
`debounce` prevents a function from being called too frequently by waiting until calls stop coming in. It's essential for performance when handling rapid events like typing or resizing.

## Overview
 
Authentication uses JWT (JSON Web Tokens) with a refresh token flow. Users log in once and receive two tokens: a short-lived access token for API calls and a long-lived refresh token for getting new access tokens.
 
## Key Concepts
 
- **JWT**: Self-contained tokens with encoded user data
- **Access Token**: Short-lived (15 min), used for API authorization
- **Refresh Token**: Long-lived (7 days), used to get new access tokens
- **HTTP-only Cookies**: Secure storage immune to XSS
 
## How It Works
 
1. **Login** (`src/auth/login.ts:15`)
   - User submits credentials
   - Server validates against database
   - Server generates access + refresh tokens
   - Tokens stored in HTTP-only cookies
 
2. **API Request** (`src/middleware/auth.ts:8`)
   - Client sends request with cookies
   - Middleware extracts access token
   - JWT is verified and decoded
   - User data attached to request
 
3. **Token Refresh** (`src/auth/refresh.ts:22`)
   - Access token expires (15 min)
   - Client automatically calls /refresh
   - Server validates refresh token
   - New access token issued
 
4. **Logout** (`src/auth/logout.ts:10`)
   - Refresh token invalidated in database
   - Cookies cleared
 
## Code Walkthrough
 
\`\`\`typescript
// src/middleware/auth.ts:8-25
 
export const requireAuth = async (req, res, next) => {
  const token = req.cookies.accessToken;
 
  if (!token) {
    return res.status(401).json({ error: 'Not authenticated' });
  }
 
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;  // Attach user to request
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
};
\`\`\`
 
## Connections
 
- **User Model**: `src/models/User.ts` - Password hashing, user data
- **Protected Routes**: `src/routes/api/*.ts` - Use `requireAuth` middleware
- **Frontend**: `src/hooks/useAuth.ts` - Client-side auth state
 
## Summary
 
Authentication is handled through JWTs stored in HTTP-only cookies. The access token is short-lived for security, while the refresh token enables seamless re-authentication. The middleware pattern keeps protected routes clean and centralized.