Deep modules — and why they matter more in the AI era

1 · What is a module?

A module is any chunk of code with a line drawn around it. A file. A folder. A class. A package. A service. A repo. The unit doesn't matter — the line does.

Every module has two parts:

• Interface — the surface other code touches. Function signatures, exported types, public methods, REST endpoints. What a caller has to learn.
• Implementation — everything inside that the caller doesn't have to know. Helpers, internal state, private functions, the actual logic.

The whole point of drawing a line is to declare a contract: "outside this line, you only need to know X. Inside, the complexity is my problem."

2 · Deep vs shallow modules

This is John Ousterhout's framing from A Philosophy of Software Design. Picture a module as a rectangle. The width is the size of its interface — how much a caller has to learn. The depth is how much functionality lives behind it.

• Deep — narrow on top, fat below. One simple call, lots happening inside. Example: Unix read(fd, buf, n). Three arguments. Behind them: filesystem layers, page cache, device drivers, networking. The caller doesn't care.
• Shallow — wide on top, thin below. The interface is almost as complicated as the implementation. Example: an 8-argument wrapper that just forwards to another function. You pay full interface cost for almost no hiding.

The rule: a module earns its keep by hiding more than it exposes. If it doesn't hide much, it's noise — the caller would be better off reading the body inline.

3 · The "cover the body" test

A useful diagnostic: cover the implementation with your hand and read only the interface. Can you predict what it does and what it costs? If yes, the module is deep — the interface communicates the contract. If you have to peek inside to know what's happening, the abstraction is leaky and the module is shallow.

Try it on three real signatures:

// ~190 lines hidden behind 4 exports:
//
//  - PHP-bracket form encoding (the provider accepts form-data, not JSON)
//  - The three-token confusion (processId vs processToken vs authCode,
//    documented with the exact error you'd see if you got it wrong)
//  - Env-based base URL switching (sandbox vs prod)
//  - Non-JSON response handling
//  - Forged-payload protection (NaN > x is always false)
//  - HTTP status surfacing without leaking back into echoed bodies

function buildHeaders(userId, env, contentType, accept, traceId) {
  return {
    "X-User-Id": userId,
    "X-Env": env,
    "Content-Type": contentType,
    "Accept": accept,
    "X-Trace-Id": traceId,
  };
}

// Hidden behind one async generator:
//
//  - Picks the correct system prompt by `kind` (article/podcast/video/transcript/...)
//    using a Record so adding a new kind becomes a compile error, not a silent default
//  - Yields a "chunks" event with citation metadata (slug + title for cross-resource cases)
//  - Yields a "variant" event so the caller can persist which prompt version actually ran
//  - Streams "token" events as the LLM emits chunks
//  - Yields a final "done" event with token-usage totals (nullable when unreported)
//  - Wraps the provider call with retry/backoff on 429s and 5xxs
//  - Defensive precondition: sources must be non-empty (silent empty would hallucinate)

4 · Why the same advice transfers to AI — for different reasons

Ousterhout was writing for humans reading code. His argument was about working memory and cognitive load: a deep module lets a reader page out the implementation and just reason about the interface. That argument still applies — but the AI era adds a separate, sharper one.

Humans and language models have inverted cognitive constraints:

Pocock's framing — "go back to old books" — is correct in outcome but a little misleading in cause. The reasons fundamentals transfer to AI aren't nostalgic. They're different physics, same shape:

• Wide interface ⇒ more bytes for the same operation ⇒ token cost
• Wide interface ⇒ more public API surface ⇒ more chances for the agent to misuse it
• Narrow boundary ⇒ cheap to test from outside ⇒ tight feedback loop
• Narrow boundary ⇒ bounded blast radius when the agent is wrong inside

5 · Pocock's claim, made concrete

Pocock says: "AI is really good at creating codebases like this" — the shallow shape. Why?

• Each turn the agent sees only so much; safer to make small isolated functions
• Fewer interface decisions to commit to
• Pattern-matched to "good code = small functions" from training data
• It's the path of least resistance when you don't have a holistic view

The compounding bit is what hurts: AI both produces shallow structure and fails to navigate shallow structure. Once a codebase tilts shallow, every new feature widens the dependency graph by another fan, and the next agent run gets lost in it.

A worked example

