thesoftwarehouse/copilot-collections/tsh-implementing-backend

Implementing Backend

Provides patterns for building backend API services with modular architecture, structured testing, and production-ready infrastructure following TSH best practices.

When to Use

• Building new REST or GraphQL API endpoints
• Implementing CRUD operations with filtering, sorting, and pagination
• Setting up authentication and authorization (JWT)
• Integrating with external/third-party services
• Writing integration tests for endpoints or unit tests for business logic
• Configuring database migrations, seeding, or repository patterns
• Setting up Docker and docker-compose for local development
• Implementing logging and observability
• Documenting APIs with Swagger/OpenAPI
• Designing modular architecture with vertical slices

Guiding Principles

Architecture: Vertical Slice / Modular Structure

Organize code by domain/feature, not by technical layer. All artifacts related to a domain live in the same directory.

src/
├── users/
│   ├── users.controller.ts      # HTTP layer (routes, request/response)
│   ├── users.service.ts          # Business logic
│   ├── users.repository.ts       # Data access
│   ├── users.module.ts           # Module registration / DI wiring
│   ├── dto/
│   │   ├── create-user.dto.ts
│   │   └── update-user.dto.ts
│   ├── entities/
│   │   └── user.entity.ts
│   ├── tests/
│   │   ├── users.integration.test.ts
│   │   └── users.service.unit.test.ts
│   └── users.swagger.yml         # (if using separate swagger files)
├── orders/
│   ├── orders.controller.ts
│   ├── orders.service.ts
│   ├── orders.repository.ts
│   └── ...
├── shared/                       # Cross-cutting concerns only
│   ├── middleware/
│   ├── guards/
│   ├── filters/
│   ├── interceptors/
│   └── utils/
└── config/
    ├── database.config.ts
    ├── auth.config.ts
    └── app.config.ts

Rules:

• A module should be self-contained. Moving or removing a feature module should not break other modules.
• Cross-module communication goes through well-defined interfaces (service interfaces, events), never direct imports of internal classes.
• Shared utilities go in shared/ only when used by 3+ modules. Otherwise keep them in the feature module.

REST API Design

Resource Naming & HTTP Methods

Naming conventions:

• Use plural nouns for resource names: /users, /orders, /products
• Use kebab-case for multi-word resources: /order-items
• Nest sub-resources max 1 level deep: /users/:id/orders (avoid deeper nesting)
• Use query parameters for filtering, not path segments

Standard Error Response Codes

Standard Error Response Format

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    { "field": "email", "message": "must be a valid email address" }
  ]
}

DataGrid: Filtering, Sorting & Pagination (TSH Standard)

Every list endpoint returning paginated data MUST follow this schema.

Request Query Parameters

Example: GET /users?page=1&limit=10&sort[lastName]=ASC&filter[status]=active&search=john

Filter Behavior

• Same field, multiple values → interpreted as OR:

`` ?filter[firstName]=Ewa&filter[firstName]=Adam → WHERE (firstName = 'Ewa' OR firstName = 'Adam') ``

• Different fields → interpreted as AND:

`` ?filter[firstName]=Ewa&filter[lastName]=Kowalska → WHERE (firstName = 'Ewa' AND lastName = 'Kowalska') ``

• LIKE search → use URL-encoded %25 suffix:

`` ?filter[lastName]=Now%25 → WHERE lastName LIKE 'Now%' ``

Advanced Filter Operators (when applicable)

Response Format (Mandatory)

{
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 57,
      "totalPages": 6
    },
    "filter": {
      "status": "active"
    },
    "sort": {
      "lastName": "ASC"
    },
    "search": "john"
  },
  "data": [{ "..." }]
}

Rules:

• meta always reflects the actual applied parameters back to the client.
• Invalid filter/sort field names are silently ignored (no error thrown), but not applied.
• Default limit should be defined in app configuration (e.g. 20 or 50).
• Maximum limit should be capped to prevent abuse (e.g. 100 or 250).

