Skip to content
Skills Library
Programming · Learning & explanation

backend-patterns

/backend-patterns

Backend development patterns and best practices. Use for API design, database optimization, microservice architecture, authentication, caching strategies, and server-side implementation.

Licence
MIT
Last repository change
16.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Backend development patterns and best practices. Use for API design, database optimization, microservice architecture, authentication, caching strategies, and server-side implementation.

Original author description

Backend development patterns and best practices. Use for API design, database optimization, microservice architecture, authentication, caching strategies, and server-side implementation.

How it works

  1. 1. API Design
  2. 2. Database Patterns
  3. 3. Authentication & Authorization
  4. 4. Caching Strategies
  5. 5. Error Handling Patterns
  6. 6. Logging & Observability
  7. 7. Testing Patterns
  8. 8. Security Checklist (OWASP Top 10)
Original SKILL.md headings · 559 lines, 2,277 words
SKILL.md preview
---
name: backend-patterns
description: >
  Backend development patterns and best practices. Use for API design, database
  optimization, microservice architecture, authentication, caching strategies,
  and server-side implementation.
---

# Backend Patterns

You are the backend engineering expert. You apply proven server-side patterns for APIs, databases, security, and observability. Every recommendation must be concrete, with code examples and anti-patterns to avoid.

---

## 1. API Design

### REST Conventions

#### URL Structure

```
GET    /api/v1/users              → List users (paginated)
GET    /api/v1/users/:id          → Get single user
POST   /api/v1/users              → Create user
PATCH  /api/v1/users/:id          → Partial update
PUT    /api/v1/users/:id          → Full replace
DELETE /api/v1/users/:id          → Soft delete
```

#### Naming Rules

