Modular Design Principles

Modular Design Principles

Use this skill when reasoning about structure and boundaries in any codebase. It intentionally avoids framework names, folder conventions, and tooling — map principles to your stack locally.

What to load

---

Layered mental model

• Composition roots (applications, hosts, runners): wire modules together; keep orchestration thin.
• Modules / bounded contexts: cohesive units of behavior and data ownership; each should be understandable and testable on its own.
• Shared kernels (use sparingly): only stable, truly cross-cutting concepts; resist turning them into a grab-bag of “everything everyone needs.”

How you physically lay this out (mono repo, multi repo, packages, libraries) is a delivery choice, not the definition of modularity. The principles below still apply.

---

The ten principles

Principle 8 is often the hardest: ambiguous ownership of data or names is a frequent source of “works until it doesn’t” integration bugs.

For depth (rules for agents + abstract examples per principle), load references/principles.md.

---

Typical violations (stated abstractly)

1. Colliding concepts — the same name or schema for different things in different modules, or duplicate “global” definitions that diverge over time. 2. Reach-through persistence — one module reading or writing another module’s tables, buckets, or documents without going through an agreed contract. 3. Centralized data ownership — a single persistence layer that registers and exposes all stores for all modules, encouraging hidden coupling. 4. Logic at the edge — business rules in transport adapters (HTTP handlers, UI, CLI) instead of domain/application code. 5. Edge talking to storage directly — adapters depending on low-level persistence APIs instead of use cases or application services. 6. Unscoped transactions — writes that span boundaries without clear transaction ownership and failure semantics. 7. Leaky exports — repositories, internal services, or implementation types exposed as the module’s public API. 8. Facades that aren’t thin — “public” entry points that embed querying, mapping, or policy instead of delegating to the right layer inside the module.

---

Creating a bounded context (workflow)

Use when introducing a new cohesive area of the system (greenfield module or extracted domain).

1. Scope and language — Name the context; list core nouns/verbs (ubiquitous language). Reject vague names that collide with other contexts. 2. Responsibilities — What decisions happen only here? What is explicitly out of scope? 3. State ownership — Which facts are authoritative in this context? Where are they stored conceptually (even if storage tech is undecided)? 4. Public contract — Operations and/or events other contexts may use. Version or evolve this contract intentionally. 5. Integrations — For each neighbor: sync call, async message, shared read model, or batch sync? Document consistency (immediate, eventual) and failure behavior. 6. Invariants and lifecycles — What must always be true inside this boundary? What starts/completes a lifecycle? 7. Isolation check — Can you test core behavior without spinning up unrelated contexts (fakes at ports)? 8. Observability — How will you trace a request or job through this context with clear identifiers?

Cross-module interaction (while designing): prefer the minimal contract; define timeouts, retries, idempotency for async; avoid “temporary” direct store access as a shortcut.

---

When to split or merge

Default: fewer boundaries until real pain appears — “flat is often better” than premature fragmentation. Splitting adds coordination, versioning, and operational cost.

Six-criteria test (favor split when several are true)

Cohesion / coupling (qualitative). Favor high cohesion inside a module and low, explicit coupling between modules. If the only motivation is “files got big” or “folder aesthetics,” merge or wait.

When to merge or not split yet

• Boundaries are artificial (same language, same lifecycle, constant cross-calls).
• Splitting would duplicate logic or data without a clear single writer rule.
• Team is not ready to own contracts, versioning, and ops for extra units.

Decision prompts (short)

• Would separation reduce accidental coupling more than it increases coordination cost?
• Is there a natural ubiquitous language boundary, or only a technical seam?

---

Sub-units inside a bounded context

Sometimes one outer boundary is right, but inside it there are named sub-areas (subdomains, feature areas). Principles still apply within the context.

Ownership

• Each sub-unit should own its slice of model and persistence concerns where possible — avoid one mega registration layer that wires every store and repository for every sub-unit in one place (encourages reach-through and hidden coupling).

