When a client's custom work grows past a single feature, a structural question appears: is this one module that contains everything, or several modules that each do one thing. It usually gets answered by whoever set up the repository first, out of habit rather than decision. It deserves a decision, because in Odoo a module is not just a folder. It is the unit of installation, of dependency, and of upgrade. The boundaries you draw between modules are the boundaries along which the system can later move.
The pull toward one big module
One module is simpler to start. One manifest, one folder, no dependency graph to think about, no deciding which half of a feature goes where. For a small, cohesive piece of work that is the right answer, and splitting it would be ceremony. The problem is only what happens as it grows. A single large module becomes all-or-nothing: every install carries everything, every upgrade reloads everything, and a problem in any corner is a problem for the whole. There is no seam to deploy along, because there are no seams.
The pull toward many small modules
Many modules give you seams. A clean split lets one part be installed without the others, upgraded without disturbing the others, and reasoned about on its own. It also forces a discipline: to put two things in separate modules, you have to define how they depend on each other, and defining that is the same act as defining the architecture. The cost is that the seams have to be real. Modules that all depend on each other in a cycle, or are split so finely that no single module is independently meaningful, give you all the overhead of many modules and none of the isolation. A dependency graph that is itself a tangle is worse than one honest large module.
The seam that matters most: the edition boundary
One split is almost always worth making explicitly: anything that depends on Odoo Enterprise features belongs in its own module. A module that depends on an Enterprise-only piece will not install on Community at all. Keeping the Enterprise-coupled code in a separate bridge module means the core stays edition-neutral, and the coupling is visible in the dependency graph instead of hidden inside the code.
How we decide
- Small and cohesive: one module. Do not manufacture seams.
- Distinct features used independently, or shipped to different clients in different combinations: separate modules, with honestly declared dependencies.
- Enterprise-coupled code: its own module, always.
- The test for any proposed split: can each module be described in one sentence, and does it depend on the others in one direction only. If yes, the seam is real. If no, it is just more folders.
The note for the file
Module boundaries are the joints of the system. Too few, and nothing moves independently. Too many, badly placed, and the joints seize. The goal is not small modules or large ones; it is boundaries that match how the system actually needs to change.