Layered architecture

Definition and origin

A layered architecture organises an application into horizontal layers, each of which has one technical responsibility, offers services to the layer above and uses the services of the layer below. It is the most widely used style for business applications, often by default rather than by decision, because most web frameworks generate a project with folders for views, business logic and models.

The idea is old and comes from systems software. Edsger Dijkstra described the THE multiprogramming operating system (Communications of the ACM, 1968) as a hierarchy of levels, each built only on the ones beneath it, so that each level could be reasoned about and tested on its own. Network protocol stacks such as the OSI reference model use the same principle. In business software, layering arrived with client-server and three-tier systems in the 1990s, and POSA (1996) catalogued it as the Layers pattern. Garlan and Shaw listed layered systems among their basic styles, with the constraint that interactions are limited to adjacent layers.

The typical business application has four layers. The presentation layer handles the user interface and the protocol: HTTP requests, screens, JSON. The business layer holds the rules and use cases: how an order is priced, when it may be cancelled. The persistence layer turns business objects into stored data and back, usually through repositories and an object-relational mapper. The database layer is the database itself. Small applications sometimes merge business and persistence; larger ones add layers, such as an application layer that coordinates use cases above a domain layer that holds the core model. The style does not fix the number; it fixes the direction of dependency.

How it works: closed layers, open layers and isolation

Each layer can be closed or open. A request must pass through a closed layer: the presentation layer may not reach past the business layer into the persistence layer, even when that would be quicker to write. An open layer may be bypassed. The usual example is a layer of shared technical services, such as sending emails, generating PDF receipts or writing audit records. Only some business operations need them, so forcing every request through that layer would add pointless forwarding code. In the diagram, the business layer may call the services layer or go straight past it to persistence.

Closed layers give layers of isolation. Because the presentation layer knows only the business layer's interface, the team can replace the object-relational mapper, restructure the tables or move from one database product to another without touching a single controller or template, as long as the business layer's interface stays the same. That is information hiding (David Parnas, 1972) applied to a whole tier of the code, and it is the main benefit the style offers. Every open layer, and every exception that lets one layer skip another, weakens it: if controllers query the database directly, a schema change now ripples into the presentation layer too.

The direction of dependency is the other half of the rule. Lower layers must not know about higher ones: the persistence layer must never import a controller, and the business layer must never build HTML. When a lower layer needs to notify a higher one, it does so through an abstraction the lower layer owns, such as a callback interface or an event, so that the dependency still points downwards in the code. Section 3.4 covers dependency direction, cycles and strict versus relaxed layering in depth.

It helps to keep layers and tiers apart. A layer is a logical grouping in the code. A tier is a physical boundary at run time, such as a separate server or process. A classic three-tier system runs the browser, an application server and a database server as three tiers, while the application server alone may contain three or four layers. Turning a layer into a tier puts a network between two layers that used to call each other in memory, which multiplies the cost of every call; this is rarely worth doing for its own sake.

Example: a classic web application

Consider the ordering website of a regional food-delivery company: customers browse menus, place orders and pay; restaurant staff see incoming orders. One team of five builds it with a mainstream web framework and a PostgreSQL database. A layered structure is the obvious starting point and the code layout makes the layers visible.

foodshop/
  presentation/          # HTTP only: parse requests, render responses
    order_views.py
    menu_views.py
    templates/
  business/              # rules and use cases; no HTTP, no SQL
    order_service.py
    pricing.py
  services/              # open layer: shared technical services
    email.py
    receipts.py
  persistence/           # all database access
    order_repository.py
    menu_repository.py
    models.py
  settings.py

The consequences of technical partitioning

Because layering is technical partitioning, the business domain is smeared across the layers. There is no single place called delivery: there are delivery controllers, delivery services and delivery repositories, interleaved with everything else in each layer. A developer who wants to understand how tipping works must read across all of them. As the system grows, each layer becomes a large, low-cohesion collection of unrelated code: the business layer contains ordering, payment, menu and courier rules side by side, and nothing stops the payment code from calling deep into the menu code. Over time the layers stay clean but the inside of each layer becomes a big ball of mud.