Cross-sub-unit access

• Prefer internal application APIs or thin internal facades (same context, explicit surface) over peers importing each other’s storage types directly.
• For async flows, prefer enriched payloads so handlers do not chat across sub-units for data that could travel with the event/command.

Shared kernel inside the context

• Small, stable shared types or enums can live in a narrow shared area — but resist a growing “utils” dump that becomes the real coupling point.

Anti-pattern: A single “persistence” or “data” sub-module that becomes the only place that knows about all tables/documents for all sub-units, and everyone else reaches through it — same problems as cross-context reach-through, inside the boundary.

---

Architecture compliance pass

Use for reviews or audits without assuming tooling. Treat items as signals, not proof — confirm with domain experts.

Dependency and API signals

• Inbound vs outbound: Dependencies should align with your chosen architecture (e.g. domain at the center, adapters outside). Inward leaks of infrastructure types into core logic are a smell.
• Public surface: Can you list exported operations/events/types without including storage or internal services? If not, boundaries are leaky.
• Neighbor imports: Types or clients from module A used in module B — are they only contract types, or persistence/implementation types?

Persistence and data signals

• Reach-through: References to another context’s physical data (schema, collection, bucket name) outside an agreed contract.
• Naming collisions: Same logical name for different things, or shared global IDs without a documented mapping rule.
• Transaction ownership: Writes that span contexts without a clear saga, outbox, or single-owner rule and documented failure cases.

Operational signals

• Blame: Incidents where “we don’t know which module owns this row/behavior” → ownership or observability gap.
• Cascades: One dependency’s slowdown or failure takes down unrelated user journeys → missing timeouts, bulkheads, or degradation paths.

Severity heuristic (for reporting)

Maturity note: Scoring is qualitative unless the team defines numeric gates. Use trends: fewer P0/P1 over time, clearer contracts.

---

Quick checklist (before proposing structure)

• [ ] Public API is minimal; internals are not exported casually.
• [ ] Names and storage ownership are unambiguous per module.
• [ ] No cross-module persistence shortcuts without an explicit contract.
• [ ] Business rules sit behind a clear application/domain layer, not only in adapters.
• [ ] Cross-module calls have explicit failure and timeout behavior.
• [ ] Observability can answer “which module failed and why?” without spelunking.
• [ ] If the context has sub-units: each has clear ownership; no monolithic “registers everything” persistence grab-bag.

---

Relationship to stack-specific skills

When a project has concrete conventions (framework modules, DI, repository patterns, folder layout, codegen, CI checks), prefer those documents for how to implement. Use this skill for why boundaries exist and what good modular design optimizes for — so stack-specific advice stays aligned with the same principles.

Principles in depth

One section per principle: definition, rules for agents, abstract example. No stack or folder assumptions.

---

1 — Well-defined boundaries

Definition. Consumers depend on a small, intentional public surface (operations, events, types that are part of the contract). Everything else is implementation detail.

Rules for agents.

• Prefer extending behavior by adding to the documented API rather than importing internals.
• When suggesting refactors, preserve or shrink the public surface; do not widen it “for convenience.”
• Name things so contract vs internal is obvious in reviews (e.g. “public operation” vs “internal helper” is a conceptual distinction even without tooling).

Abstract example. A “Checkout” context exposes placeOrder(command) and OrderPlaced events. Other contexts must not reach into Checkout’s internal pricing tables; they subscribe to events or call placeOrder, not “update row X.”

---

2 — Composability

Definition. Modules can be assembled in different products or deployments without rewriting their core logic for each combination.

Rules for agents.

• Avoid hidden assumptions like “this only runs when module B is present” unless expressed as an optional integration or plugin contract.
• Configuration and feature flags should not become spaghetti that only one deployment understands.

Abstract example. The same “Inventory” module works in a small CLI tool and a large web app because its contract does not assume a specific UI or host—only the composition root changes.

---

3 — Independence

