Backend Service Guidelines

Purpose

Provide a practical, provider-agnostic checklist and working patterns for building and refactoring backend HTTP services with a layered architecture.

When to use

Use the apply-backend-service-guidelines skill when you are:

• Adding or changing HTTP endpoints (routes, controllers)
• Implementing business logic (services) or data access (repositories)
• Introducing middleware (auth, validation, auditing, rate limits)
• Standardizing error handling, logging, and observability
• Designing configuration loading and validation
• Writing or fixing backend tests (unit and integration)

Avoid using the skill when:

• you are making a narrow, single-concern change (for example, only adjusting one validation rule) and you do not need a cross-layer consistency check
• you are doing one-off debugging with a known root cause and you only need a small targeted fix

Inputs

You SHOULD have:

• The endpoint(s) being added/changed (method + path) and expected request/response shapes
• The business rules (what MUST be enforced, what MAY be optional)
• Data model information (entities, persistence requirements)
• Existing conventions in the codebase (framework, validation library, ORM/query layer)

Outputs

The skill produces one or more of:

• A clear layering plan: route → controller → service → repository
• Implementation scaffolding (controller/service/repository skeletons)
• A validation schema and error contract
• A minimal test plan (unit + integration) with verifiable acceptance criteria

Architecture rules

These rules prevent “everything everywhere” backends.

1. Routes MUST only wire HTTP to handlers

   • Register middleware and delegate to a controller.
   • Routes MUST NOT contain business logic.

2. Controllers MUST only handle HTTP concerns

   • Parse/validate inputs, translate errors to HTTP responses, and call services.
   • Controllers SHOULD be thin and testable.

3. Services MUST contain business logic

   • Services MUST be free of HTTP concepts (no req, res).
   • Services SHOULD orchestrate repositories and other services.

4. Repositories MUST isolate data access

   • Repositories SHOULD hide ORM/query details from services.
   • If the project is simple, repositories MAY be omitted; once queries become non-trivial, add a repository layer.

Error handling contract

• You MUST define an error taxonomy (validation, not found, forbidden, conflict, internal).
• You MUST return a consistent error shape across endpoints.
• Unknown errors MUST be logged and mapped to 5xx without leaking sensitive details.

Validation

• All external inputs (body, params, query) MUST be validated.
• Validation SHOULD happen at the controller boundary.
• Validation errors MUST map to 4xx with actionable messages.

Configuration

• Runtime configuration MUST be centralized and typed.
• Configuration SHOULD be validated at startup.
• Secrets MUST NOT be logged and SHOULD be injected via the runtime environment or a secrets manager.

Testing expectations

• Services MUST have unit tests for core business rules.
• Endpoints SHOULD have integration tests for request/response + persistence behavior.
• Tests SHOULD cover:
  • Happy path
  • One representative validation failure
  • One representative authorization/permission failure (if applicable)

Steps

1. Clarify the API contract

   • Define request schema and response schema.
   • Decide status codes for success and known failure modes.

2. Choose the layering

   • Add/extend: route → controller → service → repository (as needed).

3. Implement validation

   • Define a schema for inputs.
   • Convert schema failures to your standard error response.

4. Implement business logic

   • Place business rules in the service.
   • Keep functions small; prefer pure helpers for tricky logic.

5. Implement data access

   • Use repositories for complex queries and persistence workflows.
   • Add transactions where “all-or-nothing” semantics are required.

6. Add observability

   • Add structured logs around boundaries (start/end, key identifiers).
   • Capture exceptions in your error tracker and include correlation IDs if available.

7. Add tests

   • Unit tests for service rules.
   • Integration tests for the endpoint behavior.

8. Verify

   • Run the service locally or in CI.
   • Validate response shapes and database side effects (if any).

Verification

• Routes delegate to controllers without business logic
• Controllers validate inputs and map errors consistently
• Services contain business rules and are HTTP-free
• Repositories isolate data access (when used)
• Error responses follow the standard shape
• Unit tests cover core business rules
• Integration tests cover at least one happy path per endpoint

Boundaries

• MUST NOT hardcode project-specific paths, scripts, or environment layouts in shared skills
• MUST NOT include credentials, secrets, or real tokens in examples
• MUST NOT log secrets or sensitive data
• SHOULD NOT introduce new patterns if the codebase already has an established convention unless there is a clear benefit and migration plan
• SHOULD NOT skip validation for any external input
• SHOULD NOT bypass error handling contract

Included assets

• Templates: see ./templates/ for controller/service/repository/error scaffolds.
• Examples: see ./examples/ for complete request flows and refactoring patterns.