- **Plural nouns** for collections: `/users`, not `/user`.
- **Kebab-case** for multi-word: `/user-profiles`, not `/userProfiles`.
- **Nest for ownership**: `/users/:id/posts` (user's posts).
- **Max 2 levels deep**: `/users/:id/posts/:postId` — no deeper.
- **Query params for filtering**: `GET /users?role=admin&status=active`.

#### Response Envelope

```json
{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=2",
    "prev": null
  }
}
```

#### HTTP Status Codes

| Code | Usage |
|------|-------|
| `200` | Success with body |
| `201` | Created — return created resource + `Location` header |
| `204` | Success, no body (DELETE, some PATCH) |
| `400` | Validation error — include field-level errors |
| `401` | Unauthenticated — token missing or expired |
| `403` | Unauthorized — valid token but insufficient permissions |
| `404` | Resource not found |
| `409` | Conflict — duplicate key, version mismatch |
| `422` | Unprocessable entity — business rule violation |
| `429` | Rate limited — include `Retry-After` header |
| `500` | Server error — log details, return generic message |

#### Pagination

Use cursor-based pagination for large datasets:

```json
{
  "data": [...],
  "meta": {
    "has_next": true,
    "cursor": "eyJpZCI6MTAwfQ=="
  }
}
```

Use offset-based only for small, stable datasets where random page access is needed.

### GraphQL Schema Design

#### Schema-First Approach

```graphql
type User {
  id: ID!
  email: String!
  displayName: String!
  avatar: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  node: Post!
  cursor: String!
}

input CreateUserInput {
  email: String!
  displayName: String!
  password: String!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User
  errors: [UserError!]!
}
```

#### GraphQL Rules

- Use **Relay-style connections** for lists (edges + pageInfo).
- **Input types** for mutations — never inline arguments.
- **Payload types** for mutations — always include an `errors` field.
- **DataLoader** for N+1 prevention — batch all database calls.
- Limit query **depth to 5** and **complexity scoring** to prevent abuse.
- Never expose internal IDs directly — use opaque, base64-encoded cursors.

### gRPC Proto Design

```protobuf
syntax = "proto3";
package user.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  User user = 1;
}

message User {
  string id = 1;
  string email = 2;
  string display_name = 3;
  google.protobuf.Timestamp created_at = 4;
}
```

#### gRPC Rules

- **Package versioning**: `package user.v1;` — version in package name.
- **Field numbers are forever** — never reuse deleted field numbers.
- Use `google.protobuf.Timestamp` for dates, not strings.
- Wrap responses in response messages — allows adding metadata later.
- Use **server streaming** for real-time feeds, **bidirectional** for chat.

---

## 2. Database Patterns

### Query Optimization

#### The Query Checklist

1. **EXPLAIN ANALYZE** every query touching >1000 rows.
2. **Select only needed columns** — never `SELECT *` in production.
3. **Avoid N+1** — use JOINs or batch queries.
4. **Parameterize everything** — never concatenate user input.
5. **Limit result sets** — always paginate.

#### Common Optimizations

```sql
-- BAD: Full table scan
SELECT * FROM orders WHERE YEAR(created_at) = 2024;

-- GOOD: Sargable query, uses index
SELECT id, total, status
FROM orders
WHERE created_at >= '2024-01-01'
  AND created_at < '2025-01-01';
```

### Indexing Strategy

| Pattern | Index Type |
|---------|-----------|
| Exact match (`WHERE status = 'active'`) | B-tree |
| Range query (`WHERE created_at > X`) | B-tree |
| Text search (`WHERE name ILIKE '%query%'`) | GIN / trigram |
| JSON field access | GIN |
| Geospatial | GiST / SP-GiST |
| Composite filters | Composite index (most selective first) |

#### Index Rules

- **Covering indexes** for read-heavy queries — include all selected columns.
- **Partial indexes** for filtered subsets: `CREATE INDEX idx_active ON users(email) WHERE status = 'active';`
- **Never index** columns with low cardinality unless combined with high-cardinality columns.
- **Monitor unused indexes** — they slow writes with zero benefit.
- **Composite index order matters**: `(a, b, c)` supports queries on `(a)`, `(a, b)`, `(a, b, c)` but NOT `(b, c)`.

### Migration Patterns

#### Safe Migration Rules

1. **Always reversible** — every `up` has a `down`.
2. **No breaking changes** — expand first, migrate data, then contract.
3. **Column additions**: Add with `DEFAULT NULL`, backfill in batches, then add constraints.
4. **Column removals**: Stop reading → deploy → stop writing → deploy → drop column.
5. **Rename = add new + copy + drop old** — never use `RENAME COLUMN` in production.
6. **Large table migrations**: Use `pt-online-schema-change` or `gh-ost` for MySQL, `pg_repack` for PostgreSQL.
7. **Lock timeouts**: Set `SET lock_timeout = '5s';` to avoid long table locks.

---

## 3. Authentication & Authorization

### JWT Pattern

```
Access Token:
- Short-lived (15 min)
- Stored in memory (never localStorage)
- Contains: sub, roles, permissions, exp, iat, jti

Refresh Token:
- Long-lived (7-30 days)
- Stored in httpOnly secure cookie
- Rotated on each use (one-time use)
- Stored server-side for revocation
```

#### JWT Checklist

- [ ] Use RS256 or ES256 (asymmetric) — never HS256 in distributed systems.
- [ ] Validate `iss`, `aud`, `exp`, `nbf` on every request.
- [ ] Include `jti` for token revocation.
- [ ] Short expiry (15 min max for access tokens).
- [ ] Refresh token rotation with reuse detection.
- [ ] Logout = revoke refresh token server-side.

### OAuth2 Flows

| Flow | Use Case |
|------|----------|
| Authorization Code + PKCE | SPAs, mobile apps, web apps |
| Client Credentials | Service-to-service |
| Device Code | Smart TVs, CLI tools |

**Never use** Implicit flow or Resource Owner Password — both are deprecated.

### RBAC (Role-Based Access Control)

```
Roles: admin, editor, viewer
Permissions: users:read, users:write, posts:read, posts:write, posts:delete

admin  → users:read, users:write, posts:read, posts:write, posts:delete
editor → posts:read, posts:write
viewer → posts:read
```

### ABAC (Attribute-Based Access Control)

Use when RBAC is too coarse. Evaluate policies based on:

- **Subject**: user role, department, clearance level
- **Resource**: owner, classification, status
- **Action**: read, write, delete
- **Context**: time, IP, device

```
ALLOW IF:
  subject.role == "editor"
  AND resource.owner_id == subject.id
  AND action IN ["read", "write"]
  AND context.time BETWEEN 09:00 AND 18:00
```

---

## 4. Caching Strategies

### Redis Patterns

#### Cache-Aside (Lazy Loading)

```
Read:
1. Check cache → hit? return cached.
2. Miss? Query DB → store in cache with TTL → return.

Write:
1. Write to DB.
2. Invalidate cache key.
```

#### Write-Through

```
Write:
1. Write to cache.
2. Cache writes to DB synchronously.

Read:
1. Always read from cache.
```

#### Cache Stampede Prevention

```
# Use probabilistic early expiration
actual_ttl = base_ttl - (random(0, ttl * 0.1))

# Or use locking
if cache.miss(key):
    if cache.setnx(lock_key, 1, ttl=5):
        result = db.query(...)
        cache.set(key, result, ttl=300)
        cache.del(lock_key)
    else:
        sleep(0.1)
        retry()
```

### Cache Key Design

```
# Pattern: {service}:{entity}:{id}:{variant}
user:profile:12345
user:profile:12345:minimal
feed:timeline:12345:page:1
config:feature-flags:v3
```

### Cache Invalidation Rules

- **TTL everything** — no key should live forever.
- **Invalidate on write** — delete or update the cached key.
- **Use versioned keys** for bulk invalidation: `v3:user:12345` → bump to `v4` to invalidate all.
- **Event-driven invalidation** for cross-service: publish `user.updated` → subscribers invalidate their caches.
- **Never cache errors** — or cache with very short TTL (5s) to prevent thundering herd.

### CDN Caching

```
# Static assets: aggressive caching
Cache-Control: public, max-age=31536000, immutable

# API responses: short cache with revalidation
Cache-Control: public, max-age=60, stale-while-revalidate=300

# Private data: no CDN caching
Cache-Control: private, no-store
```

---

## 5. Error Handling Patterns

### Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Must be a valid email address"
      }
    ],
    "request_id": "req_abc123",
    "docs_url": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}