Definition. Modules do not rely on hidden shared mutable state across boundaries. Tests can run a module with fakes at its edges.

Rules for agents.

• Flag “global singletons” that encode cross-module policy without an explicit contract.
• Prefer passing dependencies explicitly or declared injection over ambient globals for cross-cutting concerns.

Abstract example. Two services in different modules both mutate a process-wide cache keyed by “user id” without coordination → independence is violated; replace with an explicit cache interface owned by one module or a documented shared service.

---

4 — Individual scale

Definition. Throughput, storage, batching, and limits can be tuned per module where needed, without forcing one global setting on everyone.

Rules for agents.

• When performance tuning, ask which bounded context owns the bottleneck; avoid “fixing” by coupling unrelated code paths.
• Suggest per-module quotas, pools, or batch sizes when load profiles differ.

Abstract example. “Search” needs a large read replica and aggressive caching; “Billing” needs strict serial writes. Scaling policies are not identical, and neither module forces the other’s settings.

---

5 — Explicit communication

Definition. All cross-module interaction goes through known contracts: APIs, messages, events, or versioned schemas—not incidental shared files or implicit side channels.

Rules for agents.

• Document inputs, outputs, errors, and versioning for anything that crosses a boundary.
• Discourage “just import this DTO from their package” when that DTO is really an internal persistence shape.

Abstract example. Module A notifies Module B via OrderPlaced { orderId, placedAt } on a bus, not by writing into B’s database “because it’s faster.”

---

6 — Replaceability

Definition. Dependencies on other modules are expressed in terms of interfaces, protocols, or stable contracts so implementations can be swapped or mocked.

Rules for agents.

• At boundaries, prefer narrow interfaces (“payment gateway”, “clock”, “id generator”) over concrete vendor types leaking inward.
• Refactors that pin a module to one technology everywhere should be questioned unless that is a deliberate platform choice.

Abstract example. “Notifications” depends on Notifier with send(recipient, body); email vs SMS vs push is replaceable behind that port.

---

7 — Deployment independence

Definition. Module code does not assume co-location in the same process or release unless that is an explicit architectural decision.

Rules for agents.

• Avoid “call this function directly in their package” as the only integration story when multiple deployments are possible.
• Prefer contracts that work across in-process, out-of-process, or async delivery with minimal change.

Abstract example. The same domain logic can run in a monolith today and behind a message queue tomorrow because interactions were modeled as operations/events, not as hardcoded in-process singletons.

---

8 — State isolation

Definition. Each module owns its authoritative store and naming for its facts. No silent sharing of the same logical data across boundaries without a clear rule (who writes, who reads, how consistency is achieved).

Rules for agents.

• Treat reach-through persistence (reading/writing another module’s store directly) as a design smell unless documented as an exceptional, reviewed pattern.
• Require unambiguous names for persisted concepts when multiple modules have similar nouns.

Abstract example. “Customer” in CRM and “Customer” in Billing are different aggregates with different IDs or explicit mapping—not two modules updating one ambiguous customers row.

---

9 — Observability

Definition. Logs, metrics, traces, and health checks can be attributed to a module (and often a use case) so incidents are diagnosable without reading the whole system.

Rules for agents.

• When adding diagnostics, include context (which operation, which correlation id), not only “error happened.”
• Avoid log lines that cannot be filtered by owning team or subsystem.

Abstract example. A failed payment shows billing.capture span with orderId and clear error code; support does not grep unrelated modules’ noise to find root cause.

---

10 — Fail independence

Definition. Failures are bounded: timeouts, retries with backoff, bulkheads, circuit breaking, idempotency—so one module’s outage does not cascade blindly.

Rules for agents.

• Cross-module calls should have explicit timeout and failure semantics; “hang forever” is a design bug at the boundary.
• Async handlers should be idempotent or deduplicated where duplicates are possible.

Abstract example. When Recommendations is down, Checkout still completes using defaults or a cached tier; the UI degrades instead of blocking purchase.