backend-dev · git:20260320.869847a · 2026-03-20 · sha256 e84a0186c3be4e7a

backend-dev git:20260320.869847aA

Immutable. This exact content never changes and is served at /api/v1/blob/e84a0186c3be4e7a.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_674gvyctzbsxfbyt/e84a0186c3be4e7a83901631948695fe0300e150e0822059fd2868ee8e218275.json

Then /plugin install backend-dev@markdownregistry-674gvyctzbsxfbyt in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: backend-dev
description: Use this skill for backend development — server logic, authentication, microservices, serverless functions, middleware, background jobs, caching strategies, and backend architecture patterns. Trigger on keywords: backend, server, API endpoint, middleware, authentication, authorization, microservice, serverless, background job, queue, caching, session.
---

# Backend Development

## Core Principles

- **Stateless services** — don't store session state in memory; use Redis or a DB
- **Fail fast** — validate inputs at the boundary, return errors early
- **Idempotency** — POST/PUT endpoints that can be called multiple times safely
- **Observability** — every service needs logs, metrics, and traces

---

## API Endpoint Structure

### Request Lifecycle
```text
Request → Rate Limiting → Authentication → Authorization → Validation → Business Logic → Response
```

Never skip this order. Auth before business logic. Validation before processing.

### Response Standards
```json
// Success
{ "data": { ... }, "meta": { "page": 1, "total": 100 } }

// Error
{ 
  "error": { 
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{ "field": "email", "issue": "Invalid format" }]
  }
}
```

---

## Authentication Patterns

### JWT Best Practices
- Short access token TTL (15 min) + long refresh token (7 days)
- Store refresh token in httpOnly cookie (not localStorage)
- Validate signature, expiry, issuer, and audience
- Rotate refresh tokens on use
- Maintain a revocation list or use short-lived tokens only

### Session-Based Auth
- Store session ID in httpOnly, Secure, SameSite cookie
- Store session data in Redis with TTL
- Regenerate session ID after login (session fixation prevention)

### Authorization
```typescript
// Check authorization at the service layer, not just the route
async function getOrder(userId: string, orderId: string) {
  const order = await db.orders.findById(orderId)
  if (!order) throw new NotFoundError()
  // Authorization check — user can only see their own orders
  if (order.userId !== userId) throw new ForbiddenError()
  return order
}
```

---

## Background Jobs & Queues

Use queues for:
- Email sending
- Image/file processing
- External API calls that don't need to be synchronous
- Long-running tasks

### Job Patterns
```text
Fire-and-forget: Enqueue and return immediately
Scheduled: Run at specific time (cron)
Delayed: Run after X minutes/hours
Retry: Re-attempt on failure with backoff
```

Always implement:
- Dead letter queue for failed jobs
- Idempotency key to prevent duplicate processing
- Timeout per job
- Max retry count

---

## Error Handling

```typescript
// Structured error hierarchy
class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number,
    public code: string
  ) { super(message) }
}

class ValidationError extends AppError {
  constructor(details: ValidationDetail[]) {
    super('Validation failed', 400, 'VALIDATION_ERROR')
    this.details = details
  }
}

// Global error handler
app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({ error: err })
  }
  // Log unexpected errors
  logger.error('Unexpected error', { err, req })
  res.status(500).json({ error: { code: 'INTERNAL_ERROR' } })
})
```

---

## Middleware Checklist

Every production API needs:
- [ ] Request logging (method, path, status, duration)
- [ ] Rate limiting (per IP, per user, per endpoint)
- [ ] CORS configuration (explicit whitelist)
- [ ] Helmet / security headers
- [ ] Request ID propagation (for distributed tracing)
- [ ] Body size limits
- [ ] Timeout handling

---

## Environment Configuration

```typescript
// Never hardcode configuration — always from environment
const config = {
  db: {
    url: process.env.DATABASE_URL,      // required
    poolSize: parseInt(process.env.DB_POOL_SIZE ?? '10')
  },
  jwt: {
    secret: process.env.JWT_SECRET,     // required
    expiresIn: process.env.JWT_TTL ?? '15m'
  }
}

// Validate required config at startup — fail fast
const required = ['DATABASE_URL', 'JWT_SECRET']
for (const key of required) {
  if (!process.env[key]) throw new Error(`Missing required env: ${key}`)
}
```