```

### Error Code Taxonomy

```
AUTH_*          → Authentication/authorization errors
VALIDATION_*   → Input validation errors
NOT_FOUND_*    → Resource not found
CONFLICT_*     → State conflicts (duplicate, version mismatch)
RATE_LIMIT_*   → Rate limiting
INTERNAL_*     → Server errors (log full details, return generic)
DEPENDENCY_*   → External service failures
```

### Graceful Degradation

1. **Circuit Breaker**: After N failures to a dependency, stop calling it for X seconds.
2. **Fallback**: Return cached/stale data when the primary source is down.
3. **Bulkhead**: Isolate failure domains — one slow dependency shouldn't consume all threads.
4. **Timeout**: Every external call has a timeout. Default: 5s for HTTP, 2s for cache, 30s for DB.
5. **Retry with backoff**: `delay = base * 2^attempt + jitter` — max 3 retries.

---

## 6. Logging & Observability

### Structured Logging

```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "info",
  "message": "User profile updated",
  "service": "user-service",
  "trace_id": "abc123",
  "span_id": "def456",
  "user_id": "usr_789",
  "duration_ms": 45,
  "fields": {
    "changed_fields": ["display_name", "avatar"],
    "ip": "192.168.1.1"
  }
}
```

### Logging Rules

- **Structured JSON** — never unstructured text in production.
- **Correlation IDs** — propagate `trace_id` across all services.
- **Log levels**: `debug` (dev only), `info` (business events), `warn` (recoverable issues), `error` (failures needing attention), `fatal` (process must exit).
- **Never log**: passwords, tokens, PII, credit card numbers, full request bodies with sensitive fields.
- **Always log**: request_id, user_id (hashed if needed), duration, status code, error codes.

### The Three Pillars

| Pillar | Tool Examples | Purpose |
|--------|--------------|---------|
| **Logs** | ELK, Loki, CloudWatch | What happened (events) |
| **Metrics** | Prometheus, Datadog, CloudWatch | How much / how often (aggregates) |
| **Traces** | Jaeger, Tempo, X-Ray | How requests flow (causality) |

### Key Metrics to Track

```
# RED Method (for services)
- Rate:    requests per second
- Errors:  error rate (%)
- Duration: latency percentiles (p50, p95, p99)

# USE Method (for resources)
- Utilization: CPU, memory, disk, connections
- Saturation: queue depth, thread pool usage
- Errors: resource errors (OOM, connection refused)
```

### Alerting Rules

- Alert on **symptoms** (error rate > 1%, p99 > 2s), not causes.
- Every alert must have a **runbook link**.
- **Page** for user-facing impact, **ticket** for everything else.
- Set **burn rate** alerts for SLO-based monitoring.

---

## 7. Testing Patterns

### Test Pyramid

```
        /  E2E  \        → Few, slow, expensive (critical paths only)
       / Contract \      → API contract validation between services
      / Integration \    → DB, cache, external service integration
     /    Unit Tests  \  → Many, fast, isolated (business logic)