Imagine a content platform with several resource types — articles, podcasts, videos, a cross-resource "library" search. Each type exposes a streaming Q&A endpoint so a user can ask questions about that resource. The routes grew separately, each is ~350 lines, and they look like this:

app/api/articles/ask/route.ts   ~305 lines
app/api/podcasts/ask/route.ts   ~352 lines
app/api/videos/ask/route.ts     ~345 lines
app/api/library/ask/route.ts    ~368 lines
                                ─────────
                                ~1,370 lines

LOC = lines of code. So "352 LOC" just means a 352-line file. You'll see the term in the chart and the before/after tree below.

Two of those (podcasts vs videos) are ~95% identical. Let's prove it.

6 · Side-by-side: two near-identical routes

The diff between the two routes is so narrow it's almost embarrassing. Toggle the highlight modes to see what's identical (the vast majority) vs what genuinely differs (a handful of names).

7 · The lower layers were already deep

Here's what makes this kind of case interesting: the building blocks for a unified shell often already exist. In our example, the Q&A engine in lib/qa/ was already parameterized by content type — router, history loader, answer streamer, index loader all took an indexKey or a kind or a table as input.

// Already deep — content-type-agnostic, called the same way by every route:

routeQuestion(indexKey, question, { promptName })   // returns slugs
loadRoutingIndex(indexKey)                          // returns Index
loadThreadHistory(conversationId, limit, table)     // returns ThreadHistory
streamAnswer(sources, question, { kind, ... })      // yields events

The deep-module engine was right there. Each lower-layer function had a narrow interface and fat insides. So why was the orchestration on top still copy-pasted?

8 · Deep modules at the schema level

The single most important insight in this kind of refactor often isn't in your application code at all — it's in the database. A well-shaped schema can encode the deep-module move at the data layer, and that's what makes the application-level collapse possible:

contentType: text("content_type").notNull()
  // values: "podcast" | "video" | "article" | "interview" | ...

content_id  → content_items.id
text        — the full transcript
language    — locale tag
modelVersion, transcribedAt, costUsd, ...

// One function. Used by podcast routes, video routes,
// and every future transcribed-content route for free.
loadTranscriptSources(contentIds, kindLabel) → AnswerSource[]

9 · "Should I collapse these two functions?"

Walk through the questions. The interactive tree below ends at collapse or keep separate based on real shape, not real-world labels.

• Same shape from the same source? → collapse
• Different storage (e.g. structured documents in object storage with custom markers, vs rows in a relational DB) → keep separate
• Different downstream consumers with different analytics needs (per-type query logs) → keep separate
• "Are they the same kind of thing in the real world?" is the wrong question. Audio vs video is different in real life; their transcripts are not.

10 · The redesign

Here's the new shape. The old four-route layout vs the new shell + thin callers.

What the shell owns

// lib/qa/run-ask-stream.ts (~360 lines)
//
// Owns:
//   • Auth (requireAuth)
//   • Quota (fetchAgentQuota, incrementAgentUsage)
//   • Conversation resolve/create (with ownership check)
//   • History load (loadThreadHistory(conversationId, limit, table))
//   • SSE stream lifecycle (encoder, controller, closeSafely)
//   • Abort handling (req.signal.aborted)
//   • Persist-before-close discipline (the row hits the DB
//     even when the client disconnects mid-stream)
//   • Error mapping
//
// Takes from the caller (the per-type config):
//   • table          — which queries table to log to
//   • plan(question, history) → { sources, selectedContentIds, routerUsage }
//   • resolveScopePin(conversationId, contentId) — per-type pin rule
//   • kindLabel      — for log prefixes
//   • answerKind     — forwarded to streamAnswer
//   • defaultPromptVariant

What a thin caller looks like

// app/api/live/ask/route.ts — 80 lines including imports + zod body
export async function POST(req: Request) {
  const session = await requireAuth();
  const parsed = Body.safeParse(await req.json());
  if (!parsed.success) return Response.json({ error: "invalid_body" }, { status: 400 });
  const { contentId, question, conversationId } = parsed.data;

  return runAskStream(req, {
    session: { userId: session.userId, role: session.role },
    question,
    contentId,
    providedConversationId: conversationId,
    table: liveQueries,
    logPrefix: "live/ask",
    answerKind: "live",
    defaultPromptVariant: PROMPTS.liveAnswer.default,
    async plan() {
      const sources = await loadTranscriptSources([contentId], "Live session");
      return { sources, selectedContentIds: [contentId],
               routerUsage: { inputTokens: null, outputTokens: null } };
    },
    async resolveScopePin(conversationId, requestedContentId) {
      // first prior turn fixes the session id; subsequent turns must match
      ...
    },
  });
}

