Modules of the model
Summary. A module divides one model into parts that a reader opens separately. It is not a
sub-context: a part with a language of its own is a bounded context; a part
of one model, with the same language, the same database schema and the same transactions, is a
module (Evans, Domain-Driven Design Reference, "Modules"). In this kit a module is optional:
one folder of a context holding its own layers (<module>/domain/, <module>/application/,
<module>/infrastructure/, <module>/presentation/) and its own tests (<module>/test/), declared
in the config, named with terms of the glossary, with the role folders unchanged below each layer.
Once a context declares modules, no layer folder stays at its root beside them, and what belongs
to no module has one place, its shared/ folder. Three rules keep it
honest (module/declared, module/complete, module/no-cycle), generate --module writes into
it, and move-to-module moves an existing context into modules one commit at a time.
A module, not a sub-context
Section titled “A module, not a sub-context”A context grows. Either its glossary splits into two vocabularies, and it is two contexts, or the language stays one and the model is simply large. The second case has a name in the references, and it is not "sub-context": no reference publication nests bounded contexts.
| Pattern (Evans, DDD Reference, 2015) | What the text says | What it gives here |
|---|---|---|
| Modules | "Choose modules that tell the story of the system and contain a cohesive set of concepts. Give the modules names that become part of the ubiquitous language. Modules are part of the model." | the division inside one model, named in its language |
| Modules | "This often yields low coupling between modules, but if it doesn't look for a way to change the model to disentangle the concepts, or an overlooked concept that might be the basis of a module." | coupling between modules is a signal about the model, not a metric to obey |
| Generic Subdomains | "Factor out generic models of these subdomains and place them in separate modules." | a subdomain can live in a module of a context |
| Abstract Core | "Place this abstract overall model in its own module, while the specialized, detailed implementation classes are left in their own modules defined by subdomain." | modules defined by subdomain |
| Evolving Order | "It is best not to shoot for comprehensiveness, but rather to find a minimal set that solves the problems that have emerged. Less is more." | the reason modules are optional and stop at one level |
So a module answers "this context is too big to read", never "these two parts speak different languages". Two parts that need each other but speak one language are one context divided into modules; two parts with two languages are two contexts, and the cycle between contexts guide says how to break their cycle.
What it gains, and what it does not
Section titled “What it gains, and what it does not”The gains.
- Read by concept first. A folder holds one part of the model: everything about the
waitlist, its model, its use cases, its adapters and its routes, and its specs, is under
waitlist/, not spread over ten role folders shared with everything else. These are the "modules that tell the story of the system". - A step between one big context and two contexts. Before modules, a context too big to hold in mind had two ways out: stay big, or split into two contexts and pay integration events, an outbox, eventual consistency and, when they need each other, a refused cycle. A module keeps the language, the schema and the transaction, and costs one folder.
- A smaller unit to load. A person or a coding agent working on the waitlist reads one module and the context-level files, not the whole context.
- Coupling made visible.
module/no-cyclewarns when two modules import each other: the signal Evans names to look for a better model or a missing concept.
The limits, said plainly.
- A module does not reduce the dependencies of a handler. A handler whose constructor takes too many ports has them whatever folder it sits in: see A handler with many dependencies.
- A module guarantees nothing about readability by itself. A cut by technique (
shared,core,common) makes a context harder to read, not easier. That is whymodule/declaredasks for terms of the glossary and refuses technical words; whether the cut follows the model stays a judgement of people, reviewed by thearchitecture-revieweragent. - One more folder level, and longer imports.
- What belongs to no module has one place, and is read there: the code list and the
permission set at the root of the context, and in its
shared/folder the schema, tables and migrations of its database (one database per context), its route groups, guards and shared shapes (a route group gives a prefix to the routes of a resource, whatever module answers them) and the worlds of its specs.shared/is no module and no bag: it holds nodomain/and noapplication/. A concept two modules need belongs to one of them, or is a module. - "Module" already names other things of the kit:
<context>.module.ts(explicit wiring), the module file of a module of the model that it composes (<module>/<module>.module.ts), andContextModuleof@ddd-ts-kit/di. The pages say "module of the model" wherever they could be confused.
When to divide a context, and when not
Section titled “When to divide a context, and when not”Divide a context into modules when it holds two or more clusters of concepts of the same language that a reader opens separately: the glossary is one table, but its terms gather in groups that rarely meet in one use case.
Do not divide it:
- to hide a second language. If a word changes meaning between the two parts, they are two contexts (Bounded context, the language test).
- to make a cycle between contexts disappear without asking why. Merging two contexts into one with two modules is right only when they share one language; otherwise one direction becomes an event, or a concept is missing.
- while the context is small. Evolving Order: build the structure that solves a problem met, not one that might be needed.
In this kit
Section titled “In this kit”The tree
Section titled “The tree”A module is one folder of the context holding its own layers; below each layer, the role folders of the canonical tree, unchanged.
src/contexts/appointments/ CONTEXT.md one glossary, with a ## Modules section appointments.codes.ts the closed list of the codes of the context appointments.permissions.ts the permission set of the context appointments.declarations.ts generated, at the root as before published-language/ one per context appointments.module.ts explicit style: composes the module files of the modules booking/ booking.module.ts explicit style: what booking registers domain/ aggregates/appointment.aggregate.ts errors/slot-taken.error.ts application/ application.declarations.ts generated, per layer of the module commands/book-appointment/... infrastructure/persistence/knex-appointment.repository.ts presentation/http/appointments/book-appointment/... waitlist/ domain/ aggregates/waitlist.aggregate.ts value-objects/offer.vo.ts application/ commands/join-waitlist/... event-handlers/offer-freed-slot.event-handler.ts infrastructure/persistence/knex-waitlist.repository.ts presentation/http/appointments/join-waitlist/... shared/ what belongs to no module, and nothing else infrastructure/persistence/ the schema, tables and migrations of the context presentation/http/ the route groups, guards/ and shared/ test/ worlds/ the arrangements the specs of several modules share fakes/ builders/ unit/ integration/ of no module: a clock, the spec of a guardEach module holds its tests beside its layers, <module>/test/ with unit/, integration/,
builders/ and fakes/ (left out of the tree above): a part of the model is one folder, its
tests with it, opened, moved and reviewed whole. Fakes and builders follow their subject, not
their use: the builder of an aggregate sits in the module of that aggregate, the fake of a port
or of a repository in the module of that port, whoever uses them.
What never moves into a module: at the root of the context, <context>.codes.ts,
<context>.permissions.ts, <context>.module.ts, the generated <context>.declarations.ts and
<context>.dependencies.ts, CONTEXT.md and published-language/; in shared/, the *.schema.ts
of infrastructure/persistence/ that are no row schema, the route groups
(presentation/http/*.routes.ts), presentation/http/guards/ and presentation/http/shared/, the
worlds, and the fakes, builders and specs that are named after nothing of a module. The config
never declares shared, and no module may be named after it. A module never has a glossary, a
database schema or a published language of its own, and two modules of one context never
exchange integration events: a part that needs one of them is a context.
In the explicit style, what wires the classes splits the same way. Each module has its module
file, <module>/<module>.module.ts, the only file at the root of its folder: it registers the
handlers, consumers, reactions, jobs, permissions and routes of the module, and
<context>.module.ts composes the module files and keeps what the context holds at its own
level. A context with four modules then has five module files of a readable size, not one that
passes the 350 lines of clean/file-size. On tsyringe a module file exports
{ register(builder), onStart({ resolve }) }, called from register and onStart of the
context; wired by hand it exports registerHandlers, registerReactions, registerJobs,
useCases() and routes(platform), called from the functions of the same names. In the
declared style a module has no module file: its classes declare themselves, and each layer of
the module has its generated declarations.
The config and CONTEXT.md
Section titled “The config and CONTEXT.md”"appointments": { "classification": "core", "upstreams": [{ "context": "calendars", "relationship": "published-language" }], "modules": { "booking": {}, "waitlist": { "classification": "supporting" } }}A module may carry the classification of the subdomain it holds (Generic Subdomains, Abstract
Core); without one, it has the classification of its context (CONFIG.md).
CONTEXT.md gains a ## Modules section, after ## Ubiquitous language, with one row per
module:
## Modules
| Module | Purpose ||---|---|| `booking` | Booking, rescheduling and cancelling an appointment, and the rules that keep a slot held once. || `waitlist` | Clients waiting for a taken slot, and the offer made to the first of them when it frees up. |The rules
Section titled “The rules”| Rule | Holds | Severity |
|---|---|---|
tree/closed |
accepts the folder of a declared module at the root of the context, with its layers, its test/ and its module file <module>/<module>.module.ts, nothing else at its root; accepts shared/ in a context that declares modules, closed: infrastructure/persistence/, presentation/http/ with guards/ and shared/, and test/; still reports a folder the config does not declare, with generate module as its fix |
error |
module/declared |
every module of contexts.<name>.modules is named with terms of the glossary of its context (every word of its name; no technical word, common, core, misc, utils and the other technical words of language/no-technical-name) and has a row in ## Modules of CONTEXT.md; the name shared is refused by config/valid, it is the folder of what belongs to no module |
error |
module/complete |
once a context declares modules, a file of a layer left at its level is reported, and so is a file of a module left in shared/, what belongs to no module aside |
warn, so that a context moves into modules one commit at a time; the layout of an earlier version (test/ at the level of the context, a layer folder there with nothing but what shared/ holds now) is an error whatever the severity, and context-layout moves it |
module/no-cycle |
the imports between the modules of one context form no cycle | warn, because Evans makes coupling between modules a signal to change the model, not a refusal |
Every other rule reads a file of a module as it reads the same file outside one: the role of a
file is its path with the module folder left out. npx ddd-ts-kit explain module/no-cycle gives
the reason and an example of each rule.
The generator and the move command
Section titled “The generator and the move command”# Declare the module: config, row of ## Modules, terms of the glossary. Re-runnable.npx ddd-ts-kit generate module appointments waitlist \ --purpose "Clients waiting for a taken slot, and the offer made to the first of them when it frees up." \ --term "Waitlist=The clients waiting for a slot that is taken, in the order they asked"
# Write into it: every file of a layer goes into the module, its spec, builder and fake into <module>/test/.npx ddd-ts-kit generate aggregate appointments Waitlist --module waitlistnpx ddd-ts-kit generate command appointments JoinWaitlist --aggregate Waitlist --permission waitlist.join --module waitlist
# Move what exists, with every import of it in the project and the specs named after it.npx ddd-ts-kit move-to-module appointments booking domain/aggregates/appointment.aggregate.ts application/commands/book-appointment \ infrastructure/persistence/knex-appointment.repository.ts presentation/http/appointments/book-appointment- In the explicit style,
generate modulealso writes the module file of the module,<module>/<module>.module.ts, and composes it from<context>.module.ts. Run again for a module declared before, it adds them and nothing else. A kind run with--modulethen writes its registration in that module file, and in<context>.module.tswhile the module has none. Wired by hand, a use case whose repository another module file already creates is registered in that file, so that a repository is created once per context. Registrations written before the module file existed stay in<context>.module.tsuntil they are moved by hand, with their imports. - With
--module, the files a kind reads (an existing aggregate, an event, a port) are found in whatever module holds them, and the imports it writes name where they are. A file of a use case already in a module is written with it,--moduleor not; a--modulenaming another module is refused, since it would split the use case. A spec, a builder or a fake goes into the test folder of the module of the file it is named after, and intoshared/test/when it is named after nothing of a module. What belongs to no module is written where it lives: the code list and the permission set at the root of the context, the schema of its database, its route groups, guards and shared shapes and its worlds inshared/. - In a context that declares modules, a kind that would write a file of a layer without
--moduleis refused, with the list of the modules and the same command with--module: the generator guides, it never leaves the choice unsaid. A context that still holdstest/at its own level is refused too, withcontext-layoutas the way out. - The kinds that take
--moduleshow[--module <module>]in their usage (npx ddd-ts-kit generate --help --json,writesInModules): the model, the use cases, their routes, ports, adapters, gateways, policies, events and builders. A kind that writes only what belongs to no module or what lies outside the contexts (test-world,route-group,guard,schema,e2e,service,module,context,acceptance,worker,adr) refuses--module, which would have no effect on it. move-to-moduletakes paths relative to the context, files or folders of a role of any layer, specs, fakes or builders, moves them into a declared module (a file of the tests into<module>/test/), takes the specs named after a moved file with it, and rewrites every import of them under the source root,test/andscripts/, and the compiled path a migration names a moved file by; the generated declarations follow in the same run. A path already in a module, or inshared/, moves to the module asked, and every file of a folder moves, not only its sources. Nothing is moved when a file of the same name is in the module already, when two files would land on one path, when another module of the context holds a file of the same role and name (the declarations of the context would export it twice), or when a file is not text.--dry-runshows the plan; the checks and the tests come next.move-to-modulewrites nothing either when the move would close a cycle between modules that is not there now: a module would import another that imports it back, directly or through a third. It reads the imports asmodule/no-cycledoes, before the move and with the move planned, and names the cycle, each step of it with its imports (file and line, the steps the move adds told apart from the ones there now), and the file at the other end of the imports the move adds, to move along in the same command. The rule is a warning, for a cycle someone finds; the command is about to write one on your behalf, into every import of the moved files, so it asks first.--allow-cyclemoves all the same and says the cycle with the move;--dry-runrefuses or shows the same. A cycle there before the move is not counted, and a project that turnsmodule/no-cycleoff is not judged, nor is a cycle whose every import is in a file the config turns the rule off for. The cycle named is the shortest through the dependency the move adds; a file of a use case is named by its folder, an import of a folder by itsindex.ts; and only the filesddd-ts-kit checkreads are read.context-layoutneeds no such refusal: it leaves where it is a file that would make a module depend on another.
What reads the modules
Section titled “What reads the modules”ddd-ts-kit checkand the ESLint plugin read a folder of a context as a module when the config declares it, and so do the generated.dependency-cruiser.cjsand the coverage of@ddd-ts-kit/testing, which holds each layer of each module to its threshold.ddd-ts-kit docs,describe,error-factoriesand the generators read the role folders of every module the config declares, ascheckdoes: the reference ofCONTEXT.mdlists the aggregates, use cases, ports, refusals and jobs of the modules as those of the context. A folder the config does not declare is read by none of them, andtree/closedreports it.error-factorieswrites the class of a concept next to the errors it replaces, in their module; errors of one concept read from two folders are refused untilmove-to-modulegathers them.- In the declared style assembled by barrel, each layer of a module has its generated
<layer>.declarations.ts, re-exported by<context>.declarations.ts. - In the explicit style,
checkreads the module file of a module as a module file of its context (composition/only-in-module,declarations/port-adapter-wired,authz/declared,domain-events/transactional-before-commit), anddescribe,docsand the generators read the registrations of every module file of a context together. discoverContextof@ddd-ts-kit/diruns without the config: it reads the modules in the generated<context>.dependencies.ts, whichddd-ts-kit docswrites with them (export const modules = [...]), and loads the role files of<module>/application/,<module>/infrastructure/and<module>/presentation/. A folder that file does not name is no module at boot either: a role file in it is refused, ascheckreports it.
From a context laid out before its modules held their tests
Section titled “From a context laid out before its modules held their tests”Earlier versions kept the tests of every module in the test folder of the context
(test/unit/<module>/), and its schema, its route groups, its fakes, builders and worlds at the
level of the context. This version reads that layout only to move it: module/complete reports
test/ at the level of the context, and a layer folder there that holds nothing but what
shared/ holds now, as an error whatever its severity, and the generators refuse to write in
such a context until it is moved. npx ddd-ts-kit context-layout [<context>...] [--dry-run]
moves it in one run: the specs of test/<unit|integration>/<module>/ to <module>/test/; each
spec, fake and builder left in the test folders of the context to the module of the file it is
named after (a builder after an aggregate, a fake after a port or a repository), else of the one
module its imports name, else to shared/test/; the schema and tables, the route groups, guards
and shared shapes and the worlds to shared/; every import of them following, the compiled path
a migration names them by included. A file of a layer whose imports name two modules, or none, is
listed and stays where it is: move it with move-to-module. Nothing is overwritten, and a second
run moves nothing. The command names each config of a test runner (vitest.config.ts,
vitest.mutation.config.ts, jest.mutation.config.js) that still globs the integration specs of
the test folder of the contexts alone: add the test folder of their modules beside it, or the
integration specs of a module run with the unit specs.
Adopting modules, step by step
Section titled “Adopting modules, step by step”- Read the glossary. Group its terms by the use cases that use them together. Two groups that rarely meet are two modules; a word with two meanings is two contexts.
- Declare the modules:
generate module <context> <module> --purpose "...", once per module.module/completenow warns about every file of a layer outside a module: that list is the plan. It also reportstest/at the level of the context as an error, and the generators refuse the context until step 4: the context is in the middle of its move, read as it is, its files of a layer where they were. - Move one cluster per commit:
move-to-module <context> <module> <paths>..., its model, its use cases, its adapters and its routes, thennpm run verify. The specs named after the moved files follow them into<module>/test/. A move that would close a cycle between modules is refused with the file to move along: a cluster moves whole. - Lay out what is left:
npx ddd-ts-kit context-layout <context>, once the files of the layers are in their modules, or earlier to generate into a module at once. The fakes and the builders follow their subject into its module, the schema, the route groups and the worlds go toshared/, and what no module is told for goes toshared/test/. Run before step 3, it sends toshared/test/the fakes and builders whose subject is not in a module yet:move-to-moduletakes them later, named one by one. - Read the warnings of
module/no-cycle. A cycle between two modules asks whether a concept is in the wrong module, or whether a concept is missing. - From then on, generate with
--module.
Limits and when not to use it
Section titled “Limits and when not to use it”- The tools check the folders, not the cut.
module/declaredproves that a module is named in the language of its context; it cannot prove that the concepts inside belong together. - No command renames or removes a module. Move its files into another module with
move-to-module, then remove its entry fromcontexts.<name>.modulesand its row from## Modulesby hand. - One level only. A module holds no module. A module that grows too large to read is a question about the context: two contexts, or a concept missing.
- The rules of
module/*are read byddd-ts-kit check. The imports between modules are read at the level of the text, like the rest of the checker. - A small context does not need modules. Most contexts never will.
In the example
Section titled “In the example”examples/scheduling divides its context into two modules: calendars (the calendars and the
appointments they hold) and waitlist. Dividing it showed what module/no-cycle is for: the
calendar built the waiter of the waitlist, and a handler of the calendars both noted an
attendance and offered a freed slot. The calendar now answers the appointment type it offers and
the waitlist builds its waiter; the reaction that offers a freed slot belongs to the waitlist,
the one that notes the attendance to the calendars.
Sources
Section titled “Sources”- Eric Evans, Domain-Driven Design Reference: Definitions and Pattern Summaries, Domain Language, 2015, domainlanguage.com/ddd/reference: Modules, Generic Subdomains, Abstract Core, Segregated Core, Evolving Order.
- Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, Addison-Wesley, 2003, chapter 5 (Modules) and chapter 15 (Distillation).
- Vlad Khononov, Learning Domain-Driven Design, O'Reilly, 2021, chapter 3 (bounded contexts versus subdomains).