modular-monolith
Designing and enforcing a Modular Monolith in .NET — module anatomy, public Contracts, internal visibility, module registration, synchronous query contracts vs integration events, transactional outbox
SKILL.md.claude/skills/modular-monolith/SKILL.md
GitHubModular Monolith
Module anatomy
{Root}.Modules.{M}.Contracts— public: integration events, exposed query interfaces + DTOs.{Root}.Modules.{M}[.*]— everything else,internalby default (recipe decides project split).{M}Module.cs—Add{M}Module/Map{M}Module/ optionalUse{M}Modulefor background services.- Own
DbContextwithHasDefaultSchema("{db_schema}")and own migrations history table.
Communication — choose per interaction
| Need | Mechanism | Rules |
|---|---|---|
| Read data owned by another module, immediately | query contract (IPartnerLookup) implemented inside the owner |
returns DTOs from Contracts; no IQueryable; cacheable; bulk methods to avoid N+1 |
| React to something that happened | integration event via outbox | publisher does not know consumers; consumers idempotent; at-least-once |
| Command another module to do something now | ⚠️ avoid; prefer event. If unavoidable, command contract in owner's Contracts with explicit ADR | never inside the caller's transaction |
| Show combined data (screens/reports) | composition in the UI/BFF, or Reporting module views | never join schemas in write paths |
Transactional outbox (in-process)
- Aggregate raises domain event → interceptor maps to integration event →
outbox.Messagesrow in the same transaction as the business change. - Dispatcher (hosted service) polls, publishes to in-process bus, marks processed; retries with backoff; poison messages to a dead-letter table with alerting.
- Consumers record
ProcessedEvents(EventId)in their own schema, in the same transaction as their change. - Same contract works with a broker later; only the dispatcher changes.
Data ownership
- One schema per module; the module is the only writer.
- Foreign keys across schemas: no. Store the id; validate via query contract or event-carried state.
- Cross-module reporting: dedicated Reporting module with read-only views/SPs over other schemas, granted SELECT only — recorded as a profile exception with ADR.
Cross-module consistency
No distributed transactions. Use: event → consumer → compensating event on failure (saga in the module that owns the process). Name the process owner explicitly in the ADR.
Enforcement (architecture tests)
- No module references another module's non-Contracts assembly.
- Contracts reference nothing but SharedKernel.
- Public types outside Contracts: only
{M}Moduleextension class. consumesin profile matches actual references (test reads profile.yml).- Each DbContext touches only its schema (test inspects model metadata).
Extraction path to a service (when forces appear)
- Module already communicates only via Contracts + events → replace in-proc bus with broker.
- Replace query contracts with HTTP/gRPC clients implementing the same interfaces.
- Move schema to its own database; Reporting switches from views to event-fed read store. If step 1 is not true, you are not ready — fix boundaries first.
Deeper patterns (sagas, event versioning, module-level auth): references/advanced.md.