Authentication & Authorization

JWT-Based Authentication

• Use JSON Web Tokens (JWT) for stateless authentication.
• Token is passed in the Authorization header: Bearer <token>.
• Validate the token signature, expiration (exp), and issuer (iss) on every protected request.
• Store secrets/keys in environment variables, never in code.
• Use short-lived access tokens (15-60 minutes) with refresh token rotation where appropriate.

Current User Endpoint

• Expose a GET /me endpoint that returns the profile of the currently authenticated user.
• This endpoint should extract the user identity from the JWT (e.g. sub claim) and return the full user profile.
• Do not accept user ID as a parameter — always derive from the token.

GET /me
Authorization: Bearer <token>
→ 200 { "id": "...", "email": "...", "roles": [...] }

Authorization

• Implement role-based access control (RBAC) or attribute-based access control (ABAC) depending on project complexity.
• Authorization checks happen via middleware/guards before reaching the controller action.
• Always validate that the authenticated user has permission to access/modify the specific resource (not just the endpoint).

Dependency Injection

• Always use a DI container. Register services, repositories, and infrastructure in a central container/module.
• Inject dependencies via constructor injection.
• Depend on interfaces/abstractions, not concrete implementations.
• DI enables testability: in tests, swap real implementations with mocks/stubs.

See the technology-specific references below for recommended DI frameworks per language.

Database Handling

ORM & Repository Pattern

• Use the project's ORM for all database operations (TypeORM, MikroORM, Doctrine, Entity Framework, Hibernate, GORM, etc.).
• Implement the Repository Pattern: all database queries go through repository classes, never directly from services or controllers.
• Repositories return domain entities/models, not raw database rows.
• Use transactions for operations that modify multiple tables/records.

Migrations

• All database schema changes go through migration files. Never modify the database manually.
• Each migration must have both up (apply) and down (revert) methods.
• Migrations run automatically on application startup (for containerized apps) or via a dedicated migration command/lambda (for serverless).
• Never modify an existing migration that has been deployed. Create a new migration instead.
• Name migrations descriptively: 2025-02-08-add-status-column-to-orders.

Seeding

• Provide seed data for development, test, and staging environments only.
• Never seed production or UAT environments with test data.
• Seeds should be idempotent — running them multiple times produces the same result.
• Separate seed files by domain (e.g. seed-users.ts, seed-products.ts).

Database Best Practices

• Use UUID or ULID for primary keys where appropriate (better for distributed systems).
• Define proper indexes for foreign keys, frequently queried columns, and unique constraints.
• Use snake_case naming for tables and columns (e.g. order_items, created_at).
• Always define created_at and updated_at timestamps.
• Use soft deletes (deleted_at) when business rules require record retention.

External Service Adapters (Third-Party Clients)

When integrating with external APIs, always create a dedicated client/adapter class.

Pattern

src/
├── integrations/
│   ├── payment-gateway/
│   │   ├── payment-gateway.client.ts   # HTTP calls, request/response mapping
│   │   ├── payment-gateway.types.ts    # External API types/interfaces
│   │   └── payment-gateway.module.ts   # DI registration
│   ├── email-provider/
│   │   ├── email-provider.client.ts
│   │   └── ...

Rules

1. Isolate all HTTP communication with external services into a client class. Never call HTTP clients (Axios, fetch, HttpClient) directly from services or controllers.
2. Map external types to internal domain types at the adapter boundary. The rest of the application should not know about the external API's data format.
3. Store configuration (API URLs, keys, tokens) in environment variables and inject via config.
4. Handle errors gracefully: catch HTTP errors, map them to domain-specific exceptions, and log the details.
5. Make clients testable: depend on an interface so the client can be mocked in tests.
6. Add retry logic and timeouts for resilience. Use circuit breaker patterns for critical integrations.

Testing Strategy

Test Pyramid

See the technology-specific references below for recommended testing tools per language.

Integration Tests for Endpoints