The external lifecycle is request in, response out. This page follows the internal lifecycle between those two events.
- Client and routing
The client enters the application through routing.
- Handler
Parse the HTTP contract and call the application service.
- Service
Apply application and domain decisions, then request persistence through a repository.
- Repository and database
The repository talks to storage. Return the result through the service and handler to the client.
The response returns through the calling path; each responsibility stays in its own layer.
How to read this model
A processing line with four purposeful stations. The object is a teaching analogy. Inspecting a part highlights its role; it does not execute or simulate the software. Cabinet trays are records, workpieces are data, and latches are checks. Unless an explanation states a quantity, compartments and sample workpieces do not denote data counts. Part dimensions are not a quantitative scale.
- The operating system sends the request to the port where the server listens.
- The router matches the method and path, including dynamic segments such as
/users/123. - Middleware can reject the request, add context, or prepare shared state.
- The handler extracts and validates input, calls the service, and chooses the response format and status code.
- The service applies business rules and coordinates repository or external calls.
- The repository runs a database operation. The result then travels back up the path.
| Layer | Owns | Does not own |
|---|---|---|
| Handler or controller | Input and output formats, validation, status codes | Business rules and SQL |
| Service | Business processing and orchestration | HTTP objects and response codes |
| Repository | Database queries and persistence mapping | Business orchestration |
Why split the layers
The split gives each change a likely home. A response format can change in the handler. A rule can change in the service. A query can change in the repository. Tests can cross a small interface at each seam.
The split also has a cost. Three thin wrappers add indirection without hiding complexity. Keep a smaller application together until a separate interface buys locality or reuse. How to use this handbook uses the same depth test throughout this handbook.
Continue with handlers and controllers, services, and repositories. For the network side of the contract, read HTTP and APIs.