Codebase Design

Deep Modules

A deep module has a small interface and a lot of implementation. A shallow module has a large interface and little implementation — it passes through without adding leverage.

DEEP (good):                    SHALLOW (avoid):
┌──────────────────────┐        ┌──────────────────────────┐
│  Small Interface     │        │  Large Interface         │
│  Few methods,        │        │  Many methods,           │
│  simple params       │        │  complex params          │
├──────────────────────┤        ├──────────────────────────┤
│                      │        │                          │
│  Deep Implementation │        │  Thin Implementation     │
│  Complex logic       │        │  Just passes through     │
│  hidden inside       │        │                          │
└──────────────────────┘        └──────────────────────────┘

When designing an interface, ask:

• Can I reduce the number of methods?
• Can I simplify the parameters?
• Can I hide more complexity inside?

Vocabulary

Use these exact terms. Do not drift into "component," "service," "API," or "boundary."

The Deletion Test

Imagine deleting the module. If the complexity vanishes — it was a pass-through (shallow, eliminate it). If the complexity reappears across N callers — it earned its keep (deep).

Interface Design

1. Accept dependencies, don't create them. Inject what you need; don't instantiate internally.
2. Return results, don't produce side effects. Functions that return values are easier to test than void methods that mutate state.
3. Small surface area. Fewer methods = fewer tests. Simpler params = simpler test setup.
4. Tests at the seam. Tests exercise the same interface callers use. If you need to mock internals to test, the interface is wrong.

Seam Discipline

• Don't cut a seam until something actually varies across it.
• One concrete implementation = no seam yet. Only introduce abstraction when a second implementation exists or is imminent.
• Adapters describe the role they fill, not what's inside them (e.g. MariaDbTransactionLogDao, not RealTransactionLogDao).