Architecture Overview (Backend Services)

This skill describes a layered architecture that keeps HTTP concerns, business logic, and data access separated.

Layered architecture pattern

HTTP Request
  ↓
Routes (routing only)
  ↓
Controllers (HTTP handling)
  ↓
Services (business logic)
  ↓
Repositories (data access)
  ↓
Database

Responsibilities by layer

• •

  Routes

  • •Register paths/methods and middleware
  • •Delegate to controllers
  • •Do not contain business rules
• •

  Controllers

  • •Parse params/body/query
  • •Validate inputs
  • •Call services
  • •Translate domain errors into HTTP responses
• •

  Services

  • •Business rules and orchestration
  • •No direct HTTP knowledge (Request/Response types)
• •

  Repositories

  • •Encapsulate DB queries and transactions
  • •Return domain-friendly results
  • •Map DB errors into typed errors

Request lifecycle (example)

// Route delegates to controller
router.post("/users", authMiddleware, (req, res) => userController.create(req, res));

// Controller validates and calls service
const input = createUserSchema.parse(req.body);
const user = await userService.create(input);

// Service enforces business rules and uses repository
return await userRepository.create(input);

Middleware ordering (high signal)

Typical safe ordering:

1. •Monitoring/request tracing init (first)
2. •Body parsing
3. •Cookie/session parsing (if used)
4. •Request context (correlation ids, user identity)
5. •Routes
6. •Error boundary (last)
7. •Monitoring error handler (last)

Rule: error handlers must be registered after routes.

Related Skills

• •routing-and-controllers
• •services-and-repositories