10.2.1 The pattern you already live in🔗

Look at what the last three lectures produced, stacked in order:

• FastAPI lecture—route handlers that parse HTTP, validate input with Pydantic, and return JSON.

• REST lecture—the contract those handlers expose: resources, methods, status codes.

• Database lecture—crud.py over SQLAlchemy models over PostgreSQL, and exercise E8, which wired the API to real storage without changing the contract tests.

That separation—HTTP concerns here, data concerns there, rules in between—has a name: layered architecture (also called n-tier architecture), one of the most common software architecture patterns in industry. Today we make the pattern explicit, name its rules, and—most importantly—see what happens when you don’t follow it.

10.2.2 Why architecture patterns exist at all🔗

An architecture pattern is a pre-made decision about where code goes. Its value is boring and enormous: when every feature asks “where do I put this?”, a team without an answer produces the big ball of mud—everything touching everything, where no change is safe. A pattern answers the question once, for the whole codebase. (This is CLAUDE.md-thinking at the largest scale: conventions written down so nobody—human or AI agent—has to re-decide them per feature. Indeed, “which layer does this belong in?” is precisely the kind of instruction your agents need in a design doc.)

10.2.3 Intuition: a restaurant🔗

A layered application is a restaurant. The waiter (presentation) talks to customers, writes down orders in a fixed format, and never cooks. The chef (business logic) decides whether the order is possible, applies the house rules, and never talks to customers. The pantry clerk (data access) is the only person who goes into the storeroom (database). The customer never wanders into the pantry; the chef never argues with a diner. Each role is replaceable—new waiter, same kitchen—precisely because the handoffs are standardized.

10.4.1 The request flow, traced🔗

GET /tasks/123—the reference outline’s flow, on our stack:

Notice the translation duty at each boundary going up: the repository turns rows into domain objects; the presentation turns domain results into HTTP. The service in the middle speaks only domain language—Task, User, TooManyOpenTasks—never Request, never SELECT. When you review code (or an agent’s diff), vocabulary is the fastest layer-violation detector: a word from the wrong layer’s language is a misplaced responsibility.

10.5.1 Presentation layer🔗

Responsibility: everything about talking to the outside—REST endpoints, request parsing, input validation, serializing results, mapping outcomes to status codes. React frontends, mobile UIs, and CLI interfaces are presentation too: alternative front doors to the same building.

# app/api.py (excerpt) -- speaks HTTP, delegates everything else
@router.post("/tasks", status_code=201)
def create_task(body: TaskCreate,
                svc: TaskService = Depends(get_service)) -> TaskOut:
    try:
        task = svc.create_task(owner=body.owner, title=body.title, due=body.due)
    except DomainError as exc:
        raise HTTPException(status_code=422, detail=str(exc))  # translate!
    return TaskOut.from_task(task)

The handler is thin on purpose: parse, delegate, translate, serialize. The try/except is the layer boundary made visible—the service raises domain exceptions (TooManyOpenTasks); the presentation layer alone knows that this maps to 422 (REST lecture vocabulary). If you ever see HTTPException raised inside a service, a layer has leaked.

10.5.2 Business logic layer (service layer)🔗

Responsibility: the application’s rules and workflows—policies, calculations, authorization checks, transaction boundaries. This layer is the reason the software exists; the other three are plumbing it needs.

# app/services.py (excerpt) -- speaks pure domain language
MAX_OPEN_TASKS = 20

class TaskService:
    def __init__(self, repo: TaskRepository):
        self.repo = repo                      # depends on the layer below

    def create_task(self, owner: str, title: str, due: date) -> Task:
        if self.repo.count_open(owner) >= MAX_OPEN_TASKS:
            raise TooManyOpenTasks(f"{owner} already has {MAX_OPEN_TASKS} open tasks")
        if due < date.today():
            raise DueDateInPast(f"{due} is in the past")
        return self.repo.add(owner=owner, title=title, due=due)

Compare this to the mud-ball: the same if statements, but now they live in a class with no HTTP and no SQL in sight. That has two consequences worth dwelling on. First, every front door gets the rules for free—the web API, a future CLI, the Discord bot all call svc.create_task(...); the 20-task cap cannot be bypassed by coming in through a different entrance. Second—the payoff the reference outline calls “easier testing”—the rules are now testable in microseconds (The Payoff: Testing Each Layer in Isolation).

10.5.3 Data access layer (repository)🔗

Responsibility: all communication with the database—SQL queries, ORM operations, mapping rows to domain objects. Nothing else: no policies, no HTTP.

