Backend from First Principles: The Request Life Cycle (Handlers, Services, Repositories, & Middleware)

As a backend engineer, your primary job is to manage the flow of data through your application, from the moment a client's request arrives until the final response is sent. While this may sound like a single, simple task, a robust, production-grade backend relies on a layered architecture and a set of critical tools to handle this process securely and efficiently.

This guide will break down the essential components of a backend system, tracing the journey of a request and explaining the fundamental patterns that every engineer should know: Handlers, Services, Repositories, Middleware, and Request Context.

Now, in this part, we take an deep dive into the server's internal workings. With the request successfully received and its data initially validated and transformed, we explore the internal request life cycle: how the data flows through distinct architectural layers, and how powerful tools like Middleware and Request Context efficiently manage cross-cutting concerns and shared state. This completes our picture of how a server precisely handles a client's request from start to finish.

Part I: The Core Architecture: Layers of Responsibility

When a client's request reaches your server, it doesn't immediately execute a complex task. Instead, it moves through a pipeline of distinct layers, each with its own well-defined responsibilities. This layered approach is a design pattern that promotes scalability, maintainability, and debuggability.

Let's break down the three primary layers.

1. The Handler / Controller Layer

The Handler (or Controller) is the entry and exit point for every HTTP request. Its sole responsibility is to interact with the HTTP protocol.

Receives Requests: It is the function that is directly invoked by the routing mechanism when a specific API endpoint is hit (e.g., POST /api/users). It's responsible for extracting the raw request information, whether it's from query parameters (for GET requests), the request body (for POST, PUT, PATCH, DELETE requests), or headers.
Deals with HTTP Objects: It receives the raw request and response objects, which contain all the HTTP-specific information.
Initial Data Processing & Binding: The Handler's first task is to extract data from the request object and deserialize it from a format like JSON into the programming language's native data structure (e.g., a Go struct or a Python dictionary). This process is sometimes called binding. If this deserialization fails (e.g., malformed JSON), the Handler should immediately send a 400 Bad Request error. Additionally, this is where initial transformations can occur; for instance, if a client doesn't provide a sort query parameter for an /api/books endpoint, the Handler can default it to sort=date to ensure consistent downstream processing.
Orchestrates the Response: After processing is complete, the Handler takes the result and formats it into an appropriate HTTP response. This includes setting the correct status code (e.g., 200 OK, 201 Created, or 400 Bad Request) and an appropriate response body.

The key principle here is: all HTTP-related concerns end at the Handler layer.

2. The Service Layer

The Service Layer contains the core business logic of your application. This is where the magic happens. Unlike the Handler, the Service Layer is completely decoupled from the HTTP protocol; it has no knowledge of requests or responses.

Takes Clean Data: It receives only the clean, validated, and deserialized data from the Handler.
Performs Business Operations: It orchestrates the actual work of the application. This could involve calling one or more repository methods to interact with the database, making external API calls, sending an email notification, or running complex calculations. A single service method might orchestrate multiple repository calls, combining data from different sources to fulfill the business requirement.
Returns Data: Its job is to return the result of its operations back to the Handler, which then decides how to format the HTTP response.

Think of the Service Layer as the brain of your application. It knows what needs to be done, but it doesn't care how the data got there or how it will be sent back.

3. The Repository Layer

The Repository Layer is responsible for all database interactions. It provides a clean, abstract interface for the Service Layer to interact with your data persistence layer (like a SQL or NoSQL database).

Single Responsibility: A repository method should do one thing and one thing only. For instance, get_all_books() should return all books, and get_book_by_id(book_id) should return a single book. These should ideally be separate methods to maintain clarity and separation of concerns, rather than using optional parameters to return different types of data from one method.
Constructs Queries: It takes the data passed from the Service Layer and constructs the appropriate database query (e.g., SQL statements, ORM calls, or NoSQL commands).
Returns Raw Data: It returns the raw data fetched from the database back to the Service Layer.

The Repository Layer is a crucial abstraction. It allows you to change your database technology (e.g., from MySQL to PostgreSQL) without having to modify your Service or Handler layers.

The Request Life Cycle in Practice

The flow of data through these layers is a one-way street:

Client → Handler → Service → Repository → Service → Handler → Client

A request from the Client arrives at the Handler.
The Handler takes the data, validates it, and passes it to the Service Layer.
The Service Layer performs its business logic. If it needs to interact with the database, it calls a method in the Repository Layer.
The Repository Layer executes a database query and returns the data to the Service Layer.
The Service Layer processes the raw data, performs any final logic, and returns the result to the Handler.
The Handler formats the final response and sends it back to the Client.

Part II: The Power of Middleware

While the Handler/Service/Repository pattern handles the core logic, many operations are common to every single API request. Instead of duplicating this code in every Handler, we use Middleware.

A Middleware is a function that sits in the middle of the request life cycle. It has a unique ability to intercept, inspect, and modify the request and response objects, as well as to terminate the request early.

