backend-patterns

Backend Patterns Skill

Deep backend architecture patterns for building production-grade server applications.

When to Use

Activate this skill when:

• Designing API endpoints or services
• Making database schema decisions
• Implementing caching, queuing, or background jobs
• Setting up authentication/authorization architecture
• Structuring a backend project

---

1. API Design Patterns

RESTful Resource Design

// DECISION FRAMEWORK: Choose your API style
//
// REST   → CRUD-heavy, public APIs, caching-friendly
// GraphQL → Complex nested data, mobile clients, bandwidth-sensitive
// tRPC   → TypeScript monorepo, full-stack type safety
// gRPC   → Microservice-to-microservice, high performance

// REST Naming Convention:
// ✅ GET    /api/users          → List users
// ✅ POST   /api/users          → Create user
// ✅ GET    /api/users/:id      → Get single user
// ✅ PATCH  /api/users/:id      → Partial update
// ✅ DELETE /api/users/:id      → Delete user
// ✅ GET    /api/users/:id/orders → Nested resource
//
// ❌ GET /api/getUsers          → Verb in URL
// ❌ POST /api/users/create     → Redundant verb
// ❌ GET /api/user              → Singular for collection

Layered Architecture (Handler → Service → Repository)

// Layer 1: Handler — HTTP concerns ONLY
// - Parse request (params, body, query)
// - Call service
// - Format HTTP response
// - NO business logic here
async function createUserHandler(req: Request, res: Response) {
  const input = CreateUserSchema.parse(req.body)       // validate
  const result = await userService.createUser(input)    // delegate
  return res.status(201).json({ success: true, data: result })
}

// Layer 2: Service — Business logic ONLY
// - Orchestrate operations
// - Enforce business rules
// - Transaction boundaries
// - NO HTTP concepts, NO direct DB queries
class UserService {
  constructor(
    private userRepo: UserRepository,
    private emailService: EmailService,
    private eventBus: EventBus
  ) {}

  async createUser(input: CreateUserInput): Promise<User> {
    await this.ensureEmailUnique(input.email)
    const user = await this.userRepo.create({
      ...input,
      password: await hashPassword(input.password),
    })
    await this.eventBus.publish('user.created', { userId: user.id })
    return user
  }
}

// Layer 3: Repository — Data access ONLY
// - Single table/entity operations
// - Query construction
// - NO business logic, NO cross-entity operations
class UserRepository {
  async create(data: CreateUserData): Promise<User> {
    return prisma.user.create({ data })
  }
  async findByEmail(email: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { email } })
  }
}