There is an organisational cost too. Organising teams by layer (a front-end team, a back-end team, a database team) means nearly every feature needs a hand-off and a queue between teams, which Conway's law then cements into the architecture. Martin Fowler calls teams organised by layer an anti-pattern for this reason: developers need not be full-stack, but teams should be. A layered architecture does not force teams to be split by layer, but it makes it the path of least resistance.

Finally, a layered monolith is one architecture quantum: one deployment unit and usually one database. Every change, however small, means building, testing and redeploying the whole application, and the whole application scales and fails as one. That is often perfectly acceptable, but it sets a ceiling.

The architecture sinkhole and other anti-patterns

The architecture sinkhole anti-pattern, a name popularised by Mark Richards, describes requests that flow through layers which do nothing but pass them on. Viewing a menu is the typical case: the controller calls a service method that calls a repository method that runs a query, and the controller and service add nothing. Every layer of pass-through adds code to write, test and read, and a little latency. Some pass-through is the price of isolation and is fine. Richards offers a rule of thumb: if roughly a fifth of requests are simple pass-through, that is normal; if most of them are, the application is probably mostly data access with little business logic, and layering is the wrong style or the layers should be opened. Opening layers, however, gives up isolation, so decide deliberately and record why.

Other common anti-patterns are worth recognising early. Leaky layers: SQL in controllers, HTTP request objects passed into services, or ORM entities rendered straight to JSON, so a change in one layer ripples into others. Upward dependencies: a repository that calls a service, or a domain object that formats HTML. The anaemic business layer: services that only shuffle data while the real rules live in controllers or stored procedures; Fowler named the related Anemic Domain Model anti-pattern in 2003. The god service: one OrderService of several thousand lines that every other service calls. The utility layer that everything depends on: a common package that gradually accumulates business logic and couples everything to everything.

When it is a good fit, and when it is not

Layered architecture is a good choice for small and medium applications built by one team, for products whose domain is not yet well understood (domain partitioning needs boundaries you do not yet know), for tight budgets and deadlines, and for applications that are mostly forms over data, with modest rules. It is also a reasonable inner structure for a single module or service that is itself part of a domain-partitioned system: a layered delivery module inside a modular monolith gets the best of both.

It is a poor choice as the top-level structure of a large system with several teams, because every team works in every layer and features collide. It is poor when parts of the system need very different scalability or availability, because there is only one quantum. And it is poor when the business logic is rich and central, because the rules are scattered among controllers, services and stored procedures; there, a domain-centred inner structure such as hexagonal or clean architecture keeps the core independent of the database and the web framework.

The most common evolution path is from a layered monolith to a modular monolith: keep one deployment, but reorganise the top level by domain and keep layers inside each module.

Enforcing the layer rules in code

Layer rules decay quickly. Under deadline pressure, a developer imports the repository straight into a controller because it saves twenty minutes, nobody notices in review, and the next developer copies the pattern. The defence is an architecture test: an automated check of dependencies that runs in the build and fails it when a rule is broken, which makes the rule a fitness function.

In Python, import-linter reads contracts from a configuration file. Its layers contract lists layers from highest to lowest and forbids any lower layer from importing a higher one. It does not on its own make layers closed (a higher layer may import any lower layer), so a forbidden contract adds the rule that presentation must not import persistence directly; it needs allow_indirect_imports switched on, because otherwise the normal chain from presentation through business to persistence would count as a violation. In Java, ArchUnit expresses the same rules as a unit test: layeredArchitecture() declares the layers by package and states, for example, that the persistence layer may only be accessed by the service layer. Similar tools exist for other ecosystems, such as dependency-cruiser for JavaScript and TypeScript.

Two practices make the checks stick. Introduce them with the existing violations recorded as known exceptions, so the build goes green immediately and only new violations fail it; then reduce the exceptions over time. And keep the configuration next to the code and review changes to it like code, because relaxing a rule is an architectural decision that deserves a decision record.

[importlinter]
root_package = foodshop

[importlinter:contract:layers]
name = Layers only depend downwards
type = layers
layers =
    foodshop.presentation
    foodshop.business
    foodshop.services
    foodshop.persistence

[importlinter:contract:closed-business]
name = Presentation must go through business
type = forbidden
source_modules = foodshop.presentation
forbidden_modules = foodshop.persistence
# presentation -> business -> persistence is the normal path
allow_indirect_imports = True