# app/repositories.py (excerpt) -- speaks SQL, hides it from everyone above
class SqliteTaskRepository:
    def count_open(self, owner: str) -> int:
        row = self.conn.execute(
            "SELECT COUNT(*) FROM tasks WHERE owner = ? AND done = 0",
            (owner,),                      # parameterized: injection-safe
        ).fetchone()
        return row[0]

The interface the service sees (count_open, add, get, complete) is written in domain vocabulary; the SQL is an implementation detail behind it. Swap in PostgresTaskRepository or the database lecture’s SQLAlchemy crud.py, and the service cannot tell the difference—that is the maintainability claim (“database changes usually affect only the data layer”) made concrete. In the mini-project the interface is a Protocol, so the swap is checked by types, not hope.

10.5.4 Database layer🔗

Responsibility: durable storage and integrity—PostgreSQL, MySQL, SQLite, MongoDB. Everything from the Relational Database Design & MySQL lecture is this layer: schema, constraints, transactions. One clarification the stack diagram invites: constraints living “down here” is not a violation of “rules live in the service.” The service enforces policies (a cap of 20 is a choice); the database enforces invariants (a task must have an owner—true in every possible application). When in doubt: if the rule could plausibly change next semester, it’s service; if violating it means the data is corrupt, it’s schema.

10.7.1 Performance overhead🔗

Every request traverses every layer—UI → Service → Repository → Database—even trivial ones. A health-check endpoint pays four function calls and two translations to return "ok". In-process, this is nanoseconds and almost never matters; what does bite is each layer naively adding its own query (the N+1 problem from the database lecture can hide between layers, where no single layer sees the whole flow). Measure before blaming the pattern—but know the cost is real.

10.7.2 Rigidity: one feature, four files🔗

Add a “priority” field end-to-end and you will touch the schema, the repository, the service, and the API schema—four edits for one concept. That’s the price of separation, and on a small CRUD app it can feel like ceremony. It is also, note, exactly the shape the The Elephant-Goldfish Model design doc’s “every single file” list captures—layered systems make that list predictable, which is why agents work well in them.

10.7.3 Pass-through code (the real disease)🔗

The most common degeneration: layers that merely forward.

# services.py -- adding nothing
def get_task(self, task_id):
    return self.repo.get(task_id)      # no rule, no translation, no check

When most of a service looks like this, the middle layer is dead weight—every change costs a stop at a station where nothing happens. Two honest responses: (a) accept modest pass-through as the reserved seat for rules that are coming (our get_task will soon check rule 3—visibility); (b) if a system is pure CRUD with genuinely no rules, admit it and collapse a layer. The unforgivable option is ritual: layers maintained because the diagram says so. Architecture is a tool, not a liturgy.

10.7.4 When to use it (and not)🔗

Use layered architecture when: building CRUD-plus-rules applications (the vast majority of business software—student information systems, banking, e-commerce backends, hospital systems); the team is small; requirements are understood; you’re teaching or learning fundamentals. Reach elsewhere when: components must scale/deploy independently (→ microservices), the domain is deeply event-shaped (→ event-driven), or the business core must be fanatically isolated from frameworks (→ hexagonal/clean, below).

10.10.1 Basic🔗

1. E1. Take mudball.py and highlight each line with P (presentation), S (service), R (repository), or D (database). Which lines carry two letters at once? Those are the coupling points.

2. E2. For each snippet, name the layer it belongs in—and the layer it’s probably in when found in the wild: (a) raise HTTPException(404); (b) SELECT COUNT(*) ...; (c) if user.role != "admin": raise NotAllowed; (d) CHECK (length(title) > 0); (e) converting a Task to JSON.

3. E3. Draw the request trace for PATCH /v1/tasks/7/completion sent by bob for a task owned by alice, showing exactly which layer stops the request and what crosses each boundary on the way back up.

4. E4. State the dependency rule. Then explain which rule is violated (and why it matters) if: (a) services.py imports HTTPException; (b) repositories.py imports MAX_OPEN_TASKS; (c) api.py opens a sqlite3.connect(...).

5. E5. Why does test_twenty_first_open_task_is_rejected need no database, and what specifically about mudball.py makes the equivalent test there require one?

10.10.2 Intermediate🔗

1. E6. Finish the refactor: mudball.py also had a GET /tasks?owner=... listing endpoint (write it if missing). Move it through all four layers—repository method, service method (rule 3: only your own tasks), route—with one unit test and one contract test.