11 · How LOC grows with content types

The shallow approach scales linearly: each new content type costs another ~350 lines. The deep approach pays a one-time shell cost and then ~80 lines per type. Drag the slider to see how the gap widens.

12 · Path A vs Path B vs Path C

Three reasonable answers to "we want to add a new content type and we have a shallow-orchestration problem." Each has trade-offs.

The right answer in most situations is Path A. Two reasons:

1. The new feature needs to ship. Adding it through the shell gets it out the door and proves the shell shape under one fresh caller.
2. The shell signature is unproven. Migrating four existing routes into an unproven shell would be the bigger bet. The next migration becomes the second caller — still cheap to course-correct if needed.

13 · What stays separate (and why that's part of the design)

A real deep-module move names what it doesn't unify. The honest version of this refactor explicitly excludes a few things, and each exclusion has a reason:

• Loaders for differently-stored content stay separate. Suppose alongside the transcribed-content types there's also a structured documents type — say, long-form books stored as markdown in object storage with custom page markers (e.g. <!-- page N -->). That loader has to parse markers the transcript loader doesn't need to know about. Different storage, different shape, different parsing → forcing it through the shared loader would mean the loader knows about page markers it has no business knowing about.
• Routers with different strategies stay separate. A cross-resource "library" search that has to first pick which book and then which chapter is a two-stage routing problem. A single-resource Q&A endpoint is one-stage. Different routing strategies belong as different functions, not as one "router" with branching internals.
• Per-type query log tables stay separate. podcast_queries, video_queries, live_queries — each has the right fk targets and the right per-type analytics needs. The shell's table parameter accepts any of them; the union of column shapes is named explicitly (call it AskQueriesTable) and only includes the ones that genuinely share a column set.
• Routes whose insert shape really differs stay outside the shell. If one route logs bookSlug + selectedChapterSlugs and another logs contentId + selectedContentIds, those are different schemas. Forcing them through the shell would require the shell to know about books, which defeats the point of a narrow boundary.

14 · The naming move

Folder names are part of the interface — and they're easy to get wrong in a way that compounds. A common pattern: the first surface you build gets a domain-specific folder name (say, lib/articles/), then subsequent surfaces piggyback on the same infrastructure, and the folder name never gets updated. Now the folder says one thing and contains another.

This connects directly to a different Pocock point: ubiquitous language. Names are part of the interface. A wrong name doesn't just look bad — it leaks into how every future contributor and agent thinks about the module. An LLM exploring the codebase will read lib/articles/router.ts and reason about it as "the articles router," not "the generic Q&A router." Every prompt that needs to talk about routing has to first re-establish that the name lies.

lib/articles/   ← misleading (only one of many surfaces uses articles)
  router.ts                (used by ALL Q&A surfaces)
  answer.ts                (used by ALL Q&A surfaces)
  history.ts               (used by ALL Q&A surfaces)
  index-loader.ts          (used by ALL Q&A surfaces)
  sources.ts               (used by ALL Q&A surfaces)

lib/articles/   →    lib/qa/   ← honest

The fix is git mv + a find/replace on imports. Cosmetic at the file level, real at the cognitive level. The trick is sequencing: do the rename after the migrations, not during them.

15 · The lesson, in one breath

Deep modules in the AI era aren't about clever abstraction. They're about drawing the boundary at the place where complexity legitimately differs vs is identical — and being honest about which is which.

The leverage point moves from "writing code" to "drawing the right boundary." That sounds like it should make senior judgment matter less in an AI-assisted workflow. It's the opposite. AI can hand-roll the implementation behind any interface you give it. Choosing the right interface is the part that doesn't automate.

This kind of refactor isn't a clever architectural move. It's three small acts of judgment, in order:

1. Notice that the routes are 95% identical at the orchestration layer.
2. Notice that the lower layers were already deep — the engine exists; only the route shell is leaky.
3. Refuse to unify the routes whose shape really differs, even though the temptation is to pull everything into the shell.

None of those three are mechanical. They're shape-sensing decisions. The mechanical part — writing the 360-line shell, the 80-line new route — is the easy half.