A typical middleware function receives three parameters: request, response, and a special function called next(). The next() function is what passes control to the next middleware in the pipeline, or to the final Handler. The order of middlewares is crucial, as the request flows through them sequentially.

Here are some common examples of middlewares and why they're perfect for the job:

Security Middlewares

CORS (Cross-Origin Resource Sharing): This middleware intercepts a request and checks its origin. If the origin is from an approved domain, it adds appropriate headers to the response object before calling next(). This ensures that only authorized web applications can communicate with your server, a browser-level security feature.
Security Headers: This middleware adds important HTTP security headers (e.g., Content-Security-Policy, X-Frame-Options, Strict-Transport-Security) to every response, enhancing the overall security posture of your application.
Authentication: This is a crucial middleware. It takes a token from the request headers, verifies it, and performs authentication.
- If successful: It stores the authenticated user's ID and role in a shared state (we'll cover this next) and calls next() to allow the request to proceed.
- If it fails: It immediately sends a 401 Unauthorized response to the client and does not call next(), effectively terminating the request before it reaches any sensitive business logic.
Rate Limiting: This middleware tracks the number of requests from a specific client (e.g., using their IP address) over a period of time.
- If the limit is exceeded: It returns a 429 Too Many Requests error and terminates the request.
- If the limit is not exceeded: It calls next(), allowing the request to proceed.

Logging and Monitoring Middlewares

Logging: A logging middleware will execute for every single request. It can extract various parameters like the request path, method, query parameters, and even parts of the request body, logging them to a console or a log file. This centralized logging is vital for auditing, debugging, and monitoring the health of your application without cluttering your core business logic.

Utility Middlewares

Global Error Handling: This is arguably the most important middleware, and its placement is key. It's usually the last middleware in the pipeline. Its job is to catch any unstructured errors that may have occurred in any of the upstream layers (Handlers, Services, or other middlewares). It then takes that error, formats it into a standardized, client-friendly JSON error response (e.g., with a 400 client error or 500 server error status code), and sends it back. This ensures a consistent error experience for the client, no matter what went wrong.
Compression: For API calls that return large amounts of data, a compression middleware (e.g., using GZIP) can compress the response body before it is sent back to the client, significantly reducing bandwidth and improving performance for the client.
Data Passing/Binding Middleware: While initial deserialization and validation can occur in the Handler, in some frameworks, these processes can also be entirely delegated to dedicated middleware functions upstream of the Handler. This centralizes the parsing and validation logic even further.

Part III: The Request Context: A Shared State

So far, we've seen how middleware can modify a request and pass it to the next function. But what if a middleware needs to share information with a Handler or a Service method further down the line, without directly passing it as a function argument? This is where the Request Context comes in.

A Request Context is an object that acts as a key-value storage that is scoped to a single request. It is created when a request first arrives and is accessible throughout the entire life cycle of that request, across all middlewares and the Handler.

Why is it needed? The Problem of Decoupling

The Handler/Service/Repository pattern is about keeping components loosely coupled. However, this creates a challenge. For example, your Service Layer needs to know the user's ID to save a new book in the database, but it can't depend on the Handler to pass it the ID because that would be a tight coupling.

Request Context solves this:

Authentication Middleware: The authentication middleware is the first component to verify a user's identity. Once it successfully authenticates a user, it stores the user_id and user_role (or other permissions) in the Request Context.
Handler/Service Layer: Downstream, when the execution reaches your Handler or Service method, it can pull the user_id directly from the Request Context. This is a secure and trusted source of information. The Handler and Service methods never have to worry about the origin of the user_id; they just trust that it was placed there by the authentication middleware.

Crucially, this prevents a major security vulnerability: a malicious client could send a forged user_id in the request body. By taking the user ID from a trusted source (the authentication middleware's Request Context) instead of the client's payload, you prevent this kind of attack.

Other Use Cases for Request Context

Traceability: A middleware can generate a unique request_id (e.g., a UUID) at the start of a request and store it in the context. This ID can then be included in all log messages and external API calls made by the Service Layer (especially in microservice architectures), allowing you to trace the entire request flow for debugging or auditing purposes.
Cancellation/Timeouts: The Request Context can carry a cancellation signal or a deadline. If a request times out, the signal can be propagated through the context to any ongoing database operations or external API calls, allowing them to abort gracefully instead of hanging forever and consuming server resources.

Conclusion

The request life cycle in a production-grade backend is a meticulously orchestrated process. By understanding and implementing these fundamental patterns—the layered architecture of Handlers, Services, and Repositories, the reusable power of Middleware, and the shared-state mechanism of the Request Context—you can build systems that are not only functional but also scalable, maintainable, and, most importantly, secure.

Credit goes to the Backend From First Principle Playlist by Sriniously

Search This Blog

The JK Journal

The Anatomy of a Backend Request: Layers, Middleware, and Context Explained