2. E7. Add rule 4: a task may not be completed before its due date minus 30 days (no completing December tasks in July—this is a procrastination app with standards). Implement it touching exactly one file, and write down which file. Then add the test. What does the one-file answer tell you about where the boundaries are?

3. E8. Write PostgresTaskRepository (or reuse the database lecture’s SQLAlchemy crud.py behind an adapter) satisfying the TaskRepository protocol. The graded criterion: both test files pass unchanged with the new repository wired into main.py.

4. E9. Add a second front door: cli.py, a command-line interface (python -m app.cli add "study" 2099-01-01 –user alice) that calls TaskService directly. Demonstrate that the 20-task cap holds from the CLI without writing any new rule code—then write one paragraph on what this proves about the service layer.

5. E10. Introduce a deliberate pass-through: add services.get_open_count(owner) that just calls the repo. Now argue both sides in a short design memo: keep it (reserved seat) or let the API call repo.count_open directly (skip a layer)? Cite the trade-offs section, pick a side, and state the rule your team would adopt.

10.10.3 Advanced🔗

1. E11. Rotate to hexagonal. Invert the remaining arrow: move TaskRepository (the Protocol) into domain.py, make repositories.py import from the domain, and add a second adapter—JsonFileTaskRepository. Draw before/after dependency diagrams and explain, in terms of the comparison table, what just became possible that wasn’t before.

2. E12. Layer-violation linter. Write a script (or Claude Code slash command + CI job, per the (part "Claude Code Files") lecture) that fails the build if forbidden vocabulary crosses layers: HTTPException|status_code in services.py/repositories.py, sqlite3|SELECT|INSERT outside repositories.py, import app.api anywhere below the presentation layer. Run it on mudball.py and count the violations.

3. E13. The architecture review, EGM-style. Write the four-section design doc (The Elephant-Goldfish Model lecture) for migrating terptasks-layered to hexagonal architecture, including the Alternatives section arguing why you did not choose microservices or event-driven for a campus task app. Goldfish-test the doc; deliver the doc plus the critic’s findings.

10.11.1 Key takeaways🔗

1. Layered architecture = one responsibility per layer + the dependency rule (talk only downward, one layer at a time). The folders are cosmetic; the rule is the pattern.

2. The four layers answer “where does this code go?”—HTTP at the top, rules in the middle, SQL below, storage at the bottom. Vocabulary is the violation detector: a word from another layer’s language is misplaced code.

3. Boundaries are replaceability contracts. Swap SQLite for PostgreSQL, add a CLI beside the API, hand tests a fake—each swap exercises a boundary, and each is impossible in the mud-ball.

4. The testing pyramid falls out of the layers: many microsecond unit tests against fakes for the rules; fewer full-stack contract tests for the translation. Testability is a property of where the boundaries are.

5. The costs are real: per-request overhead, four-files-per-feature rigidity, and the pass-through disease. Layers are a tool, not a liturgy—collapse one when it provably adds nothing.

6. Policies vs. invariants: rules that could change live in the service; truths that make data valid live in the schema. Both are “business logic”; they have different homes.

7. Know the neighborhood: MVC organizes presentation’s interior; microservices distribute; hexagonal/clean invert the data-layer arrow. A repository interface is your first step on that road.

10.11.2 Terminology🔗

10.11.3 Common mistakes🔗

• SQL in route handlers; HTTPException in services (vocabulary leaks).

• Mistaking folders for architecture while dependencies still tangle.

• Testing business rules only through HTTP + database (slow, flaky, and it means the rules have no callable name).

• Letting every service method become pass-through and defending the layer as ritual.

• Duplicating rules in each front door instead of sharing the service.

• Putting changeable policy in schema constraints, or data invariants only in Python.

• “Fixing” a code-organization problem with microservices (tiers ≠ layers).

10.11.4 Connections🔗

• Backward: this lecture names what the FastAPI (presentation), (part "REST APIs") (the contract), and Relational Database Design & MySQL (data access + storage) lectures built; the E8 wiring exercise was the boundary payoff in advance; fakes-over-interfaces is the testing lecture’s dependency-injection theme grown up.

• Forward: the OWASP notes’ access-control flaws are usually misplaced-layer bugs (authorization in the UI instead of the service); hexagonal/clean architecture radicalize today’s dependency rule; and for AI-assisted work, layered systems are what make the The Elephant-Goldfish Model “every single file” implementation lists short, predictable, and safe to hand to an agent.