dev-backend

Dev-Backend — Production-Grade Backend Engineering

Build reliable, secure, and maintainable server-side applications.

This skill has modular references for specialized guidance — read the relevant ones before coding.

It activates by change surface whenever work primarily touches APIs, servers, services, jobs, data access, schemas, migrations, or operational backend behavior.

> C0/C1 work (small local patches): See dev §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references.

Modular References

Read api-design.md + anti-slop-backend.md first, then the relevant stack file.

For C2 ordinary slices, crud-api.md alone suffices; read api-design.md/architecture.md for new API styles or C3+ work.

When backend decisions depend on current external API docs, API lifecycle

changes, LLM/RAG provider behavior, dependency freshness, or package/source

evidence, read the active search skill and follow its query-rewrite,

source-fetch, and evidence-status rules.

---

0. Stack Detection & Architecture Clarification

Auto-detect (existing projects)

If config files exist → detect silently and proceed.

Architecture Clarification (new or ambiguous projects)

When the request has unspecified technology or unclear scope, clarify before coding:

1. Identify what's ambiguous from this list:

1. Recommend one with reasoning: cite project context. e.g., "Small team → monolith + PostgreSQL + JWT is the simplest starting point."
2. Over-engineering guard: A CRUD API *probably* doesn't need GraphQL + microservices + event sourcing. Simple → complex, not the reverse.
3. One round limit: 2-3 options → recommend → confirm → proceed.

If the user already specifies clear tech (e.g. "FastAPI로 REST API 만들어줘"), skip this entirely.

Node/framework defaults (verified 2026-07-02): production uses Active/Maintenance

LTS — Node 24 (Active LTS) for new services, Node 22 (Maintenance). Framework: Fastify

for greenfield Node APIs (schema/Pino/plugin structure); Express 5 for legacy/ecosystem

compatibility; Hono for edge/serverless/multi-runtime Web-Standards APIs. New TS

validation baseline is Zod v4 (read the migration guide before upgrading v3 projects).

Sources: references/stacks/node.md § Sources.

For new Node backend source files, prefer .ts when the repo supports TypeScript or is greenfield. Inherit dev TypeScript strict-compatibility rules.

If backend boundaries are unclear, read existing source-of-truth docs/logs first, then document routes, services, repositories, data stores, and runtime commands in the repo's existing SOT before broad implementation.

---

1. Architecture Decision

Before coding, identify the right pattern:

Default to monolith. Extract only when you have a proven need (different scaling, independent deployment, technology mismatch).

See references/core/architecture.md for full decision matrices.

API Protocol Decision

Hybrid pattern (verified 2026-07-02):

Public/Partner → REST (OpenAPI 3.1+; prefer 3.2 where tooling supports it)
Mobile/Web BFF → GraphQL (client aggregation; Apollo Federation ONLY when multiple
                 independently-owned subgraphs must compose into a supergraph)
Internal services → gRPC (Protobuf contracts)
TS internal tools → tRPC v11 (zero-codegen type safety)

Deprecations: emit Deprecation (RFC 9745) and optional Sunset (RFC 8594) headers,

but client adoption is uneven — always pair with OpenAPI/changelog dates and deprecated-

endpoint traffic dashboards.

See references/core/api-design.md for protocol-specific patterns.

Long-Lived Connection Operation

Rules for SSE, WebSocket, and any connection held open beyond a single request-response cycle.

Lifecycle Rules:

Server-Side Requirements:

• Connection registry: Track all active connections in-memory (Map by client/session ID). Required for graceful drain and debugging.
• Graceful drain on deploy: Stop accepting new connections → send "reconnect" frame to existing → wait drain timeout → close.
• Memory budget: Allocate max memory per connection (e.g., 2KB buffer). Monitor total; reject new connections when approaching limit.
• Backpressure: If client stops consuming, buffer up to N messages then drop oldest or disconnect.

Pattern — "202 + Job ID" for Long Operations:

Instead of holding a connection open for a slow operation:

POST /generate → 202 { jobId: "j_abc123" }
GET /jobs/j_abc123 → { status: "processing", progress: 0.6 }
                   → { status: "complete", result: {...} }

Use SSE/WebSocket only for push notifications about job status — not for the operation itself.

Banned:

---

2. Layered Architecture (Default; Allow Serverless Handlers, Vertical Slices, and Small Scripts When Appropriate)

Routes → Controllers → Services → Repositories → Database
  │          │             │            │
  │          │             │            └── Data access only
  │          │             └── Business logic (validation at controller boundary — service trusts caller per dev-architecture §4)
  │          └── Parse HTTP, format response
  └── URL mapping, middleware

Rules:

• Routes: URL patterns + middleware only. No logic.
• Controllers: parse input, call services, format output. No business rules.
• Services: receive/return plain data (not req/res). All logic here.
• Repositories: abstract DB access. Services access data through repositories only.

Repository Pattern (Interface Abstraction)

Use repository interfaces so services depend on abstractions, enabling mocking and swapping implementations.

Async Task Queue Patterns

When work exceeds what an HTTP response cycle should hold open, use a queue.

Decision: Queue vs Direct:

Pattern — Accept, Queue, Notify:

1. Client  → POST /tasks       → Server validates, enqueues
2. Server  → 202 { jobId }     → Client receives immediately
3. Worker  → picks from queue  → executes task
4. Client  → GET /tasks/{id}   → polls status (or receives webhook/SSE push)
5. Worker  → completes         → writes result, triggers notification

Queue Selection Guide:

Required Safeguards:

Banned:

---

3. Error Handling

Use a centralized AppError class (DEFAULT — when the repo already has an error convention, follow it instead). Distinguish operational vs programmer errors.

Error Taxonomy (AppError Hierarchy)

Create an AppError base class with statusCode, code, and isOperational properties. Extend for each error type (ValidationError, NotFoundError, etc.).

Result Pattern (conditional)

Consider the Result/Either pattern (e.g. neverthrow) for recoverable domain errors where explicit error handling improves clarity — adopt it only when the project scope justifies it and the repo doesn't already settle error style (HEURISTIC, not a universal requirement).

Rule: Use Result where recoverable/domain errors are first-class. Reserve try/catch for error boundaries (middleware, top-level handlers) only.

---

4. Middleware Execution Order

Apply in this sequence (order matters):

1. Request ID generation
2. Request logging
3. Security headers (CORS, CSP, HSTS)
4. Rate limiting
5. Authentication
6. Authorization
7. Body parsing
8. Input validation (schema)
9. Route handler
10. Error handler
11. Response logging

---

5. API Response Contract

API endpoints should use a stable response envelope (DEFAULT) unless the protocol (GraphQL, gRPC, SSE) defines its own or the repo already has a different established contract — follow the existing contract first. Envelope, OTel, health checks, and deployment-readiness checks are production-surface concerns (dev §0.4 shared definition), conditional by project scope, not universal blockers.

Rules:

• success boolean at top level — never infer from HTTP status alone
• error.code is machine-readable (UPPER_SNAKE), error.message is human-readable
• meta.requestId on every response — enables cross-service tracing
• Pagination uses cursor-based (after/before) for large datasets, offset-based (page/pageSize) for admin UIs
• Nullability: prefer consistent key presence; omit when sparse payloads are intentional
• Timestamps: ISO 8601 UTC (2024-01-15T09:30:00Z), never Unix epoch in JSON
• Money: integer cents + currency code, never floating point

See references/core/api-design.md for protocol-specific patterns (REST, GraphQL, gRPC, tRPC).

---

6. Caching Strategy

Decision rules:

• Say Redis-compatible, not Redis-only (verified 2026-07-02): prefer Valkey

(Linux Foundation, BSD) for permissive OSS/self-hosted defaults; choose Redis when

managed-service, module, or license posture justifies it (Redis relicensed 2024;

Redis 8 added AGPLv3).

