[{"_1":2,"_62":-5,"_63":-5},"loaderData",{"_3":4,"_12":13},"routes/_layout",{"_5":6},"pages",[7],{"_8":9,"_10":11},"slug","about","title","What's going on here?","routes/blog/index",{"_14":15,"_45":46,"_47":46,"_48":38,"_49":50,"_61":46},"posts",[16],{"_8":17,"_18":19,"_43":44},"the-modular-monolith-a-practical-middle-ground-you","meta",{"_10":20,"_21":22,"_23":24,"_25":26,"_34":35,"_36":37,"_41":42},"The Modular Monolith: A Practical Middle Ground","description","Why jumping straight to microservices might be unnecessary — and how modular monoliths give us structure without the operational overhead.","date","2026-03-16","keywords",[27,28,29,30,31,32,33],"modular monolith","software architecture","microservices","monolith","domain boundaries","module design","scalability","author","Denys Bashkatov","tags",[38,39,40],"Architecture","JavaScript","Node.js","social",true,"html","

I've watched teams break a perfectly functional application into a dozen services, then spend months debugging issues that did not exist before. Most applications do not need microservices. What they need is structure. A modular monolith provides that without the operational overhead of distributed systems.

What a Modular Monolith Is

A modular monolith is a single deployable application where the code is organized into well-defined, loosely coupled modules — each with clear boundaries, its own internal logic, and explicit interfaces for communication with other modules.

Key properties:

Single deployment unit — one build, one deploy, one runtime
Strong module boundaries — modules cannot reach into each other's internals
Explicit contracts — modules communicate through defined interfaces
Independent data ownership — each module owns its data, even if they share a database

Why Not Microservices

Distributed systems trade one set of problems for a larger, more expensive set:

Network latency between every service call
Distributed transactions
Service discovery and load balancing
Independent deployment pipelines for each service
Monitoring and tracing across service boundaries
Data consistency issues

A modular monolith gives us the organizational benefits — clear ownership, separated concerns, independent development — without the operational complexity.

And here is the part that is easy to miss: a well-structured modular monolith is far easier to split into microservices later than a tangled monolith. We are not closing any doors — we are buying ourselves time to learn where the real boundaries are.

Project Structure

For an e-commerce platform, instead of one flat directory of controllers, services, and models, organize by domain:

src/\n├── modules/\n│   ├── catalog/\n│   │   ├── catalog.module.ts\n│   │   ├── catalog.service.ts\n│   │   ├── catalog.repository.ts\n│   │   └── catalog.types.ts\n│   ├── orders/\n│   │   ├── orders.module.ts\n│   │   ├── orders.service.ts\n│   │   ├── orders.repository.ts\n│   │   └── orders.types.ts\n│   ├── payments/\n│   │   ├── payments.module.ts\n│   │   ├── payments.service.ts\n│   │   ├── payments.repository.ts\n│   │   └── payments.types.ts\n│   └── users/\n│       ├── users.module.ts\n│       ├── users.service.ts\n│       ├── users.repository.ts\n│       └── users.types.ts\n├── shared/\n│   ├── events.ts\n│   └── types.ts\n└── app.ts

Each module exposes a public API and nothing else leaks out.

Enforcing Module Boundaries

Boundaries that are not enforced do not exist. Each module should export only what it wants to expose:

// modules/catalog/catalog.module.ts\n\nimport { CatalogService } from './catalog.service';\nimport { CatalogRepository } from './catalog.repository';\n\nconst repository = new CatalogRepository();\nconst service = new CatalogService(repository);\n\n// This is the public API. Nothing else leaves this module.\nexport const catalogModule = {\n  getProduct: (id: string) => service.getProductById(id),\n  listProducts: (filters: ProductFilters) => service.listProducts(filters),\n  onProductUpdated: service.productUpdatedEvent,\n};\n\nexport type { Product, ProductFilters } from './catalog.types';

The orders module can use catalogModule.getProduct() but cannot import CatalogRepository directly.

We can enforce this with ESLint rules to prevent cross-module internal imports:

// eslint.config.js\nexport default [\n  {\n    rules: {\n      'no-restricted-imports': ['error', {\n        patterns: [\n          {\n            group: ['*/modules/*/!(*.module|*.types)'],\n            message: 'Import from the module file, not internal files.',\n          },\n        ],\n      }],\n    },\n  },\n];

Communication Between Modules

Modules need to communicate. Use direct calls for synchronous queries and events for notifications.

Direct calls for when we need a response:

// modules/orders/orders.service.ts\n\nimport { catalogModule } from '../catalog/catalog.module';\n\nclass OrdersService {\n  async createOrder(userId: string, productId: string, quantity: number) {\n    const product = await catalogModule.getProduct(productId);\n\n    if (!product) {\n      throw new Error(`Product ${productId} not found`);\n    }\n\n    return this.repository.create({\n      userId,\n      productId,\n      quantity,\n      totalPrice: product.price * quantity,\n    });\n  }\n}

Events for when a module needs to notify others without knowing who is listening:

// shared/events.ts\n\ntype EventHandler<T> = (payload: T) => void | Promise<void>;\n\nexport class EventBus {\n  private handlers = new Map<string, EventHandler<any>[]>();\n\n  on<T>(event: string, handler: EventHandler<T>) {\n    const existing = this.handlers.get(event) || [];\n    this.handlers.set(event, [...existing, handler]);\n  }\n\n  async emit<T>(event: string, payload: T) {\n    const handlers = this.handlers.get(event) || [];\n    await Promise.all(handlers.map((h) => h(payload)));\n  }\n}\n\nexport const eventBus = new EventBus();

// modules/orders/orders.service.ts\nimport { eventBus } from '../../shared/events';\n\n// After creating an order:\nawait eventBus.emit('order.created', { orderId, userId, productId, quantity });

// modules/payments/payments.module.ts\nimport { eventBus } from '../../shared/events';\nimport { PaymentsService } from './payments.service';\n\nconst service = new PaymentsService();\n\neventBus.on('order.created', async (order) => {\n  await service.initiatePayment(order);\n});

The orders module does not know that payments is listening. When we eventually need to extract payments into its own service, we swap the in-process event bus for a message broker — the module's internal code does not change.

Data Ownership Without Separate Databases

Use schema separation or table-level ownership rules:

// modules/catalog/catalog.repository.ts\n\nclass CatalogRepository {\n  // This module owns these tables. No other module touches them.\n  private readonly TABLES = {\n    products: 'catalog_products',\n    categories: 'catalog_categories',\n  } as const;\n\n  async getById(id: string): Promise<Product | null> {\n    const row = await db.query(\n      `SELECT * FROM ${this.TABLES.products} WHERE id = $1`,\n      [id]\n    );\n    return row ? this.toProduct(row) : null;\n  }\n}

The convention: prefix tables with the module name. The catalog module owns catalog_* tables, orders owns orders_* tables. If one module needs data from another, it goes through the module's public API — never through a direct database query.

When to Move to Microservices

Legitimate reasons to extract a module into a separate service:

Independent scaling — one module genuinely needs significantly more compute than the rest
Different runtime requirements — a module needs a GPU, a different language, or a different deployment cadence
Team autonomy at scale — there are many engineers and coordination overhead is the bottleneck
Fault isolation — a module's failure is cascading and crashing unrelated functionality

If we have done the modular monolith work, extraction is straightforward. The module already has a defined interface. We put a network boundary where the function call boundary was, swap the event bus for a message queue, and we are most of the way there.

What I'd Recommend

Start with a modular monolith. Be disciplined about boundaries from day one. Use linting and code review to enforce them. Build an event system early — it is cheap and it pays off whether we stay monolithic or not.

Resist the urge to prematurely distribute. Every network hop we add is a new failure mode, a new latency source, and a new thing to monitor. Earn the complexity by proving it is needed.

\n","page",1,"totalPages","tag","allTags",[38,51,52,53,54,39,55,56,40,57,58,59,60],"CSS","Database","Docker","Homelab","Linux","Networking","PostgreSQL","React","TypeScript","Ubuntu","total","actionData","errors"]

Tech Notes

Tech tips and new discoveries