---
name: backend-systems-guidance
description: Canonical overlay for server-side networked code that needs stronger architecture, testing, reliability, and security discipline. Use alongside the repo's implementation skill when implementing or reviewing backend services, APIs, middleware, queues, repositories, or backend refactors.
---

# Backend Systems Guidance

This is a composable overlay, not a standalone workflow.
Use alongside the repo's implementation skill when the change touches backend
code.

This is the canonical backend overlay in this repo.
It extends the thin baseline `backend-guidance` overlay with stronger guidance
for non-trivial service boundaries, repositories, reliability, and trust
boundaries.

Prefer it over `backend-guidance` when the task includes new endpoints or
consumers, multi-layer refactors, repository or transaction work, auth or
trust-boundary logic, or backend review that needs explicit testing and
reliability checks.

Use the bundled references only when needed:

- [references/fusion-notes.md](references/fusion-notes.md) for why this skill is
  narrower than the source set it came from
- [references/trigger-evals.md](references/trigger-evals.md) for lightweight
  prompt checks when revising the trigger or scope

## When to use

- the repo has server-side networked code such as HTTP handlers, gRPC methods,
  webhooks, queue consumers, or message producers
- the task adds or reshapes routes, controllers, services, repositories,
  middleware, or request-processing boundaries
- the task changes auth, authorization, validation, idempotency, retries,
  external requests, caching, or observability
- the task needs backend review beyond basic handler thinness, especially for
  security, data access, or missing tests

## Not for

- HTTP client code, CLI tooling, offline batch scripts, or data pipelines with
  no request or consumer boundary
- frontend-only work
- threat modeling or security audit work where `security` should be the primary
  workflow skill

Do not fold infrastructure deployment workflows, outbound-client-only guidance,
or full security-audit checklists into this skill. Keep this overlay centered
on backend request and consumer systems plus their immediate reliability and
trust boundaries.

## Core workflow

1. Read the touched backend files and map the request or consumer path end to
   end: boundary, service logic, data access, external calls, and state
   changes.
2. Pick the mode before changing code:
   - baseline backend change when the work is mostly a thin handler or small
     service fix
   - service-boundary change when responsibilities, data access, or dependency
     direction may need to move
   - reliability-hardening or review mode when the main risk is missing tests,
     auth gaps, retries, observability, or unsafe failure handling
3. Keep the boundary thin: decode input, authenticate and authorize, validate,
   call a service, map transport errors, and serialize output. Business
   decisions belong in service code that can run without the transport layer.
4. Place persistence and external integrations deliberately:
   - repositories or data adapters own query shape, batching, and transaction
     details when that improves clarity or testing
   - services coordinate business rules, idempotency, retries, and side-effect
     ordering
   - handlers and controllers do not reach directly into ORM or network clients
     unless the change is truly trivial and stays trivial
5. Harden cross-cutting concerns at the edge:
   - validate external input once at the boundary
   - enforce auth and authorization before business actions
   - set timeouts, retry rules, and destination allowlists for outbound calls
   - use structured logging, correlation identifiers, and explicit error
     mapping for observable failure paths
6. Choose the smallest test set that proves the change:
   - unit tests for service logic and decision branches
   - integration tests for handlers, consumers, repositories, and transaction
     behavior
   - auth and permission tests for protected flows
   - contract or schema tests when the change alters external API or event
     shapes
   - load or concurrency tests only for changed hotspots, queue throughput, or
     latency-sensitive paths
7. Review the result for boundary leaks, unsafe defaults, data-access
   inefficiency, and missing verification before finishing.

## Decision rules

- Start with `backend-guidance` for ordinary backend edits. Use this overlay
  when the task needs stronger design pressure, harder review, or explicit
  backend quality gates.
- Keep handlers thin in responsibility, not by literal line count. If a
  handler or consumer owns business decisions, retries, transaction branching,
  or query orchestration, extract inward.
- Keep business logic transport-free. If testing a rule requires booting HTTP,
  gRPC, or queue infrastructure, the logic is in the wrong place.
- Add a repository or data-access interface when it reduces duplication,
  isolates non-trivial queries, helps transaction composition, or makes tests
  materially simpler. Do not add one for single-call trivial CRUD.
- Prefer one validation pass at the outer edge plus typed internal data. Avoid
  repeated validation in every layer unless a trust boundary changes.
- Treat retries as a design choice, not a default. Only retry idempotent or
  explicitly deduplicated work, and pair retries with deadlines or backoff.
- Use idempotency keys or duplicate-detection for retried creates, webhook
  handlers, and queue consumers that can be re-delivered.
- Every outbound request needs a timeout and failure policy. For user-controlled
  destinations, apply allowlists or equivalent SSRF protections.
- Keep error handling explicit: domain code returns or throws domain-level
  failures; boundary code maps them to HTTP, gRPC, queue, or job semantics.
- Measure before adding caching. Cache only stable read paths with clear
  invalidation or bounded staleness.

## Validation

A backend change is done when, in addition to the base implementation skill's
validation:

- handlers or consumers stay as boundary glue and delegate business decisions to
  testable service code
- data access and external I/O live behind clear seams when the change is
  non-trivial
- external input, auth, and transport-specific error mapping stay at the edge
- retries, idempotency, timeouts, and failure handling are explicit where the
  change can duplicate work or call remote systems
- tests cover the changed behavior at the correct level, including integration
  coverage for boundary behavior and permission or failure cases when relevant
- new high-risk paths emit enough evidence to debug production behavior