ADR-0001: Modular monolith
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”Ochema covers ten functional areas: attract, recruit, compliance, people, fleet, operations, driver, portals, finance and platform. They share the same companies, users, permissions and audit log, and one user action often crosses areas. Hiring a candidate in Recruit creates a person in People and a driver file in Compliance.
How should the back end be split so that the areas stay separate in the code and a cross-area action stays consistent?
Decision drivers
Section titled “Decision drivers”- A write that crosses areas must be atomic.
- The boundaries between areas must be checked by tools, not by convention.
- One deployable unit for the API, with background work running from the same code.
- A company can have an area switched off without a different build.
Considered options
Section titled “Considered options”- Modular monolith: one NestJS application, one module per functional area.
- One service per functional area. Common market alternative, listed for comparison.
- Serverless functions. Excluded by the infrastructure decision of the same date: containers, no function-as-a-service.
Decision outcome
Section titled “Decision outcome”Chosen option: 1, the modular monolith.
apps/api is one NestJS application. Each functional area is a folder in apps/api/src/modules, and what every module needs (database, sessions, audit, errors, storage, events) is the shared kernel in apps/api/src/core. A module imports another module only through its index.ts. The worker is a second process built from the same code: apps/worker hosts the job modules that apps/api/src/worker.ts exports.
The reason is the first driver. Every authenticated request runs in one database transaction that carries the company context (TransactionInterceptor), so a service of one module can call the public interface of another and both writes commit or roll back together. Separate services would turn the same action into a distributed transaction.
Consequences
Section titled “Consequences”- Good, because a cross-module action is one transaction with one audit trail.
- Good, because the boundary is enforced: the lint rule
ochema-api/module-boundaryrejects an import of an internal file of another module, andapps/api/test/module-cycles.test.tsfails on an import cycle between modules. - Good, because the module switch per company is a guard (
ModuleGuard), not a deployment. - Bad, because all modules are deployed and scaled together. A heavy area cannot be scaled alone.
- Bad, because import cycles between modules must be managed by hand. Services used by several modules had to move to modules of their own, see ADR-0027.
More information
Section titled “More information”apps/api/src/app.module.ts: the modules of the API and the global request pipeline.apps/api/src/worker.tsandapps/worker/src/main.ts: the worker process.apps/api/eslint-module-boundary.jsandapps/api/test/lint-boundary.test.ts: the boundary rule and its test.- Building blocks shows the modules and their dependencies.
- Concept pages: Tenant isolation for the transaction of a request, Background work for the worker.
- Related: ADR-0006, ADR-0027.