• Cache only after correctness is proven on the uncached path.
• Prefer cache-aside by default; use write-through only when strong consistency matters.
• Every key has a namespace, version, stable identifier, TTL, and invalidation trigger.
• Never cache error responses or personalized CDN responses; protect cached PII with encryption and access controls.
• Add stampede protection for hot keys and monitor hit rate, pool exhaustion, and stale-read incidents.

See references/core/caching.md for TTL guidance, Redis-compatible cache patterns, CDN rules, invalidation triggers, connection pooling, and code examples.

---

7. Observability (OpenTelemetry)

Decision rules:

• Production services emit traces, metrics, and structured JSON logs with requestId, traceId, and spanId.
• OTel maturity (verified 2026-07-02): traces and metrics are Stable in JS/Python;

logs are still Development — the baseline is trace/span-correlated structured

logs + OTel traces/metrics; adopt OTel Logs export only where that maturity is acceptable.

• Start with OTel auto-instrumentation, then add custom spans only for business-critical or non-instrumented work.
• Never log PII, secrets, full request/response bodies, or noisy stack traces outside error boundaries.
• Page only on customer-impacting signals tied to SLOs; use warning alerts for capacity trends.

See references/core/observability.md for OTel setup, structured logging conventions, trace propagation, dashboards, RUM correlation, and alerting guidance.

---

8. Skeleton Project Evaluation

When starting from a template or boilerplate, verify before building on top:

Treat templates as starting points, not gospel. Strip to essentials, then add what you need.

---

9. API Performance Targets (HEURISTIC defaults, not universal SLOs)

These are aggressive healthy-service starting budgets. Each product MUST define its own

SLOs from user journeys and alert on error-budget burn, not raw percentile thresholds

alone (Google SRE SLO practice; see observability.md Sources).

• Measure at the handler level, not including network
• Use Server-Timing header to expose backend timing to frontend
• Log slow queries (> 100ms) with EXPLAIN output
• Connection pool (long-running servers): min = CPU cores, max = CPU cores × 4; for serverless/Lambda use min = 0–2

API responses that drive UI must include descriptive error messages (not just codes) for screen reader announcement, pagination metadata (total count) for assistive technology, and Content-Language header matching response body language.

10. SEO Support Endpoints

When the app serves web pages (SSR/SSG):

• GET /sitemap.xml — dynamic sitemap generation with <lastmod>
• GET /robots.txt — configurable per-environment (disallow staging/preview)
• Structured data: provide JSON-LD data in API responses when frontend needs it
• Redirect chains: max 1 hop (301 for permanent, 308 for POST-preserving)

11. Deployment Patterns

Deployment strategy (blue-green, canary, rollback, feature flags) is owned by

dev-devops. This skill owns the backend contract that enables safe deploys:

• Database migrations: separate from code deploy, backward-compatible (expand-then-contract).
• Migrations must have a rollback path (down migration or backward-compat contract).
• Feature flags: backend provides the flag-read API; rollout strategy is dev-devops.
• Health endpoints (/health, /ready) gate traffic cuts — see §12 and references/core/health-checks.md.

---

12. Pre-Flight Checklist

Before delivering:

• [ ] Consistent response envelope on every endpoint
• [ ] Input validation with schema (Zod, Pydantic, etc.)
• [ ] Authentication middleware on protected routes
• [ ] Rate limiting on public endpoints
• [ ] Structured JSON logging with requestId and traceId
• [ ] Error handler returns proper HTTP codes via AppError hierarchy
• [ ] No raw SQL in service layer
• [ ] No hardcoded secrets
• [ ] Migrations have a rollback path (down migration or backward-compat contract)
• [ ] Observability: traces and structured logs wired (see references/core/observability.md)
• [ ] Health endpoints: /health (liveness) and /ready (readiness) — see references/core/health-checks.md
• [ ] API performance: p95 reads ≤ 200ms, slow queries logged with EXPLAIN (§9)
• [ ] SEO endpoints: sitemap.xml + robots.txt if serving web pages (§10)
• [ ] Security review: delegate to dev-security/SKILL.md for production readiness
• [ ] Stack-specific rules followed (see references/stacks/)