---

name: backend-controller-pattern description: This skill provides general guidelines for designing backend controller layers across any framework. It should be used when implementing REST endpoints, handling HTTP status codes, managing pagination, or structuring API request/response handling.

Backend Controller Pattern Skill

General guidelines for API Boundaries.

for framework-specifics, see:

• NestJS Controllers

For validation/serialization rules, see:

• Data Validation

Core Responsibilities

1. Accept HTTP requests (Method, Body, Query, Headers)
2. Validate input (Check format, required fields)
3. Call Service Layer (Delegate business logic)
4. Serialize Response (Transform/Filter data)
5. Handle Errors (Map exceptions to HTTP Status codes)

HTTP Status Codes

Use standard REST conventions:

Input Validation

Principle: Validate at the Gate.

• Never let invalid data reach business logic.
• Never trust client input (even from your own frontend).
• Transform API format (snake_case) to Internal format (camelCase).

See Data Validation Skill for detailed Schema definitions.

Response Serialization

Principle: Filter at the Exit.

• Always return consistent JSON structures.
• Never expose Database IDs (BigInt), use UIDs (string).
• Never expose internal fields (password, deletedAt).
• Transform Internal format (camelCase) to API format (snake_case).

Pagination

Principle: Always Limit Lists.

Unbounded queries are a DoS vector and performance killer.

Standard Response Format:

Copy{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 150
  }
}

Authorized vs Authenticated

Understand the difference:

• Authentication (401): "Who are you?" (Login check)
• Authorization (403): "Are you allowed?" (Permission check)

Layer Boundaries

Strict separation of concerns:

Copy[ HTTP Controller ]  <-- Knows about Requests, Responses, Status Codes
        |
        v
[ Business Service ] <-- Knows about Logic, Transactions, Domain Errors
        |
        v
[ Data Repository ]  <-- Knows about Database, SQL, ORM

Anti-Patterns:

• ❌ Controller running SQL queries (Leaky abstraction)
• ❌ Controller containing complex logic (Fat controller)
• ❌ Service returning HTTP objects (Service coupled to transport)