```

### Unit Testing Rules

- Test **behavior**, not implementation.
- One assertion per test (logical, not literal).
- Use **factories** for test data, not fixtures.
- Mock at **boundaries** (DB, HTTP, file system), not internal classes.
- **Arrange-Act-Assert** structure for every test.

### Integration Testing

```
# Test real database interactions
- Use testcontainers or in-memory DB.
- Each test gets a clean database (transaction rollback or truncate).
- Test complex queries, joins, and constraints.
- Test migration up AND down.

# Test external service integration
- Use WireMock / MSW for HTTP service mocks.
- Test happy path, error responses, timeouts.
- Record/replay for deterministic tests.
```

### Contract Testing (Pact / Schema Validation)

```
# Consumer-driven contracts
1. Consumer (frontend) defines expected API shape.
2. Contract is shared with provider (backend).
3. Provider verifies its API satisfies the contract.
4. Both sides run contract tests in CI.

# Schema validation
- Validate request/response against OpenAPI spec.
- Fail CI if API response doesn't match schema.
```

---

## 8. Security Checklist (OWASP Top 10)

### Prevention Matrix

| Threat | Prevention |
|--------|-----------|
| **A01 Broken Access Control** | Deny by default. Validate permissions on every endpoint. Test IDOR (insecure direct object reference). |
| **A02 Cryptographic Failures** | TLS everywhere. AES-256 for data at rest. bcrypt/argon2 for passwords. Never roll your own crypto. |
| **A03 Injection** | Parameterized queries only. Input validation (allowlist, not blocklist). ORM with prepared statements. |
| **A04 Insecure Design** | Threat modeling. Abuse case testing. Rate limiting on sensitive endpoints. |
| **A05 Security Misconfiguration** | Disable debug in production. Remove default credentials. Security headers (HSTS, CSP, X-Frame-Options). |
| **A06 Vulnerable Components** | Automated dependency scanning (Snyk, Dependabot). Pin versions. Update regularly. |
| **A07 Auth Failures** | MFA for sensitive ops. Account lockout after N failures. Credential stuffing protection. |
| **A08 Data Integrity Failures** | Verify CI/CD pipeline integrity. Sign artifacts. Validate deserialization input. |
| **A09 Logging & Monitoring** | Log auth events, access control failures. Alert on anomalies. Retain logs 90+ days. |
| **A10 SSRF** | Allowlist outbound URLs. Block internal IP ranges. Validate and sanitize URLs. |

### Security Headers

```
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; script-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()
```

### Input Validation Rules

- **Validate on the server** — client validation is UX, not security.
- **Allowlist over blocklist** — define what IS valid, not what isn't.
- **Type coercion** — parse integers as integers, not strings.
- **Length limits** — every string field has a max length.
- **File uploads** — validate MIME type by content (magic bytes), not extension. Limit size. Scan for malware.

Versions

RepositoryScoreLicence
This page · andersonlimahw/lemon-ai-hub95MIT
Sanit-mann/The-Insectoids100MIT
tadokoro-ryusuke/cc-plugins100MIT
kensaurus/cursor-kenji100MIT
Selenophile2004/applied-agent-skills100MIT
tranhieutt/software_development_department100MIT
affaan-m/ECC95MIT
affaan-m/ECC95MIT
SHRIJANAGAIN/Nemo-Cli95Apache-2.0

Database snapshot: 13.11.2026 · package version 1891108d4fad (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100backend
    Use when making backend architecture decisions — choosing API styles, database types, caching strategies, authentication mechanisms, and server-side design patterns for scalable, maintainable systems. USE FOR: backend architecture decisions, choosing API styles, choosing…
  • 100senior-backend
    Designs and implements backend systems including REST APIs, microservices, database architectures, authentication flows, and security hardening. Use when the user asks to "design REST APIs", "optimize database queries", "implement authentication", "build microservices", "review…
  • 90moai-domain-backend
    Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns. Use when designing APIs, implementing server logic, authentication, or authorization.
  • 100backend-development
    Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
  • 95wicked-garden-engineering-backend
    Backend engineering specialist for APIs, databases, server-side patterns, data modeling, scalability, and integrations. Use when: "design an API", "database schema", "how to handle auth", "backend performance", "REST endpoint", "query optimization", "server-side architecture
  • 100node-patterns
    Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes. Use when building or reviewing Node.js, Express, or Next.js API routes and their data access.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.