Layered Architecture

This unlocks the ability to understand why large software systems — including the code behind AI products — are structured the way they are. Without this, reading a real codebase feels like wandering through a city with no map. With it, you can find where a bug lives, what a change will break, and why a team put a database gate between you and your data. It is the foundation for every other architecture idea in your library: Hexagonal Architecture, Ports and Adapters, Dependency Inversion, Separation of Concerns. Master this and the rest become variations on the same idea.

Think of a building. It has a facade, interior walls, load-bearing pillars, and a foundation. A good building keeps the plumbing hidden, the electrical wiring out of sight, and the occupants safe. A bad building runs a water pipe through the middle of a bedroom because someone needed a tap there and it was cheaper at the time. Software is the same. A layered system separates the parts that people touch (the presentation), the parts that decide what the app actually does (the application and domain logic), and the parts that talk to the outside world like databases and servers (the infrastructure). The rule is that each layer only ever talks to the layer directly beneath it — it never reaches across. The presentation layer never touches the database; the application layer never writes a SQL query. This one rule, applied even by hand, prevents a thousand disasters: you can change the database without touching the screen, you can test the business rules without a real database, and when something breaks, you know which floor to go to. The cost is a little extra planning up front — but what you buy is a system that does not slowly rot into a tangled mess.

A government ministry. The public submits forms at the counter (presentation). The counter clerks do not decide policy — they just take the form and pass it to the case officers who apply the rules of the ministry (application). The actual rules of who gets what, written by legislators, are the domain. The ministry does not write its own electricity grid or run its own post — it uses the national infrastructure: the postal service, the power company, the tax records that live somewhere else. The strict rule is that the counter never goes straight to the power company to demand a favour, and the case officers never open the treasury vault themselves. Every request flows down one floor at a time. The upshot is that the ministry can switch from letters to email without changing the rules, and when the treasury changes its records system, the ministry's application logic does not care. Where the analogy breaks down: real government floors do not have written dependency rules, and they drift into chaos because people are impatient and take shortcuts. In software, the dependency rule is enforced by the compiler and the code review, not by a sign on a door. Also, a ministry has many floors with many shortcuts; a well-built software system is ruthlessly disciplined — no layer ever reaches over another, even if the shortcut is tempting.

Layered architecture is a way of organising a codebase into distinct horizontal tiers — presentation, application, domain, and infrastructure — where each tier may only depend on the one beneath it, so that the outer tiers (user interface, data access) can change without disturbing the inner ones (business rules).

Your library lists this under Software Architecture, the parent concept of structural decisions. You already have notes on Separation of Concerns and Single Responsibility — this is their structural expression. Layering is the concrete realisation of 'keep distinct responsibilities in distinct places'. You also have notes on Hexagonal Architecture and Ports and Adapters — those are a stricter version of the same idea, where the domain is at the centre and all external interaction goes through defined interfaces instead of just a layer boundary. Dependency Inversion is the mechanism that makes it work: you depend on abstractions, not concrete implementations, so the outer layer can be swapped without touching the inner. The 'ilities' — maintainability, testability, scalability — are the payoff this trade buys.