Skip to content

ADR-0001: Modular monolith

  • Status: Accepted
  • Date: 2026-11-12

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?

  • 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.
  1. Modular monolith: one NestJS application, one module per functional area.
  2. One service per functional area. Common market alternative, listed for comparison.
  3. Serverless functions. Excluded by the infrastructure decision of the same date: containers, no function-as-a-service.

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.

  • 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-boundary rejects an import of an internal file of another module, and apps/api/test/module-cycles.test.ts fails 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.
  • apps/api/src/app.module.ts: the modules of the API and the global request pipeline.
  • apps/api/src/worker.ts and apps/worker/src/main.ts: the worker process.
  • apps/api/eslint-module-boundary.js and apps/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.